Skip to main content

Welcome to InterSystems IRIS Cloud Document!

With the InterSystems IRIS® Cloud Document, you can store data in a flexible document database with full cloud support and query it using a familiar SQL syntax.

To query data stored in a relational database, try InterSystems IRIS Cloud SQL.

Using InterSystems IRIS Cloud Document

The following steps outline how to create an InterSystems IRIS Cloud Document deployment:

  1. Go to the InterSystems Cloud Services PortalOpens in a new tab to sign up for a trial or subscription. Select InterSystems Cloud Document from the list of services.

    On the deployment creation page, select the option for Cloud Document and then select a deployment size. If you intend to connect to the deployment from a Java or .NET application, enable external connections. Enter a password to secure your deployment. Choose a cloud provider and give your deployment a name.

    After reviewing your configuration, click Create to create the deployment.

  2. On the Deployments page, see your named deployment appear with a status of “Pending.” After a few minutes, the status of the deployment should change to “Running.”

  3. Select your running deployment to bring up the Deployment Overview page. On this page, you can see the status, details, and metrics of the selected deployment. You can also enable or disable external connections as well as restrict the IP address ranges to further secure your instance.

  4. Add a file to your deployment.

    1. In your deployment, go to the Add and Manage Files page. Log into the deployment using the password you added during deployment creation.

    2. Click the Upload button to add least one JSON file to the deployment. The JSON file must have an array or an object at the top level.

  5. Import a collection.

    1. Go to the Collection Import page to import the contents of the JSON file into a collection, which is a group of documents that share a similar structure.

    2. Use the Select file button to choose the file you just uploaded.

    3. Select the collection you would like to add the data to; to create a new collection, choose (Add a new collection) and enter a name for the collection.

    4. Click Import to begin importing the data into from the file into the collection. This process may take a long time, depending on the size of the file you are importing.

  6. Go to the Collection Browser page. Select the name of your collection from the list and use the Next and Previous buttons to view the contents of the collection. Note that you cannot modify or query a collection from this page.

  7. Go to the SQL Query Tools page. In the SQL Editor, you can write a SQL query that uses the JSON_TABLEOpens in a new tab function to return data from documents stored in the collection. The following example demonstrates a query that returns the number of documents in a collection called MyCollection:

    SELECT COUNT(*) as document_count FROM JSON_TABLE(MyCollection FORMAT COLLECTION)

    To improve the performance of JSON_TABLE, consider defining an index on the collection.

    Note:

    Note that you can only use read-only SQL commands, like SELECT, through the SQL Query Tools page in the Cloud Services Portal. To write or delete data, enable external connections, make an external connection to your application, and execute the desired command from your application.

Congratulations! You have created a deployment and issued a query against a document collection through the Cloud Services Portal. To add more documents, add files to the deployment on the Add and Manage Files page and add the contents of the documents to a collection on the Collection Import.

Make an External Connection

If you have enabled external connections, you can connect your deployment to a Java or .NET application by:

  1. Downloading the InterSystems Cloud Document driver for JavaOpens in a new tab or .NETOpens in a new tab.

  2. Getting the connection information for your deployment from the Deployment Details section of the Overview page in the Portal and confirming that external connections are enabled.

  3. Adding the connection string to your application as described in Connecting Your Application to InterSystems IRIS Cloud DocumentOpens in a new tab.

Once connected, your application can access the data stored in documents hosted in your Cloud Document deployment. The sections below link to more comprehensive documentation for using the Java and .NET drivers with Cloud Document.

Using the Java Driver for Cloud Document Using the .NET Driver for Cloud Document

Indexes on Collections

A collection is a set of similarly structured documents that often queried together. They are analogous to a table schema in a relational database, but are not prescriptive. As a result, documents in a collection do not need to have the exact same set of fields, offering flexibility amongst the contents in the database. Some entries in the collection may contain data in a particular field that does not exist in other entries, without the need to maintain null or empty values. Nonetheless, a collection should contain relatively similar data to take advantage of indexes on common fields.

Creating an index on a field can greatly improve the efficiency of operations issued against the collection, particularly JSON_TABLE. When you create an index on a particular field, documents with the same value for that field are grouped together. Similar to an index on a relational table, an index on a collection reduces the number of documents that a query needs to read when searching for data with a particular value in the field.

To create, delete, or build an index, navigate to the Create Indices page in the Portal. To create an index, select the collection you would like to create the index on, then click the Create Index button. Fill out the form to create the index.

Once you have created an index, you can select it in the Defined Indices list and use the Build Index and Delete Index to build and delete the index, respectively.

Index Options for Collections

You can create three different types of indexes: map, bitmap, and key. The difference between these types are explained below.

Map Index

Each entry in the index contains a key, derived from the field that the index is built on, and points to the documents in the database that share that key. This index is analogous to standard index in Cloud SQL.

Bitmap Index

A bitmap index is similar to a map index, but the pointer to the record is an integer computed using its bit position. In many cases, a bitmap index is more efficient than a map index. This index is analogous to a bitmap index in Cloud SQL.

Key Index

The index key is unique, corresponding with a single document in the database. This index is analogous to defining an index on a relational table with the UNIQUEOpens in a new tab constraint in Cloud SQL.

Learning Resources

FeedbackOpens in a new tab