Stargate Document API (2.0.18)

Download OpenAPI specification:Download

URL: https://stargate.io License: Apache 2.0 Terms of Service

The Stargate Document API modifies and queries 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

Search documents result

{"data": [{"location": "London",
"race": {"competitors": 100,
"start_date": "2022-08-15"
}
},
{"location": "Barcelona",
"race": {"competitors": 30,
"start_date": "2022-09-26"
}
}
],
"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

Payload

Content type

application/json

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

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

Payload

Content type

application/json

[{"location": "London",
"race": {"competitors": 100,
"start_date": "2022-08-15"
}
},
{"location": "Barcelona",
"race": {"competitors": 30,
"start_date": "2022-09-26"
}
}
]

Response samples

Content type

application/json

{"documentIds": ["822dc277-9121-4791-8b01-da8154e67d5d, 6334dft4-9153-3642-4f32-da8154e67d5d"
]
}

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

Single document

{"documentId": "822dc277-9121-4791-8b01-da8154e67d5d",
"data": {"location": "London",
"race": {"competitors": 100,
"start_date": "2022-08-15"
}
}
}

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

Payload

Content type

application/json

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

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

400
401
404
500
503

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

Payload

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

Payload

Content type

application/json

Example

Function `$pop`

{"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

Sub-document

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": {"race": {"competitors": 100,
"start_date": "2022-08-15"
}
}
}

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

Payload

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

400
401
404
500
503

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

Payload

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

Payload

Content type

application/json

Example

Function `$pop`

{"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

200
401
404
500
503

Content type

application/json

{"schema": {"empty": true,
"valueNode": true,
"containerNode": true,
"missingNode": true,
"array": true,
"object": true,
"nodeType": "ARRAY",
"pojo": true,
"number": true,
"integralNumber": true,
"floatingPointNumber": true,
"short": true,
"int": true,
"long": true,
"float": true,
"double": true,
"bigDecimal": true,
"bigInteger": true,
"textual": true,
"boolean": true,
"null": true,
"binary": true
}
}

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

Payload

Content type

application/json

{"$schema": "https://json-schema.org/draft/2019-09/schema"
}

Response samples

Content type

application/json

{"schema": {"empty": true,
"valueNode": true,
"containerNode": true,
"missingNode": true,
"array": true,
"object": true,
"nodeType": "ARRAY",
"pojo": true,
"number": true,
"integralNumber": true,
"floatingPointNumber": true,
"short": true,
"int": true,
"long": true,
"float": true,
"double": true,
"bigDecimal": true,
"bigInteger": true,
"textual": true,
"boolean": true,
"null": true,
"binary": true
}
}

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": [{"name": "cycling",
"upgradeAvailable": false,
"upgradeType": "null"
}
]
}

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

Payload

Content type

application/json

{"name": "events"
}

Response samples

Content type

application/json

Example

Invalid collection name

{"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

401
404
500
503

Content type

application/json

Example

Unauthorized

{"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

Payload

Content type

application/json

{"upgradeType": "SAI_INDEX_UPGRADE"
}

Response samples

Content type

application/json

{"data": {"name": "cycling",
"upgradeAvailable": false,
"upgradeType": "null"
}
}

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

200
401
500
503

Content type

application/json

{"data": [{"name": "cycling",
"replicas": 1,
"datacenters": [{"name": "dc1",
"replicas": 3
}
]
}
]
}

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

Payload

Content type

application/json

Example

With SimpleStrategy

{"name": "cycling",
"replicas": 1
}

Response samples

Content type

application/json

{"name": "cycling",
"replicas": 1,
"datacenters": [{"name": "dc1",
"replicas": 3
}
]
}

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

200
401
404
500
503

Content type

application/json

{"data": {"name": "cycling",
"replicas": 1,
"datacenters": [{"name": "dc1",
"replicas": 3
}
]
}
}

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

401
404
500
503

Content type

application/json

Example

Unauthorized

{"code": 401,
"description": "Unauthorized operation.",
"grpcStatus": "PERMISSION_DENIED"
}