API docs by Redocly

Stargate Document API reference (2.0.18)

Download OpenAPI specification:Download

URL: https://www.datastax.com/contact-us License: Apache 2.0 Terms of Service

The Stargate Document API modifies and queries Astra DB Cassandra data stored as unstructured JSON documents in collections. See the documentation site for additional information.

Documents

Document-related operations.

Search documents in a collection

Page over documents in a collection, with optional search parameters.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

query Parameters
where
any
Examples:
  • - No condition
  • location=[object Object] - Single condition
  • location=[object Object]&race.competitors=[object Object] - Multiple conditions (implicit $and)
  • $and=[object Object],[object Object] - And conditions
  • $or=[object Object],[object Object] - Or conditions
  • $not=[object Object] - Using negation
  • $and=[object Object],[object Object] - With selectivity

A JSON blob with search filters:

  • allowed predicates: $eq, $ne, $in, $nin, $gt, $lt, $gte, $lte, $exists
  • allowed boolean operators: $and, $or, $not
  • allowed hints: $selectivity (a number between 0.0 and 1.0, less is better), defines conditions that should be search for first
  • Use \ to escape periods, commas, and asterisks
fields
any
Examples:
  • - No fields
  • fields=race&fields=location - Fields example

A JSON array representing the field names that you want to restrict the results to.

page-size
integer <int32> [ 1 .. 20 ]
Default: 3

The max number of results to return.

page-state
boolean

Cassandra page state, used for pagination on consecutive requests.

profile
boolean

Whether to include query profiling information in the response (advanced).

raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
Example
{
  • "data": [
    ],
  • "pageState": "c29tZS1leGFtcGxlLXN0YXRl"
}

Create a document

Create a new document with the generated ID. If the collection does not exist, it will be created.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

query Parameters
ttl
integer <int32>

The time-to-live (in seconds) of the document.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON of a document.

object

Responses

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Create documents

Create multiple new documents. If the collection does not exist, it will be created.

Include the id-path parameter to extract the ID for each document from the document itself. The id-path should be given as path to the document property containing the id, for example a.b.c.[0]. Note that document IDs will be auto-generated in case there is no id-path parameter defined.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

query Parameters
id-path
string

The optional path of the ID in each document whose value will be used as the ID of the created document, if present.

ttl
integer <int32>

The time-to-live (in seconds) of the document.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON array of a documents for batch write.

arrays

Responses

Request samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Response samples

Content type
application/json
{
  • "documentIds": [
    ]
}

Get a document

Retrieve the JSON representation of a single document.

Note that in case when conditions are given using the where query parameter or the page-size query parameter is defined, the response will contain an array of sub-documents where the condition is matched. The structure of returned sub-documents will only contain the path to the field which was included in the condition. Other fields of the matched sub-document can be included using the fields parameter. Only single field conditions are possible at the moment. Multiple conditions targeting the same field are allowed. The page size and page state parameters are only used together with where and enable paging through matched sub-documents.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

query Parameters
where
any
Examples:
  • - No condition
  • location=[object Object] - Single condition
  • location=[object Object]&race.competitors=[object Object] - Multiple conditions (implicit $and)
  • $and=[object Object],[object Object] - And conditions
  • $or=[object Object],[object Object] - Or conditions
  • $not=[object Object] - Using negation
  • $and=[object Object],[object Object] - With selectivity

A JSON blob with search filters:

  • allowed predicates: $eq, $ne, $in, $nin, $gt, $lt, $gte, $lte, $exists
  • allowed boolean operators: $and, $or, $not
  • allowed hints: $selectivity (a number between 0.0 and 1.0, less is better), defines conditions that should be search for first
  • Use \ to escape periods, commas, and asterisks
fields
any
Examples:
  • - No fields
  • fields=race&fields=location - Fields example

A JSON array representing the field names that you want to restrict the results to.

page-size
integer <int32> >= 1

The max number of results to return.

page-state
boolean

Cassandra page state, used for pagination on consecutive requests.

profile
boolean

Whether to include query profiling information in the response (advanced).

raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
Example
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": {
    }
}

Create or update a document

Create or update a document with a given ID. If the collection does not exist, it will be created. If the document already exists, it will be overwritten.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

query Parameters
ttl
integer <int32>

The time-to-live (in seconds) of the document.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON of a document.

object

Responses

Request samples

Content type
application/json
{
  • "location": "London",
  • "race": {
    }
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a document

Delete a document with a given ID.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

query Parameters
profile
boolean

Whether to include query profiling information in the response (advanced).

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a document

Patch a document with a given ID. Merges data at the root with requested data. Note that operation is not allowed if a JSON schema exist for a target collection.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

query Parameters
ttl-auto
boolean

If set to true on document update or patch, ensures that the time-to-live for the updated portion of the document will match the parent document. Requires a read-before-write if set to true.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON of a patch.

object

Responses

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function

Execute a built-in function (e.g. $push and $pop) against the root of this document. Performance may vary.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

query Parameters
profile
boolean

Whether to include query profiling information in the response (advanced).

raw
boolean

Unwrap results.

Request Body schema: application/json

The request body for executing a built-in function.

operation
required
string\$pop|\$push|\$set

The operation to execute

object or null

The value to use for the operation

Responses

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

  • $pop - returns the item that was popped from the array
  • $push - returns the complete array, including the item that was pushed
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": 123
}

Get a path in a document

Retrieve the JSON representation of the document at a provided path.

Note that in case when conditions are given using the where query parameter or the page-size query parameter is defined, the response will contain an array of sub-documents where the condition is matched. The structure of returned sub-documents will only contain the path to the field which was included in the condition. Other fields of the matched sub-document can be included using the fields parameter. Only single field conditions are possible at the moment. Multiple conditions targeting the same field are allowed. The page size and page state parameters are only used together with where and enable paging through matched sub-documents.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

document-path
required
string

The path in the JSON that you want to target. Use path delimiter / to target sub-paths, for example to get a JSON object under $.account.user use account/user. Use \ to escape periods, commas, and asterisks.

query Parameters
where
any
Examples:
  • - No condition
  • location=[object Object] - Single condition
  • location=[object Object]&race.competitors=[object Object] - Multiple conditions (implicit $and)
  • $and=[object Object],[object Object] - And conditions
  • $or=[object Object],[object Object] - Or conditions
  • $not=[object Object] - Using negation
  • $and=[object Object],[object Object] - With selectivity

A JSON blob with search filters:

  • allowed predicates: $eq, $ne, $in, $nin, $gt, $lt, $gte, $lte, $exists
  • allowed boolean operators: $and, $or, $not
  • allowed hints: $selectivity (a number between 0.0 and 1.0, less is better), defines conditions that should be search for first
  • Use \ to escape periods, commas, and asterisks
fields
any
Examples:
  • - No fields
  • fields=race&fields=location - Fields example

A JSON array representing the field names that you want to restrict the results to.

page-size
integer <int32> >= 1

The max number of results to return.

page-state
boolean

Cassandra page state, used for pagination on consecutive requests.

profile
boolean

Whether to include query profiling information in the response (advanced).

raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
Example

Response example when using a sub-document path /race on a document like:

{ "location": "London", "race": { "competitors": 100, "start_date": "2022-08-15" } }

{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": {
    }
}

Create or update a path in a document

Create or update a path in a document by ID. If the collection does not exist, it will be created. If data exists at the path, it will be overwritten.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

document-path
required
string

The path in the JSON that you want to target. Use path delimiter / to target sub-paths, for example to get a JSON object under $.account.user use account/user. Use \ to escape periods, commas, and asterisks.

query Parameters
ttl-auto
boolean

If set to true on document update or patch, ensures that the time-to-live for the updated portion of the document will match the parent document. Requires a read-before-write if set to true.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON of a sub-document.

object

Responses

Request samples

Content type
application/json
{
  • "competitors": 100,
  • "start_date": "2022-08-15"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Delete a path in a document

Delete the data at a path in a document by ID.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

document-path
required
string

The path in the JSON that you want to target. Use path delimiter / to target sub-paths, for example to get a JSON object under $.account.user use account/user. Use \ to escape periods, commas, and asterisks.

query Parameters
profile
boolean

Whether to include query profiling information in the response (advanced).

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "description": "Request invalid: payload not provided."
}

Patch a path in a document

Patch data at a path in a document by ID. Merges data at the path with requested data, assumes that the data at the path is already an object. Note that operation is not allowed if a JSON schema exist for a target collection.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

document-path
required
string

The path in the JSON that you want to target. Use path delimiter / to target sub-paths, for example to get a JSON object under $.account.user use account/user. Use \ to escape periods, commas, and asterisks.

query Parameters
ttl-auto
boolean

If set to true on document update or patch, ensures that the time-to-live for the updated portion of the document will match the parent document. Requires a read-before-write if set to true.

profile
boolean

Whether to include query profiling information in the response (advanced).

Request Body schema: application/json

The JSON of a patch.

object

Responses

Request samples

Content type
application/json
{
  • "location": "Berlin"
}

Response samples

Content type
application/json
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d"
}

Executes a a built-in function against a path in a document

Execute a built-in function (e.g. $push and $pop) against a value in this document. Performance may vary.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

document-id
required
string

The ID of the document.

document-path
required
string

The path in the JSON that you want to target. Use path delimiter / to target sub-paths, for example to get a JSON object under $.account.user use account/user. Use \ to escape periods, commas, and asterisks.

query Parameters
profile
boolean

Whether to include query profiling information in the response (advanced).

raw
boolean

Unwrap results.

Request Body schema: application/json

The request body for executing a built-in function.

operation
required
string\$pop|\$push|\$set

The operation to execute

object or null

The value to use for the operation

Responses

Request samples

Content type
application/json
Example
{
  • "operation": "$pop"
}

Response samples

Content type
application/json

Note that data property content depends on the executed function:

  • $pop - returns the item that was popped from the array
  • $push - returns the complete array, including the item that was pushed
{
  • "documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
  • "data": 123
}

Json Schemas

Json schema management operations.

Get a JSON schema

Get a JSON schema from a collection.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

Responses

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Attach a JSON schema

Assign a JSON schema to a collection. This will erase any schema that already exists.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

Request Body schema: application/json

The JSON schema to attach

empty
boolean
valueNode
boolean
containerNode
boolean
missingNode
boolean
array
boolean
object
boolean
nodeType
string (JsonNodeType)
Enum: "ARRAY" "BINARY" "BOOLEAN" "MISSING" "NULL" "NUMBER" "OBJECT" "POJO" "STRING"
pojo
boolean
number
boolean
integralNumber
boolean
floatingPointNumber
boolean
short
boolean
int
boolean
long
boolean
float
boolean
double
boolean
bigDecimal
boolean
bigInteger
boolean
textual
boolean
boolean
boolean
null
boolean
binary
boolean

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "schema": {
    }
}

Collections

Collection management operations.

List collections

List all available collections in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

query Parameters
raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a collection

Create a new empty collection in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

Request Body schema: application/json
name
required
string\w+

The name of the collection.

Responses

Request samples

Content type
application/json
{
  • "name": "events"
}

Response samples

Content type
application/json
Example
{
  • "code": 400,
  • "description": "Could not create collection events-collection, it has invalid characters. Valid characters are alphanumeric and underscores."
}

Delete a collection

Delete a collection in a namespace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

Responses

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}

Upgrade a collection

Upgrade a collection in a namespace.

WARNING: This endpoint is expected to cause some down-time for the collection you choose.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

collection
required
string\w+
Example: events

The name of the collection.

query Parameters
raw
boolean

Unwrap results.

Request Body schema: application/json
upgradeType
required
object
Value: "SAI_INDEX_UPGRADE"

The upgrade type to perform.

Responses

Request samples

Content type
application/json
{
  • "upgradeType": "SAI_INDEX_UPGRADE"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Namespaces

Namespace management operations.

List namespaces

List all available namespaces. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
query Parameters
raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a namespace

Create a new namespace using given replication strategy. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
Request Body schema: application/json

Request body

name
required
string\w+

The name of the namespace.

replicas
integer or null <int32> >= 1
Default: 1

The amount of replicas to use with the SimpleStrategy. Ignored if datacenters is set.

Array of objects or null (Datacenter)

The datacenters within a namespace. Only applies for those namespaces created with NetworkTopologyStrategy.

Responses

Request samples

Content type
application/json
Example
{
  • "name": "cycling",
  • "replicas": 1
}

Response samples

Content type
application/json
{
  • "name": "cycling",
  • "replicas": 1,
  • "datacenters": [
    ]
}

Get a namespace

Retrieve a single namespace specification. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

query Parameters
raw
boolean

Unwrap results.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a namespace

Delete a namespace if exists. Note that a namespace is an equivalent to the Cassandra keyspace.

Authorizations:
Token
path Parameters
namespace
required
string\w+
Example: cycling

The namespace where the collection is located.

Responses

Response samples

Content type
application/json
Example
{
  • "code": 401,
  • "description": "Unauthorized operation.",
  • "grpcStatus": "PERMISSION_DENIED"
}