Developing with the Stargate Document API

Stargate is a data gateway deployed between client applications and a database. The Stargate Document API modifies and queries data stored as unstructured JSON documents in collections. Because the Document API uses schemaless data, no data modeling is required!

If the Document API is used with Apache Cassandra, document indexing is accomplished with Cassandra secondary indexes.

If the Document API is used with DataStax Enterprise, SAI indexing is used. The blog The Stargate Cassandra Documents API describes the underlying structure used to store collections.

Information about namespaces and collections

To use the Document API, you must define a namespace that will store collections. Collections can store either unstructured JSON documents or documents with a defined JSON schema. Documents can themselves hold multiple documents. Multiple collections are contained in a namespace, but a collection cannot be contained in multiple namespaces.

Only namespaces need to be specifically created. Collections are specified when a document is inserted.

Prerequisites

If you’re looking to just get started, you can try DataStax Astra DB and skip the installation steps.

The base URL will be https://DATABASE_ID-REGION.apps.astra.datastax.com/api/rest/v2. See the FAQ to learn where to find your DATABASE_ID and REGION.

  • Install cURL, a utility for running REST, Document, or GraphQL queries on the command line.

  • [Optional] If you prefer, you can use Postman as a client interface for exploring the APIs

    • You will also find links to downloadable collections and environments in Using Postman

  • [Optional] If you going to use the GraphQL API, you will want to use the GraphQL Playground to deploy schema and execute mutations and queries.

  • [Optional] For the REST and Document APIs, you can use the Swagger UI.

  • Install Docker for Desktop

  • Pull a Stargate Docker image

  • Cassandra 4.0

  • Cassandra 3.x

  • DSE 6.8

v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-4_0:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with an Apache Cassandra 4.0 backend.

docker pull stargateio/stargate-4_0:v1.0.57
v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-3_11:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with an Apache Cassandra 3.11 backend.

docker pull stargateio/stargate-3_11:v1.0.57
v2

For Stargate v2, you’ll need to pull an image for coordinator, plus an image for each API that you wish to run: restapi, graphql, and docsapi. The coordinator image contains a Apache Cassandra backend, the Cassandra Query Language (CQL), and the gRPC API.

The following are the commands for each of those images using the tag v2:

docker pull stargateio/coordinator-dse-68:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2
v1

This image contains the Cassandra Query Language (CQL), REST, Document, GraphQL APIs, and GraphQL Playground, along with a DataStax Enterprise 6.8 backend.

docker pull stargateio/stargate-dse-68:v1.0.57
  • Run the Stargate Docker image

  • Cassandra 4.0

  • Cassandra 3.x

  • DSE 6.8

v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_4_0_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate Cassandra instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=4.0 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-4_0:v1.0.57
v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_cass_3_11_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate Cassandra instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=3.11 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-3_11:v1.0.57
v2

Use this docker-compose shell script to start the coordinator and APIs in developer mode. The easiest way to do that is to navigate to the <install_location>/stargate/docker-compose directory, and run the script. You will want to run, for example:

./start_dse_68_dev_mode.sh

This command will start using the latest available coordinator and API images with the v2 tag.

You may also select a specific image tag using the -t <image_tag> option. A list of the available tags for the coordinator can be found here.

v1

Start the Stargate container in developer mode. Developer mode removes the need to set up a separate DSE instance and is meant for development and testing only.

docker run --name stargate \
  -p 8080:8080 \
  -p 8081:8081 \
  -p 8082:8082 \
  -p 127.0.0.1:9042:9042 \
  -d \
  -e CLUSTER_NAME=stargate \
  -e CLUSTER_VERSION=6.8 \
  -e DEVELOPER_MODE=true \
  stargateio/stargate-dse-68:v1.0.57

API reference

If you prefer to learn using a QuickStart, try out the Stargate Document QuickStart. To view the API Reference, see Stargate Document API.

Creating a namespace

In order to use the Document API, you must create the namespace as a container that will store collections, which in turn store documents. Documents can themselves hold multiple documents. Multiple collections are contained in a namespace, but a collection cannot be contained in multiple namespaces.

Only namespaces need to be specifically created. Collections are specified when a document is inserted. An optional setting, replicas, defines the number of data replicas the database will store for the namespace. If no replica is defined, then for a namespace in a single datacenter cluster, the default is 1, and for a multiple-datacenter cluster, the default is 3 for each datacenter.

Simple namespace

Send a POST request to /v2/schemas/namespaces. In this example we use test for the name, and no replicas setting, to default to 1. docs/build/stargate/stargate/develop/api-doc/doc-creating-namespace.html

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/schemas/namespaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "test"
}'
curl --location --request POST 'http://localhost:8082/v2/schemas/namespaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "test"
}'
{"name":"test"}

The generated authorization token and the content type are passed with --header. The token must be identified as X-Cassandra-Token so that cluster recognizes the token and its value. The specified name for the namespace is passed as JSON data using --data.

cURL can use any of the shortcut or longhand flags:

Shortcut Longhand Example Description

-L

--location

-L http://localhost:8082

Retrieves the URL listed, even if it has moved

-X

--request

-X PUT

Defines the type of REST operation, such as POST, GET, and DELETE

-H

'--header'

'-H "X-Cassandra-Token: $AUTH_TOKEN"'

Passes header information, such as auth tokens and the content type

'-d'

'--data'

-d '{ "name": "test", "replicas": 1 }'

Passes data as part of the request body

'-g'

'--globoff'

No argument

The -globoff flag switches off the URL globbing parser, and you can specify URLs that contain the characters {}[] without having curl interpret them. This option is handy for making the URLs for Document API calls cleaner to read, with less escaping.

Set replicas in simple namespace

To set the replicas, send a POST request to /v2/schemas/namespaces. In this example we use test for the name, and 2 for the number of data replicas.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/schemas/namespaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "test",
    "replicas": 2
}'
curl --location --request POST 'http://localhost:8082/v2/schemas/namespaces' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
    "name": "test",
    "replicas": 2
}'
{"name":"test"}

Namespace for multiple datacenters

For a multiple-datacenter cluster, a namespace is defined datacenters. Send a POST request to /v2/schemas/namespaces. In this example we use myworld-dcs for the name, the datacenters are dc1 and dc2, where dc1 defaults to 3 replicas and dc2 is set to 5 replicas.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L -X POST 'http://localhost:8180/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "test-dcs",
    "datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'
curl -L -X POST 'http://localhost:8082/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json' \
-d '{
    "name": "test-dcs",
    "datacenters": [ {"name": "dc1"}, {"name": "dc2", "replicas": 5} ]
}'
{"name":"test"}

Checking namespace existence

To check if namespaces exist, execute a Document API query with cURL to find all the namespaces:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L -X GET 'http://localhost:8180/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
curl -L -X GET 'http://localhost:8082/v2/schemas/namespaces' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
{
  "data": [
    {
      "name": "system_schema"
    },
    {
      "name": "system"
    },
    {
      "name": "system_auth"
    },
    {
      "name": "system_distributed"
    },
    {
      "name": "system_traces"
    },
    {
      "name": "stargate_system"
    },
    {
      "name": "data_endpoint_auth"
    },
    {
      "name": "test"
    }
  ]
}

To get a particular namespace, specify the namespace in the URL:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -X GET 'http://localhost:8180/v2/schemas/namespaces/test' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -X GET 'http://localhost:8082/v2/schemas/namespaces/test' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "data": {
    "name": "test"
  }
}

Deleting a namespace

Send a DELETE request to /v2/schemas/namespaces/{namespace_name} to delete a namespace. All collections and documents will be deleted along with the namespace.

  • cURL command (/v2)

  • cURL command (/v1)

curl -L -X DELETE 'http://localhost:8180/v2/schemas/namespaces/test' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L -X DELETE 'http://localhost:8082/v2/schemas/namespaces/test' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
Deletions do not return any data.

Creating a collection

In the Document API, collections are created in a {glossary_url}gloss_namespace.html[namespace]. Collections store documents. Multiple collections are contained in a namespace, but a collection cannot be contained in multiple namespaces.

Only namespaces need to be specifically created. Collections can be created either as an empty collection first, or created with the first document creation in a collection.

Creating an empty collection

Send a POST request to /v2/namespaces. In this example we use library for the name.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location \
--request POST 'http://localhost:8180/v2/namespaces/test/collections' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "name": "library"
}'
curl --location \
--request POST 'http://localhost:8082/v2/namespaces/test/collections' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "name": "library"
}'
No return

The generated authorization token and the content type are passed with --header. The token must be identified as X-Cassandra-Token so that cluster recognizes the token and its value. The specified name for the namespace is passed as JSON data using --data.

cURL can use any of the shortcut or longhand flags:

Shortcut Longhand Example Description

-L

--location

-L http://localhost:8082

Retrieves the URL listed, even if it has moved

-X

--request

-X PUT

Defines the type of REST operation, such as POST, GET, and DELETE

-H

'--header'

'-H "X-Cassandra-Token: $AUTH_TOKEN"'

Passes header information, such as auth tokens and the content type

'-d'

'--data'

-d '{ "name": "test", "replicas": 1 }'

Passes data as part of the request body

'-g'

'--globoff'

No argument

The -globoff flag switches off the URL globbing parser, and you can specify URLs that contain the characters {}[] without having curl interpret them. This option is handy for making the URLs for Document API calls cleaner to read, with less escaping.

Add JSON schema to a collection

To set JSON schema that a collection’s documents will use, send a PUT request to /v2/namespaces/test/collections/library. In this example, a collection is created to store a Person object that has three properties: first name, last name, and age:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PUT 'http://localhost:8180/v2/namespaces/test/collections/library2/json-schema' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person'\''s first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person'\''s last name."
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    }
  }
}
'
curl --location --request PUT 'http://localhost:8082/v2/namespaces/test/collections/library2/json-schema' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '{
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person'\''s first name."
    },
    "lastName": {
      "type": "string",
      "description": "The person'\''s last name."
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    }
  }
}
'
{
  "schema": {
    "title": "Person",
    "type": "object",
    "properties": {
      "firstName": {
        "type": "string",
        "description": "The person's first name."
      },
      "lastName": {
        "type": "string",
        "description": "The person's last name."
      },
      "age": {
        "description": "Age in years which must be equal to or greater than zero.",
        "type": "integer",
        "minimum": 0
      }
    }
  }
}

JSON schema support is experimental. Also, partial updates of data are not allowed if JSON schema is defined.

Checking collection existence

To check if a collection exists, execute a GET request to find all the collections:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L -X GET 'http://localhost:8180/v2/namespaces/test/collections' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
curl -L -X GET 'http://localhost:8082/v2/namespaces/test/collections' \
-H "X-Cassandra-Token: $AUTH_TOKEN" \
-H 'Content-Type: application/json'
{
  "data": [
    {
      "name": "library",
      "upgradeAvailable": false
    },
    {
      "name": "library2",
      "upgradeAvailable": false
    }
  ]
}

Deleting a collection

Send a DELETE request to /v2/schemas/namespaces/test/collections/library to delete a namespace. All documents will be deleted along with the collection:

  • cURL command (/v2)

  • cURL command (/v1)

curl -L \
-X DELETE 'http://localhost:8180/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X DELETE 'http://localhost:8082/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
Deletions do not return any data.

Writing documents

All data written with the Document API is stored as JSON documents stored in collections.

The maximum size of a document is 1 MB.

A few terms will help your understanding as you prepare to write and read documents:

document-id

An ID that you can either assign as a string when creating a document, or a random UUID that is assigned if an ID is not assigned during document creation.

document-path

An endpoint (resource) that exposes your API, such as /book or /book/genre.

operation

An HTTP method used to manipulate the path, such as GET, POST, or DELETE.

For more information about the database design of the Document API, see the blog post on the Documents API.

Add document with a document-id

First, let’s add a document to a specified collection using a document-id. If a document-id is specified, a PUT request is required, rather than a POST request. The document-id can be any string. Send a PUT request to /v2/namespaces/{namespace_name}/collections/{collection_name}/{document-id} to add data to the collection library. The data is passed in the JSON body.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location \
--request PUT 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "stuff": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "other": "I need a document with a set value for a test."
}'
curl --location \
--request PUT 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "stuff": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "other": "I need a document with a set value for a test."
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311"
}

Notice that the document-id is returned.

Add a document without a document-id

Suppose you want each document to be assigned a random UUID. Send a POST request to /v2/namespaces/{namespace_name}/collections/{collections_name} to add data to the collection library. The data is passed in the JSON body.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location \
--request POST 'http://localhost:8180/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "some-stuff",
  "other": "This is nonsensical stuff."
}'
curl --location \
--request POST 'http://localhost:8082/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
  "id": "some-stuff",
  "other": "This is nonsensical stuff."
}'
{
  "documentId": "0c88a952-ea0b-4000-83ba-57d293b8e345"
}

Notice that the document-id returned is a UUID if not specified, by default.

Add a document with data

Documents can be added with varying JSON data, unless a JSON schema is specified. Send a POST request to /v2/namespaces/{namespace_name}/collections/{collections_name} similar to the last example, but add more JSON data to the body of the request:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
    "reader": {
       "name": "Amy Smith",
       "user_id": "12345",
       "birthdate": "10-01-1980",
       "email": {
           "primary": "asmith@gmail.com",
           "secondary": "amyispolite@aol.com"
       },
       "address": {
           "primary": {
               "street": "200 Antigone St",
               "city": "Nevertown",
               "state": "MA",
               "zip-code": 55555
           },
           "secondary": {
               "street": "850 2nd St",
               "city": "Evertown",
               "state": "MA",
               "zip-code": 55556
           }
       },
       "reviews": [
           {
               "book-title": "Moby Dick", 
               "rating": 4, 
               "review-date": "04-25-2002",
               "comment": "It was better than I thought."
           },
           {
               "book-title": "Pride and Prejudice", 
               "rating": 2, 
               "review-date": "12-02-2002",
               "comment": "It was just like the movie."
           }
       ]
    }
}'
curl --location --request POST 'http://localhost:8082/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
    "reader": {
       "name": "Amy Smith",
       "user_id": "12345",
       "birthdate": "10-01-1980",
       "email": {
           "primary": "asmith@gmail.com",
           "secondary": "amyispolite@aol.com"
       },
       "address": {
           "primary": {
               "street": "200 Antigone St",
               "city": "Nevertown",
               "state": "MA",
               "zip-code": 55555
           },
           "secondary": {
               "street": "850 2nd St",
               "city": "Evertown",
               "state": "MA",
               "zip-code": 55556
           }
       },
       "reviews": [
           {
               "book-title": "Moby Dick", 
               "rating": 4, 
               "review-date": "04-25-2002",
               "comment": "It was better than I thought."
           },
           {
               "book-title": "Pride and Prejudice", 
               "rating": 2, 
               "review-date": "12-02-2002",
               "comment": "It was just like the movie."
           }
       ]
    }
}'
{
  "documentId": "9a47dcbc-2a41-429e-bd1b-fad26ac23b00"
}

Note the difference between using POST and PUT. The POST request is used to insert new documents when you want the system to auto-generate the document-dd. The PUT request is used to insert a new document when you want to specify the document-id. These commands can also be used to update existing documents.

A 'PATCH' request using a document-id will replace the targeted data in a JSON object contained in the document. JSON objects are delimited by { } in the data. If you have an array, delimited by '[ ]' in the JSON object targeted, or a scalar value, the values will be overwritten.

Add another document (used in examples)

This document insertion is used in later examples. It is a PUT request:

Click to hide code
  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PUT 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '     {
        "book": {
            "title": "Native Son",
            "isbn": "12322",
            "author": [
                "Richard Wright"
            ],
            "pub-year": 1930,
            "genre": [
                "poverty",
                "action"
            ],
            "format": [
                "hardback",
                "paperback",
                "epub"
            ],
            "languages": [
                "English",
                "German",
                "French"
            ]
        }
    }
'
curl --location --request PUT 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '     {
        "book": {
            "title": "Native Son",
            "isbn": "12322",
            "author": [
                "Richard Wright"
            ],
            "pub-year": 1930,
            "genre": [
                "poverty",
                "action"
            ],
            "format": [
                "hardback",
                "paperback",
                "epub"
            ],
            "languages": [
                "English",
                "German",
                "French"
            ]
        }
    }
'
{
  "documentId": "native-son-doc-id"
}

Check a document with GET request

You are probably wondering how you get data back from a document. Let’s read the data from the last example with a GET request:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "native-son-doc-id",
  "data": {
    "book": {
      "author": [
        "Richard Wright"
      ],
      "format": [
        "hardback",
        "paperback",
        "epub"
      ],
      "genre": [
        "slavery",
        "action"
      ],
      "isbn": "12322",
      "languages": [
        "English",
        "German",
        "French"
      ],
      "pub-year": 1930,
      "title": "Native Son"
    }
  }
}

Add documents in a BATCH

It is often convenient to insert several documents into a collection with one request. The Document API has an endpoint that allows for batches of JSON documents to be inserted into the same collection. Data sent to the endpoint /v2/namespaces/{namespace_name}/collections/{collection_name}/batch is expected to be in JSON lines format (1 document per line). This feature was added with https://github.com/stargate/stargate/pull/1043.

More advanced use of batch

Additionally, you can supply an id-path query parameter to use the value at a particular path in each document as the document’s key in the database. So if all your documents have an id field, you could set id-path=id and treat the value in id as the document’s key. You can also use any valid path syntax (globs not allowed), e.g. id-path=user.emails.[0].id.

If id-path is excluded, random UUIDs will be assigned to every document, and the response will have the document-ids created corresponding in the same order as the documents were supplied in.

Click to hide code
  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/namespaces/test/collections/library/batch' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' [{
     "reader": {
        "name": "Jane Doe",
        "user_id": "12345",
        "birthdate": "10-01-1980",
        "email": {
            "primary": "jdoe@gmail.com",
            "secondary": "jane.doe@aol.com"
        },
        "address": {
            "primary": {
                "street": "100 Main St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55555
            },
            "secondary": {
                "street": "850 2nd St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55556
            }
        },
        "reviews": [
            {
                "book-title": "Moby Dick", 
                "rating": 3, 
                "review-date": "02-02-2002",
                "comment": "It was okay."
            },
            {
                "book-title": "Pride and Prejudice", 
                "rating": 5, 
                "review-date": "03-02-2002",
                "comment": "It was a wonderful book! I loved reading it."
            }
        ]
     }
  },
  {
    "reader": {
       "name": "John Jones",
       "user_id": "54321",
       "birthdate": "06-11-2000",
       "email": {
           "primary": "jjones@gmail.com",
           "secondary": "johnnyj@aol.com"
       },
       "address": {
           "primary": {
               "street": "4593 Webster Ave",
               "city": "Paradise",
               "state": "CA",
               "zip-code": 95534
           }
       },
       "reviews": [
           {
               "book-title": "Moby Dick", 
               "rating": 2, 
               "review-date": "03-15-2020",
               "comment": "Boring book that I had to read for class."
           },
           {
               "book-title": "Pride and Prejudice", 
               "rating": 2, 
               "review-date": "0-02-2020",
               "comment": "Another boring book."
           }
       ]
    }
}
 ]'
curl --location --request POST 'http://localhost:8082/v2/namespaces/test/collections/library/batch' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' [{
     "reader": {
        "name": "Jane Doe",
        "user_id": "12345",
        "birthdate": "10-01-1980",
        "email": {
            "primary": "jdoe@gmail.com",
            "secondary": "jane.doe@aol.com"
        },
        "address": {
            "primary": {
                "street": "100 Main St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55555
            },
            "secondary": {
                "street": "850 2nd St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55556
            }
        },
        "reviews": [
            {
                "book-title": "Moby Dick", 
                "rating": 3, 
                "review-date": "02-02-2002",
                "comment": "It was okay."
            },
            {
                "book-title": "Pride and Prejudice", 
                "rating": 5, 
                "review-date": "03-02-2002",
                "comment": "It was a wonderful book! I loved reading it."
            }
        ]
     }
  },
  {
    "reader": {
       "name": "John Jones",
       "user_id": "54321",
       "birthdate": "06-11-2000",
       "email": {
           "primary": "jjones@gmail.com",
           "secondary": "johnnyj@aol.com"
       },
       "address": {
           "primary": {
               "street": "4593 Webster Ave",
               "city": "Paradise",
               "state": "CA",
               "zip-code": 95534
           }
       },
       "reviews": [
           {
               "book-title": "Moby Dick", 
               "rating": 2, 
               "review-date": "03-15-2020",
               "comment": "Boring book that I had to read for class."
           },
           {
               "book-title": "Pride and Prejudice", 
               "rating": 2, 
               "review-date": "0-02-2020",
               "comment": "Another boring book."
           }
       ]
    }
}
 ]'
{
  "documentIds": [
    "36614a34-c203-4d9f-a0d8-8fbbd07c18a6",
    "2dc4364c-e64d-4860-8f0a-1b5ca9bd3549"
  ]
}

Add more documents in a BATCH (used in examples)

Click to hide code
  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/namespaces/test/collections/library/batch' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' [{
     "book": {
         "title": "Moby Dick",
         "isbn": "12345",
         "author": [
             "Herman Melville"
         ],
         "pub-year": 1899,
         "genre": [
             "adventure",
             "ocean",
             "action"
         ],
         "format": [
             "hardback",
             "paperback",
             "epub"
         ],
         "languages": [
             "English",
             "German",
             "French"
         ]
     }
    },
 {
     "book": {
         "title": "Pride and Prejudice",
         "isbn": "45674",
         "author": [
             "Jane Austen"
         ],
         "pub-year": 1890,
         "genre": [
             "romance",
             "England",
             "regency"
         ],
         "format": [
             "hardback",
             "paperback",
             "epub"
         ],
         "languages": [
             "English",
             "Japanese",
             "French"
         ]
     }
 },
     {
        "book": {
            "title": "The Art of French Cooking",
            "isbn": "19922",
            "author": [
                "Julia Child",
                "Simone Beck",
                "Louisette Bertholle"
            ],
            "pub-year": 1960,
            "genre": [
                "cooking",
                "French cuisine"
            ],
            "format": [
                "hardback",
                "paperback",
                "epub"
            ],
            "languages": [
                "English",
                "German",
                "French",
                "Belgian"
            ]
        }
    }
]'
curl --location --request POST 'http://localhost:8082/v2/namespaces/test/collections/library/batch' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' [{
     "book": {
         "title": "Moby Dick",
         "isbn": "12345",
         "author": [
             "Herman Melville"
         ],
         "pub-year": 1899,
         "genre": [
             "adventure",
             "ocean",
             "action"
         ],
         "format": [
             "hardback",
             "paperback",
             "epub"
         ],
         "languages": [
             "English",
             "German",
             "French"
         ]
     }
    },
 {
     "book": {
         "title": "Pride and Prejudice",
         "isbn": "45674",
         "author": [
             "Jane Austen"
         ],
         "pub-year": 1890,
         "genre": [
             "romance",
             "England",
             "regency"
         ],
         "format": [
             "hardback",
             "paperback",
             "epub"
         ],
         "languages": [
             "English",
             "Japanese",
             "French"
         ]
     }
 },
     {
        "book": {
            "title": "The Art of French Cooking",
            "isbn": "19922",
            "author": [
                "Julia Child",
                "Simone Beck",
                "Louisette Bertholle"
            ],
            "pub-year": 1960,
            "genre": [
                "cooking",
                "French cuisine"
            ],
            "format": [
                "hardback",
                "paperback",
                "epub"
            ],
            "languages": [
                "English",
                "German",
                "French",
                "Belgian"
            ]
        }
    }
]'
{
  "documentIds": [
    "3d0e2f71-dfe9-4ab3-8099-9ee7acca0b7f",
    "5744a0a9-9aa0-4b56-bcb6-436b63b8cfd6",
    "cd95de08-5732-4f95-9675-efe72cde2594"
  ]
}

Add a reader document with document-id [need in examples]

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PUT 'http://localhost:8180/v2/namespaces/test/collections/library/John-Smith' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '     {
     "reader": {
        "name": "John Smith",
        "user_id": "12346",
        "birthdate": "11-01-1992",
        "email": {
            "primary": "jsmith@gmail.com",
            "secondary": "john.smith@aol.com"
        },
        "address": {
            "primary": {
                "street": "200 Z St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55555
            },
            "secondary": {
                "street": "850 2nd St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55556
            }
        },
        "reviews": [
            {
                "book-title": "Moby Dick", 
                "rating": 3, 
                "review-date": "02-02-2002",
                "comment": "It was okay."
            },
            {
                "book-title": "Pride and Prejudice", 
                "rating": 5, 
                "review-date": "03-02-2002",
                "comment": "It was a wonderful book! I loved reading it."
            }
        ]
     }
 }
'
curl --location --request PUT 'http://localhost:8082/v2/namespaces/test/collections/library/John-Smith' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw '     {
     "reader": {
        "name": "John Smith",
        "user_id": "12346",
        "birthdate": "11-01-1992",
        "email": {
            "primary": "jsmith@gmail.com",
            "secondary": "john.smith@aol.com"
        },
        "address": {
            "primary": {
                "street": "200 Z St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55555
            },
            "secondary": {
                "street": "850 2nd St",
                "city": "Evertown",
                "state": "MA",
                "zip-code": 55556
            }
        },
        "reviews": [
            {
                "book-title": "Moby Dick", 
                "rating": 3, 
                "review-date": "02-02-2002",
                "comment": "It was okay."
            },
            {
                "book-title": "Pride and Prejudice", 
                "rating": 5, 
                "review-date": "03-02-2002",
                "comment": "It was a wonderful book! I loved reading it."
            }
        ]
     }
 }
'
{
  "documentId": "John-Smith"
}

Decorations for writing documents: Time-to-live (TTL) and profiling

Both TTL and profiling can be used as options for POST, PUT, and PATCH requests. TTL will add a time-to-live value in the database, so that the entry will be marked for deletion when the TTL expires.

Profiling will return the CQL that is implemented in the back-end when a request is executed.

Profiling

Adding profile=true to a request will return the CQL that is executed. For this example, a PATCH request, an insertion of data is made, and a deletion of data is done, to change the data written.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PATCH 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?profile=true' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!",
  "choices": [
     "eeny",
     "meeny",
     "meiny",
     "mo"
  ]
}'
curl --location --request PATCH 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?profile=true' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!",
  "choices": [
     "eeny",
     "meeny",
     "meiny",
     "mo"
  ]
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "profile": {
    "description": "root",
    "queries": [],
    "nested": [
      {
        "description": "ASYNC PATCH",
        "queries": [
          {
            "cql": "INSERT INTO test.library (key, p0, p1, p2, p3, p4, p5, p6, p7, p8, p9, p10, p1
1, p12, p13, p14, p15, p16, p17, p18, p19, p20, p21, p22, p23, p24, p25, p26, p27, p28, p29, p30, 
p31, p32, p33, p34, p35, p36, p37, p38, p39, p40, p41, p42, p43, p44, p45, p46, p47, p48, p49, p50
, p51, p52, p53, p54, p55, p56, p57, p58, p59, p60, p61, p62, p63, leaf, text_value, dbl_value, bo
ol_value) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?,
 ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?
, ?, ?, ?, ?, ?, ?, ?, ?, ?) USING TTL ? AND TIMESTAMP ?",
            "executionCount": 5,
            "rowCount": 5
          },
          {
            "cql": "DELETE FROM test.library USING TIMESTAMP ? WHERE key = ? AND p0 = ? AND p1 = ?
 AND p2 = ? AND p3 = ? AND p4 = ? AND p5 = ? AND p6 = ? AND p7 = ? AND p8 = ? AND p9 = ? AND p10 =
 ? AND p11 = ? AND p12 = ? AND p13 = ? AND p14 = ? AND p15 = ? AND p16 = ? AND p17 = ? AND p18 = ?
 AND p19 = ? AND p20 = ? AND p21 = ? AND p22 = ? AND p23 = ? AND p24 = ? AND p25 = ? AND p26 = ? A
ND p27 = ? AND p28 = ? AND p29 = ? AND p30 = ? AND p31 = ? AND p32 = ? AND p33 = ? AND p34 = ? AND
 p35 = ? AND p36 = ? AND p37 = ? AND p38 = ? AND p39 = ? AND p40 = ? AND p41 = ? AND p42 = ? AND p
43 = ? AND p44 = ? AND p45 = ? AND p46 = ? AND p47 = ? AND p48 = ? AND p49 = ? AND p50 = ? AND p51
 = ? AND p52 = ? AND p53 = ? AND p54 = ? AND p55 = ? AND p56 = ? AND p57 = ? AND p58 = ? AND p59 =
 ? AND p60 = ? AND p61 = ? AND p62 = ? AND p63 = ?",
            "executionCount": 1,
            "rowCount": 1
          },
          {
            "cql": "DELETE FROM test.library USING TIMESTAMP ? WHERE key = ? AND p0 IN ?",
            "executionCount": 1,
            "rowCount": 0
          },
          {
            "cql": "DELETE FROM test.library USING TIMESTAMP ? WHERE key = ? AND p0 >= ? AND p0 <=
 ?",
            "executionCount": 1,
            "rowCount": 0
          }
        ],
        "nested": []
      }
    ]
  }
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "choices": [
      "eeny",
      "meeny",
      "meiny",
      "mo"
    ],
    "id": "some-other-stuff",
    "languages": [
      "English",
      "German",
      "French"
    ],
    "other": "This is changed nonsensical stuff.",
    "yet-another-field": "Hopefully, I haven't lost my other two fields!"
  }
}

TTL

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PUT 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?ttl=10000' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "okaydokie": "Now I have done it! We have a TTL at last!"
}'
curl --location --request PUT 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?ttl=10000' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "okaydokie": "Now I have done it! We have a TTL at last!"
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311"
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "okaydokie": "Now I have done it! We have a TTL at last!"
  }
}

Updating documents

Data changes, so often it is necessary to update or modify an entire document.

Replace a document with PUT

A PUT request using a document-id will replace a document found in a collection.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PUT 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "id": "some-other-stuff",
  "other": "This is changed nonsensical stuff."
}'
curl --location --request PUT 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "id": "some-other-stuff",
  "other": "This is changed nonsensical stuff."
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311"
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "id": "some-other-stuff",
    "other": "This is changed nonsensical stuff."
  }
}

Replace some data in a document with PATCH and document-id

A 'PATCH' request using a document-id will replace the targeted data in a JSON object contained in the document. JSON objects are delimited by { } in the data. If you have an array, delimited by '[ ]' in the JSON object targeted, or a scalar value, the values will be overwritten.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PATCH 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!"
}'
curl --location --request PATCH 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!"
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311"
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "id": "some-other-stuff",
    "other": "This is changed nonsensical stuff.",
    "yet-another-field": "Hopefully, I haven't lost my other two fields!"
  }
}

PATCH updates are upserts. If the document doesn’t exist, it will be created. If it does exist, it will be updated with the new document data.

Another example with PATCH

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request PATCH 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!",
  "languages": [
     "English",
     "German",
     "French"
  ]
}'
curl --location --request PATCH 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
  "yet-another-field": "Hopefully, I haven'\''t lost my other two fields!",
  "languages": [
     "English",
     "German",
     "French"
  ]
}'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311"
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "id": "some-other-stuff",
    "languages": [
      "English",
      "German",
      "French"
    ],
    "other": "This is changed nonsensical stuff.",
    "yet-another-field": "Hopefully, I haven't lost my other two fields!"
  }
}

Write data to a document-path with PUT

It is also possible to update only part of a document. Using a PUT request, you can replace current data in a document. To partially update, send a PUT request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/{document-path}. This example will change the book title from Native Son to Native Daughter:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -X 'PUT' \
  'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book' \
  -H "X-Cassandra-Token: $AUTH_TOKEN" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "Native Daughter" }'
curl -X 'PUT' \
  'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book' \
  -H "X-Cassandra-Token: $AUTH_TOKEN" \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{ "title": "Native Daughter" }'
{
    "documentId": "native-son-doc-id"
}

Write data to a document-path with PATCH

Using a PATCH request, you can overwrite current data in a document. To partially update, send a PATCH request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/{document-path}. This example overwrites a book’s information:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -X 'PATCH' \
  'http://http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book' \
  -H 'accept: application/json' \
  -H "X-Cassandra-Token: $AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "book": {
    "title": "Native Daughter",
    "isbn": "12322",
    "author": [
        "Richard Wright"
    ],
    "pub-year": 1930,
    "genre": [
        "poverty",
        "action"
    ],
    "format": [
        "hardback",
        "paperback",
        "epub"
    ],
    "languages": [
        "English",
        "German",
        "French"
    ]
  }
}'
curl -X 'PATCH' \
  'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book' \
  -H 'accept: application/json' \
  -H "X-Cassandra-Token: $AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
  "book": {
    "title": "Native Daughter",
    "isbn": "12322",
    "author": [
        "Richard Wright"
    ],
    "pub-year": 1930,
    "genre": [
        "poverty",
        "action"
    ],
    "format": [
        "hardback",
        "paperback",
        "epub"
    ],
    "languages": [
        "English",
        "German",
        "French"
    ]
  }
}'
{
    "documentId": "native-son-doc-id"
}

Using built-in functions push and pop for arrays

Two built-in functions, push and pop, can be used to modify an array in a document.

View built-in functions for a particular namespace

A GET request with the endpoint functions will return the built-in functions with their descriptions:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -X GET 'http://localhost:8180/v2/schemas/namespaces/test/functions' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

curl -X GET 'http://localhost:8082/v2/schemas/namespaces/test/functions' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json'


{
  "functions": [
    {
      "name": "$push",
      "description": "Appends data to the end of an array"
    },
    {
      "name": "$pop",
      "description": "Removes data from the end of an array, returning it"
    }
  ]
}

Push an array element into a document using a document-path

Let’s check the data in an array of book genre before we change it:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/genre' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book/genre' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \


{
  "documentId": "native-son-doc-id",
  "data": [
    "slavery",
    "action",
  ]
}

A POST using push will add the desired data to the end of the array specified in the document-path. Notice that structure of the data passed:

"operation": "$push", "value": "culture"
  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/genre/function' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
 "operation": "$push", "value": "culture" 
}'

curl --location --request POST 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book/genre/function' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \ --data-raw ' { "operation": "$push", "value": "culture" }'


{
  "documentId": "native-son-doc-id",
  "data": [
    "slavery",
    "action",
    "culture"
  ]
}

Pop an array element off a document using a document-path

A POST using pop will remove the last element from the end of the array specified in the document-path. Notice that structure of the data passed:

"operation": "$pop"

without any value assigned.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request POST 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/genre/function' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
--data-raw ' {
 "operation": "$pop"
}'

curl --location --request POST 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book/genre/function' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \ --data-raw ' { "operation": "$pop" }'


{
  "documentId": "native-son-doc-id",
  "data": "culture"
}

To check if the data is changed, GET the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/genre' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book/genre' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \


{
  "documentId": "native-son-doc-id",
  "data": [
    "slavery",
    "action"
  ]
}

Reading documents

You can either search in collections for documents, or you can search within documents.

It is possible to get a value for a particular field in a document using one of two methods, either a where clause or a document-path. These methods canretrieve documents from a collection, or information from within a document. Both methods will be detailed.

List all documents in a collection

This command finds all the documents that exist in a collection.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "pageState": "JDNkMGUyZjcxLWRmZTktNGFiMy04MDk5LTllZTdhY2NhMGI3ZgDwf_____B_____",
  "data": {
    "9a47dcbc-2a41-429e-bd1b-fad26ac23b00": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "asmith@gmail.com",
          "secondary": "amyispolite@aol.com"
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ],
        "user_id": "12345"
      }
    },
    "John-Smith": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "200 Z St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "11-01-1992",
        "email": {
          "primary": "jsmith@gmail.com",
          "secondary": "john.smith@aol.com"
        },
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ],
        "user_id": "12346"
      }
    },
    "3d0e2f71-dfe9-4ab3-8099-9ee7acca0b7f": {
      "book": {
        "author": [
          "Herman Melville"
        ],
        "format": [
          "hardback",
          "paperback",
          "epub"
        ],
        "genre": [
          "adventure",
          "ocean",
          "action"
        ],
        "isbn": "12345",
        "languages": [
          "English",
          "German",
          "French"
        ],
        "pub-year": 1899,
        "title": "Moby Dick"
      }
    }
  }
}

Decorations for getting documents - paging-size, paging-state, fields

Paging-size

The page-size parameter has a default value of 3 and a maximum value of 20. You can set the value in the REST query:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location \
--request GET 'http://localhost:8180/v2/namespaces/test/collections/library?page-size=5' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl --location \
--request GET 'http://localhost:8082/v2/namespaces/test/collections/library?page-size=5' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "pageState": "JDdjMDFmYmY0LTc1Y2YtNGQzNi1iZWVmLTkxODU5ZTExZmQ0ZADwf_____B_____",
  "data": {
    "John-Smith": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "200 Z St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "11-01-1992",
        "email": {
          "primary": "jsmith@gmail.com",
          "secondary": "john.smith@aol.com"
        },
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ],
        "user_id": "12346"
      }
    },
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "asmith@gmail.com",
          "secondary": "amyispolite@aol.com"
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ],
        "user_id": "12345"
      }
    },
    "cea50938-8279-44a9-b30d-41ee9a64be37": {
      "book": {
        "author": [
          "Herman Melville"
        ],
        "format": [
          "hardback",
          "paperback",
          "epub"
        ],
        "genre": [
          "adventure",
          "ocean",
          "action"
        ],
        "isbn": "12345",
        "languages": [
          "English",
          "German",
          "French"
        ],
        "pub-year": 1899,
        "title": "Moby Dick"
      }
    },
    "2545331a-aaad-45d2-b084-9da3d8f4c311": {
      "okaydokie": "Now I have done it! We have a TTL at last!"
    },
    "7c01fbf4-75cf-4d36-beef-91859e11fd4d": {
      "id": "some-stuff",
      "other": "This is nonsensical stuff."
    }
  }
}

Paging-state

The paging state allows a user to page through the returned documents. For large collections, you can page a subset of the results. If more than the allowed paging size of documents are returned, paging-state can be used to get subsequent pages of documents. Send a GET request to /v2/namespaces/{namespace_name}/collections/{collections_name}?page-size=5 to retrieve the first five documents (a page) in the collection

The paging state value must be retrieved from the previous JSON results. Pay close attention to the pageState value in the results. The pageState is a string representing a location in the result set. It is essentially an encoded shortcut that allows the final result set to be built from a specific point. In order to get the next five documents, re-run the request with page-state parameter set to the first page’s pageState:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?page-state=JGQwODFlYmIyLTQ4OWUtNDI1ZS04NTI1LWEyNTU4NGY0N2JjZADwf_____B_____' \
--header "X-Cassandra-Token: $AUTH_TOKEN"
curl --location --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?page-state=JGQwODFlYmIyLTQ4OWUtNDI1ZS04NTI1LWEyNTU4NGY0N2JjZADwf_____B_____' \
--header "X-Cassandra-Token: $AUTH_TOKEN"
{
  "data": {
    "e7221abd-94b8-4080-b094-7ab0c222c3fd": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "100 Main St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "jdoe@gmail.com",
          "secondary": "jane.doe@aol.com"
        },
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ],
        "user_id": "12345"
      }
    },
    "37fb3076-e413-43cb-8645-545aa13b72b0": {
      "reader": {
        "address": {
          "primary": {
            "city": "Paradise",
            "state": "CA",
            "street": "4593 Webster Ave",
            "zip-code": 95534
          }
        },
        "birthdate": "06-11-2000",
        "email": {
          "primary": "jjones@gmail.com",
          "secondary": "johnnyj@aol.com"
        },
        "name": "John Jones",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "Boring book that I had to read for class.",
            "rating": 2,
            "review-date": "03-15-2020"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "Another boring book.",
            "rating": 2,
            "review-date": "0-02-2020"
          }
        ],
        "user_id": "54321"
      }
    },
    "native-son-doc-id": {
      "book": {
        "author": [
          "Richard Wright"
        ],
        "format": [
          "hardback",
          "paperback",
          "epub"
        ],
        "genre": [
          "slavery",
          "action"
        ],
        "isbn": "12322",
        "languages": [
          "English",
          "German",
          "French"
        ],
        "pub-year": 1930,
        "title": "Native Son"
      }
    }
  }
}

Fields

Entire documents are returned in JSON format, unless the fields option is used. You can specify the fields that you wish returned in the REST query:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id?fields=["book.title","book.genre"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id?fields=["book.title","book.genre"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "native-son-doc-id",
  "data": {
    "book": {
      "genre": [
        "slavery",
        "action"
      ],
      "title": "Native Son"
    }
  }
}

In this example, fields=["book.title","book.genre"], the book title (a string) and the book genre (an array) are the only fields returned in the results.

Search collection for documents with a simple WHERE clause

A WHERE clause is used to search for documents that have a particular value that matches the corresponding operator. A GET request to /v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause} is the basic form of the query. For one of the simplest WHERE clasues, get all documents where a name equals a particular reader’s name:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "asmith@gmail.com",
          "secondary": "amyispolite@aol.com"
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ],
        "user_id": "12345"
      }
    }
  }
}

In this example, where={"reader.name":{"$eq":"Amy%20Smith"}}, note that the whitespace in the specified string must be encoded with %20. The full documents are returned in this example.

Search collection for documents with a simple WHERE clause with fields

If you wish to just return some fields, use a WHERE clause in conjunction with the fields option. Get all documents where name eq a particular reader with the fields reader name and reader birthdate:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}&fields=["reader.name","reader.birthdate"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}&fields=["reader.name","reader.birthdate"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "asmith@gmail.com",
          "secondary": "amyispolite@aol.com"
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ],
        "user_id": "12345"
      }
    }
  }
}

Search collections for documents with operators: eq, ne, or, and, not, gt, gte, lt, lte, in, nin

Several operators can be used to search for documents within collections.

Operator Description

eq

A specified value equals a field in a returned document

ne

A specified value does not equal a field in a returned document

or

One of the specified statements equals a field in a returned document

and

All of the specified statements equals a field in a returned document

not

All the specified statements not equalling a field, or a non-existent field, in a returned document

gt, gte, lt, lte

Greater than, greater than or equal, less than, less than or equal - the typical mathematical functions

in

All specified values are individually used to equal a field in a returned document

nin

All specified values are individually used to not equal a field in a returned document

eq

The eq operator matches any field value with a supplied value.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}&fields=["reader.name","reader.birthdate"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.name":{"$eq":"Amy%20Smith"}}&fields=["reader.name","reader.birthdate"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "birthdate": "10-01-1980",
        "email": {
          "primary": "asmith@gmail.com",
          "secondary": "amyispolite@aol.com"
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ],
        "user_id": "12345"
      }
    }
  }
}

ne

The ne operator matches any field value that does not equal a supplied value.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"$and":[{"reader.name":{"$ne":"Amy%20Smith"}},{"reader.name":{"$exists":true}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"$and":[{"reader.name":{"$ne":"Amy%20Smith"}},{"reader.name":{"$exists":true}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "birthdate": "11-01-1992",
        "name": "John Smith",
        "user_id": "12346"
      }
    },
    "6bcecbcd-4eb3-4fc7-ba8a-9eb781b3af5f": {
      "reader": {
        "birthdate": "06-11-2000",
        "name": "John Jones",
        "user_id": "54321"
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Jane Doe",
        "user_id": "12345"
      }
    }
  }
}

{"$and":[{"reader.name":{"$ne":"Amy%20Smith"}},{"reader.name":{"$exists":true}}]} will match if the reader name is not equal to "Amy Smith" AND the reader name exists.

Another example of using the ne operator explores using a multiple WHERE query to accomplish the same thing as the and operator in the last example:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$ne":"Amy%20Smith","$exists":true}}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.name":{"$ne":"Amy%20Smith","$exists":true}}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "birthdate": "11-01-1992",
        "name": "John Smith",
        "user_id": "12346"
      }
    },
    "6bcecbcd-4eb3-4fc7-ba8a-9eb781b3af5f": {
      "reader": {
        "birthdate": "06-11-2000",
        "name": "John Jones",
        "user_id": "54321"
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Jane Doe",
        "user_id": "12345"
      }
    }
  }
}

{"reader.name":{"$ne":"Amy%20Smith","$exists":true}} compacts same clause as the and statement above, since the two items checked, the reader’s name and the existence, are matching the same field, reader.name.

and

The and operator is used when two or more fields are matched to obtain the returned documents. Both matches must exist in order for a document to be returned.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"$and":[{"reader.name":{"$ne":"Amy%20Smith"}},{"reader.name":{"$exists":true}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"$and":[{"reader.name":{"$ne":"Amy%20Smith"}},{"reader.name":{"$exists":true}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "birthdate": "11-01-1992",
        "name": "John Smith",
        "user_id": "12346"
      }
    },
    "6bcecbcd-4eb3-4fc7-ba8a-9eb781b3af5f": {
      "reader": {
        "birthdate": "06-11-2000",
        "name": "John Jones",
        "user_id": "54321"
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Jane Doe",
        "user_id": "12345"
      }
    }
  }
}

or

The or operator is used when two or more fields are matched to obtain the returned documents. Either match must exist in order for a document to be returned.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"$or":[{"reader.name":{"$eq":"Amy%20Smith"}},{"reader.name":{"$eq":"Jane%20Doe"}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"$or":[{"reader.name":{"$eq":"Amy%20Smith"}},{"reader.name":{"$eq":"Jane%20Doe"}}]}&fields=["reader.name","reader.user_id","reader.birthdate"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Amy Smith",
        "user_id": "12345"
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Jane Doe",
        "user_id": "12345"
      }
    }
  }
}

not

The not operator returns any documents that do not match the supplied value for a field. The results also include documents that do not contain the field.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"$not":{"book.title":{"$eq":"Moby%20Dick"}}}&fields=["book.title","book.authors"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"$not":{"book.title":{"$eq":"Moby%20Dick"}}}&fields=["book.title","book.authors"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "pageState": "JGNlODc3ZTMwLWY5OGQtNDI3YS1hMWNlLWM5MTdlYjEzNzc5NwDwf_____B_____",
  "data": {
    "6bcecbcd-4eb3-4fc7-ba8a-9eb781b3af5f": {},
    "John-Smith": {},
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {},
    "2545331a-aaad-45d2-b084-9da3d8f4c311": {},
    "7c01fbf4-75cf-4d36-beef-91859e11fd4d": {},
    "ce877e30-f98d-427a-a1ce-c917eb137797": {
      "book": {
        "title": "The Art of French Cooking"
      }
    }
  }
}

gt, gte, lt, lte

The gt, gte, lt, and lte operator check if the specified value is greater than, greater than or equal, less than, or less than or equal, respectively.

This example looks for documents that have book review ratings that are greater than 3 and less than or equal to 5 (all values that are 4 or 5):

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.reviews.[*].rating":{"$gt":3,"$lte":5}}&fields=["reader.name","reader.reviews.rating","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.reviews.[*].rating":{"$gt":3,"$lte":5}}&fields=["reader.name","reader.reviews.rating","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    },
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ]
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    }
  }
}

in

The in operator matches specified values if they are in the field checked.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$in":["Jane%20Doe","Amy%20Smith"]}}&fields=["reader.name","reader.birthdate","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location -g --request GET '"Jane%20Doe","Amy%20Smith"}}&fields=["reader.name","reader.birthdate","reader.reviews"]&page-size=6' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \


{
  "data": {
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ]
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "birthdate": "10-01-1980",
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    }
  }
}

A second example gets documents where the names are in the field, but one name fails:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$in":["Jane%20Doe","John%20Smith"]}}&fields=["reader.name","reader.address","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location -g --request GET '"Jane%20Doe","John%20Smith"}}&fields=["reader.name","reader.address","reader.reviews"]&page-size=6' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \


{
  "data": {
    "John-Smith": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "200 Z St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    },
    "e32bc819-cd07-4ef6-a501-cace6869dcca": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "100 Main St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    }
  }
}

nin

The nin operator selects the documents there the specified value is not in the specified array or the fields does not exist.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.name":{"$nin":["Jane%20Doe","Amy%20Smith"]}}&fields=["reader.name","reader.birthdate","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location -g --request GET '"Jane%20Doe","Amy%20Smith"}}&fields=["reader.name","reader.birthdate","reader.reviews"]&page-size=6' \ --header "X-Cassandra-Token: $AUTH_TOKEN" \ --header 'Content-Type: application/json' \


{
  "pageState": "JDI1NDUzMzFhLWFhYWQtNDVkMi1iMDg0LTlkYTNkOGY0YzMxMQDwf_____B_____",
  "data": {
    "6348fe50-3f19-4224-946b-88acdacd539b": {
      "reader": {
        "birthdate": "06-11-2000",
        "name": "John Jones",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "Boring book that I had to read for class.",
            "rating": 2,
            "review-date": "03-15-2020"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "Another boring book.",
            "rating": 2,
            "review-date": "0-02-2020"
          }
        ]
      }
    },
    "f9fa7e41-e576-48b7-a589-65b7f6be3cb9": {},
    "John-Smith": {
      "reader": {
        "birthdate": "11-01-1992",
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    },
    "29307102-01c8-4dd3-8b1a-a886026b9f0f": {},
    "57b06ec9-e222-47e4-a976-4666581f17a5": {},
    "2545331a-aaad-45d2-b084-9da3d8f4c311": {}
  }
}

Search collections for documents with other techniques

Use multiple fields

Multiple fields can be specified for a search using a comma to delineate the search fields. For example, a specified value for a city can search in both the primary and secondary addresses of a reader:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.address.primary,secondary.city":{"$eq":"Evertown"}}&fields=["reader.name","reader.address","reader.reviews"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.address.primary,secondary.city":{"$eq":"Evertown"}}&fields=["reader.name","reader.address","reader.reviews"]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "200 Z St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    },
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ]
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "100 Main St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    }
  }
}

Use a wildcard (*) in a string or array field

A wildcard (*) is useful when searching for a specified value in multiple fields of the same type. It can be used to search either a string field or an array field. In this example, several book reviews are searched, looking for a specified book title. Each reader review has a number of fields, of which book-title is one.

A wildcard cannot be used as the last field in a specified path.

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library?where={"reader.reviews.[*].book-title":{"$eq":"Moby%20Dick"}}&fields=["reader.name","reader.address","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library?where={"reader.reviews.[*].book-title":{"$eq":"Moby%20Dick"}}&fields=["reader.name","reader.address","reader.reviews"]&page-size=6' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "data": {
    "John-Smith": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "200 Z St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "John Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    },
    "9195f8c9-1bd8-4ee5-b812-7075f9343331": {
      "reader": {
        "address": {
          "primary": {
            "city": "Nevertown",
            "state": "MA",
            "street": "200 Antigone St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "Amy Smith",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was better than I thought.",
            "rating": 4,
            "review-date": "04-25-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was just like the movie.",
            "rating": 2,
            "review-date": "12-02-2002"
          }
        ]
      }
    },
    "6bcecbcd-4eb3-4fc7-ba8a-9eb781b3af5f": {
      "reader": {
        "address": {
          "primary": {
            "city": "Paradise",
            "state": "CA",
            "street": "4593 Webster Ave",
            "zip-code": 95534
          }
        },
        "name": "John Jones",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "Boring book that I had to read for class.",
            "rating": 2,
            "review-date": "03-15-2020"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "Another boring book.",
            "rating": 2,
            "review-date": "0-02-2020"
          }
        ]
      }
    },
    "a5e54626-fd69-43ec-836d-115166e6d60b": {
      "reader": {
        "address": {
          "primary": {
            "city": "Evertown",
            "state": "MA",
            "street": "100 Main St",
            "zip-code": 55555
          },
          "secondary": {
            "city": "Evertown",
            "state": "MA",
            "street": "850 2nd St",
            "zip-code": 55556
          }
        },
        "name": "Jane Doe",
        "reviews": [
          {
            "book-title": "Moby Dick",
            "comment": "It was okay.",
            "rating": 3,
            "review-date": "02-02-2002"
          },
          {
            "book-title": "Pride and Prejudice",
            "comment": "It was a wonderful book! I loved reading it.",
            "rating": 5,
            "review-date": "03-02-2002"
          }
        ]
      }
    }
  }
}

Retrieving a document from a collection with a document-id

Retrieving a specified document

Let’s check that some data was inserted for a particular document. Send a GET request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id} to retrieve the document:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X GET 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "2545331a-aaad-45d2-b084-9da3d8f4c311",
  "data": {
    "okaydokie": "Now I have done it! We have a TTL at last!"
  }
}

Search for information within documents

Retrieving a specific portion of a document with document-path

A document-path uses a document’s structure to drill down and get information from within a document. To find particular values, send a GET request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/{document-path} to retrieve a book title:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/title' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/native-son-doc-id/book/title' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "documentId": "native-son-doc-id",
  "data": "Native Son"
}

Retrieving a document field value using a document-path and array number

This example shows the use of an array value, in conjunction with a document-id and document-path, to find the book-title of the second book a reader reviewed:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/John-Smith/reader/reviews/[1]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/John-Smith/reader/reviews/[1]' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "documentId": "John-Smith",
  "data": {
    "book-title": "Pride and Prejudice",
    "comment": "It was a wonderful book! I loved reading it.",
    "rating": 5,
    "review-date": "03-02-2002"
  }
}

Retrieving document data using a document-path and WHERE clause

This example shows the use of a WHERE clause, in conjunction with a document-id and document-path:

  • cURL command (/v2)

  • cURL command (/v1)

  • Result

curl --location -g --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/John-Smith/reader/reviews?WHERE={"reader.reviews.rating":{"$eq":5}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request GET 'http://localhost:8082/v2/namespaces/test/collections/library/John-Smith/reader/reviews?WHERE={"reader.reviews.rating":{"$eq":5}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
{
  "documentId": "John-Smith",
  "data": [
    {
      "book-title": "Moby Dick",
      "comment": "It was okay.",
      "rating": 3,
      "review-date": "02-02-2002"
    },
    {
      "book-title": "Pride and Prejudice",
      "comment": "It was a wonderful book! I loved reading it.",
      "rating": 5,
      "review-date": "03-02-2002"
    }
  ]
}

Delete a document or part of a document

Delete data in a document

To delete a document path in a document, send a DELETE request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/{document-path}. In this example, the secondary address for the user John Smith is deleted from the document.

  • cURL command (/v2)

  • cURL command (/v1)

curl --location -g --request DELETE 'http://localhost:8180/v2/namespaces/test/collections/library/John-Smith/reader/address/secondary' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request DELETE 'http://localhost:8082/v2/namespaces/test/collections/library/John-Smith/reader/address/secondary' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

Delete full document using a document-id

To delete a document, send a DELETE request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}.

  • cURL command (/v2)

  • cURL command (/v1)

curl -L \
-X DELETE 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
curl -L \
-X DELETE 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'
Deletions do not return any data.

Delete a full document using a WHERE clause

To delete a document, based on a WHERE clause, send a DELETE request to /v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/?{where-clause}.

  • cURL command (/v2)

  • cURL command (/v1)

curl --location -g --request DELETE 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?where={ "id":{"$eq":"some stuff"}}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \
curl --location -g --request DELETE 'http://localhost:8082/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311?where={ "id":{"$eq":"some stuff"}}' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \