Reading documents
Retrieving a specified document
Let’s check that the data was inserted for a particular document.
Send a GET
request to /api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}
to retrieve the document:
curl -L \
-X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/{docid}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"documentId":"{docid}",
"data":{
"id":"some-stuff",
"other":"This is nonsensical stuff."
}
}
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 can
retrieve information from a document or a sub-document.
Retrieving a document using a where clause
Now let’s search for a particular document using a where
clause.
Send a GET
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause}
to get the same information:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"firstname":\{"$eq":"Janet"\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data":{
"Janet":{
"email":"janet.doe@gmail.com",
"favorite color":"grey",
"firstname":"Janet",
"lastname":"Doe"
}
}
}
Note that the where
clause must be url encoded, so curly brackets are escaped
with \
and spaces must be replaced with %20
.
Also, the full document is returned, as opposed to the value of the field specified in the
{document-path}
like the next command.
Read with where
You can also search with a multiple where
clause.
Send a GET
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}?{where-clause}
to get the same information:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"firstname":\{"$eq":"Janet"\},"lastname":\{"$eq":"Doe"\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data":{
"Janet":{
"email":"janet.doe@gmail.com",
"favorite color":"grey",
"firstname":"Janet",
"lastname":"Doe"
}
}
}
Note that the where
clause must be url encoded, so curly brackets are escaped
with \
and spaces must be replaced with %20
.
Also, the full document is returned, as opposed to the value of the field specified in the
{document-path}
like the next command.
You can also retrieve documents using a WHERE
clause that searches sub-documents:
curl -L -X GET 'lhttps://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"weights.type":\{"$eq":"bench%20press"\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data":{
"Joey":{
"firstname":"Joey",
"lastname":"Doe",
"weights":{
"reps":15,
"type":"bench press",
"weight":150
}
}
},
"pageState":null
}
Multiple where
can be used in a variety of cases.
Here, a numerical value between to values is sought:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"weights.reps":\{"$gt":12\},"weights.reps":\{"$lt":20\}\}' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data": {
"Joey": {
"firstname": "Joey",
"lastname": "Doe",
"weights": {
"reps": 15,
"type": "bench press",
"weight": 150
}
}
}
}
Retrieving all documents
Let’s check that the document was inserted. Send a GET
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}
to retrieve
all the documents:
curl --location \
--request GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?page-size=3' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"data":{
"Joey":{
"firstname":"Joey",
"lastname":"Doe",
"weights":{
"reps":15,
"type":"bench press",
"weight":150
}
},
"Janet":{
"email":"janet.doe@gmail.com",
"favorite color":"grey",
"firstname":"Janet",
"lastname":"Doe"
},
"{docid}":{
"id":"some-stuff",
"other":"This is nonsensical stuff."
}
}
}
The page-size
parameter is included to get all the documents, rather than the
last inserted document.
Retrieving all documents with Paging
For large collections, you can page a subset of the results. In this example, page-size is set to 5. Send a GET request to /api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}page-size=5 to retrieve the first five documents (a page) in the collection:
curl --location \
--request GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?page-size=5' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"pageState":"JGNlYjczMDc5LTE1NTItNGQyNS1hM2ExLWE2MzgxNWVlYTAyMADwf_____B_____",
"data":{
"58b12778-0efd-466e-89bf-66a4c99adee1":{"author":"Tom Clancy","title":"Red Rabbit"},
"77fe8690-f8d4-43b8-b1c9-a328318d4eae":{"author":"Tom Clancy","title":"Every Man a Tiger"},
"3177f86c-a633-4302-92a5-de4c15ab5840":{"author":"Tom Clancy","title":"Rainbow Six"},
"cefc7117-fc73-47b8-a965-099cf3a59269":{"author":"Tom Clancy","title":"Clear and Present Danger"},
"ceb73079-1552-4d25-a3a1-a63815eea020":{"author":"Tom Clancy","title":"The Cardinal of the Kremlin"}
}
}
Pay close attention to the pageState
value in the results. The pageState
is
a string representation 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 -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Joey/weights/type' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{"documentId":"Joey","data":"bench press"}
In this case, the sub-document weights
is the
document-path
specified to retrieve that data about the reps
, type
, and
weight
.
curl --location --request GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Joey/weights' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
"documentId":"Joey",
"data":{
"reps":15,
"type":"bench press",
"weight":150
}
}
Retrieving a specific portion of a document with document-path
Let’s add another record for the next example:
curl -L -X PUT 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Martha' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json' \
--data '{
"firstname": "Martha",
"lastname": "Smith",
"weights": {
"type": "bench press",
"weight": 125,
"reps": 12
}
}'
{"documentId":"Martha"}
To find particular values, send a GET
request to
/api/rest/v2/namespaces/{namespace_name}/collections/{collections_name}/{document-id}/{document-path}
to retrieve all the users that have, say, weight reps between 11 and 16:
curl -L -X GET 'https://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"weights.*":\{"$gt":11\},"weights.*":\{"$lt":16\}\}&page-size=3' \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json"
{
"data": {
"Joey": {
"firstname": "Joey",
"lastname": "Doe",
"weights": {
"reps": 15,
"type": "bench press",
"weight": 150
}
},
"Martha": {
"firstname": "Martha",
"lastname": "Smith",
"weights": {
"reps": 12,
"type": "bench press",
"weight": 125
}
}
}
}