If you already know Java (or .Net) and perhaps also have used other document databases (or looking for one), but you are new to the InterSystems world, this post should help you.
InterSystems IRIS Cloud Document is a fully managed document database that lets you store JSON documents and query them with familiar SQL syntax, delivered as a cloud service managed by InterSystems.
In this article pair I’ll walk you through:
- Part I - Intro and Quick Tour (this article)
- What is it?
- Spinning up an InterSystems IRIS Cloud Document deployment
- Taking a quick tour of the service via the service UI
- Part II - Sample (Dockerized) Java App (the next article)
- Grabbing the connection details and TLS certificate
- Reviewing a simple Java sample that creates a collection, inserts documents, and queries them
- Setting up and running the Java (Dockerized) end‑to‑end sample
The goal is to give you a smooth “first run” experience.
1. What is InterSystems IRIS Cloud Document?
Cloud Document is a document database service built on top of the InterSystems IRIS data platform, exposed as a managed cloud service. You work with JSON documents stored in Collections, then query them using SQL, or through language‑specific drivers (Java or .NET).
Conceptually:
- A Document is a JSON object or array.
- A Collection is a logical container for documents and gives you APIs for insert/get/update/delete/query.
- Under the hood it’s the same engine that powers other IRIS data services, so you can use SQL to query document data if and when you need it.
2. Spinning up a deployment
You manage Cloud Document through the InterSystems Cloud Services Portal.
High‑level steps:
2.1 Create a deployment
- Log into the Cloud Services Portal.
- [By the way you need a Subscription to the service - but this is outside the scope of this article, as this is more of a commercial topic. For more details you can see our Services page Docs and the related AWS Marketplace service listing page]
- Create a new IRIS Cloud Document deployment.
- Choose region, name, etc., and let the deployment finish provisioning.
For example:
.png)
.png)
.png)
Here's a short video demonstrating this:
3. A quick tour: upload JSON, import into a collection, browse and query
The Cloud Document web console gives you a nice “zero code” way to get familiar with the service. The flow looks like this: upload a JSON file → import it into a collection → browse with the Collection Browser → run some SQL.
You’ll find these pages under your deployment’s web UI; this page from the Docs walks through the same steps.
3.1 Upload a sample JSON file
Create a small colors.json file locally, for example:
In the Cloud Document deployment UI:
- Go to the Add and Manage Files page.
- Use the Upload button and select your
colors.jsonfile.
.png)
The file must have an object or an array at the top level, which our example does.
3.2 Import the JSON into a collection
Now import the uploaded file into a Cloud Document collection:
- Navigate to the Collection Import page in the deployment UI.
- Choose your uploaded
colors.jsonvia Select file. - For Collection, either:
- pick an existing collection, or
- choose (Add new collection) and enter something like
colors.png)
(Here I clicked Preview, which shows the contents, and summarizes that upon import 3 documents will be added)
- Click Import.
The service will parse the JSON and write each object into the colors collection. If your file is large, this may take a bit longer; for three tiny objects it’s almost instant.
You should see a green popup message saying 3 documents:
.png)
[In case you get a red popup message, indicating there was some error, this might be because this is your first import, and the service "backend" is still "warming up". Looking at the network trace you might see something like this:
... https response error StatusCode: 409, RequestID: ... , api error CodeArtifactUserPendingException: ERROR: Lambda is initializing your function. It will be ready to invoke shortly.
And indeed you can ignore this, wait a little, and try again shortly after.]
3.3 Explore the data with the Collection Browser
Once you’ve imported, go to the Collection Browser page and select the colors collection. You should see each document displayed as JSON.
.png)
Things to try:
- Click on individual documents (via the Previous and Next buttons) and inspect their JSON.
- Confirm that all the objects from your file are present.
- Notice that collections are just logical groupings; you can have multiple collections with very different shapes of documents.
This browser is a good way to sanity-check what’s in your deployment without writing any code.
3.4 Run a simple SQL query
Cloud Document documents live in collections, but you can query them via SQL using JSON_TABLE (see Docs) to project JSON data into a tabular shape. In the deployment UI, go to the SQL Query Tools page and run queries such as:
SELECT name, rgb, hex
FROM JSON_TABLE(colors FORMAT COLLECTION).png)
Or for example using more functionality of JSON_TABLE:
SELECT c.name, c.hex
FROM JSON_TABLE( 'colors',
'$[*]' COLUMNS (
name VARCHAR(50) PATH '$.name',
hex VARCHAR(10) PATH '$.hex'
)
) AS c
ORDER BY c.name.png)
That’s the core pattern: load JSON into a collection, browse it as documents, and query it via SQL when you want to slice or join it.
Here's a short video demonstrating this:
Now we can move on to the next article, there we'll review and explain running a Java app, connecting to our Cloud Service, and interacting with it.
.jpg)
Open Exchange.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)
.png)