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 are looking to just get started, DataStax Astra Database-as-a-Service can get you started with no install steps. |
-
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
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:v2v1
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.57v2
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:v2v1
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.57v2
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-68:v2
docker pull stargateio/restapi:v2
docker pull stargateio/docsapi:v2
docker pull stargateio/graphqlapi:v2v1
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
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.shThis 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.57v2
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.shThis 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.57v2
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.shThis 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-
Generate an authorization token to access the interface by following the instructions in Table-based authentication/Authorization
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 --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 |
|---|---|---|---|
|
|
Retrieves the URL listed, even if it has moved |
|
|
|
|
Defines the type of REST operation, such as |
|
'--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 |
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 --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 -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 -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 -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 -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 --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 returnThe 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 |
|---|---|---|---|
|
|
Retrieves the URL listed, even if it has moved |
|
|
|
|
Defines the type of REST operation, such as |
|
'--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 |
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 --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 -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 -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, orDELETE.
|
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 --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 --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 --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 --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 -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 --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 --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 --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 --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 -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 --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 -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 --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 -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 --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 -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!"
}
}|
|
Another example with PATCH
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 -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 -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 -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 -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 --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 --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 --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 --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 -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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 --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 -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 --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 --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 --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 --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 -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 --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' \