Reading documents

Retrieving all documents

Let’s check that the document was inserted. Send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness to retrieve all the documents:

  • cURL command (/v2)

  • Result

curl -sL \
--request GET --url http://$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. The pageState is useful for pagination of the results in queries.

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/myworld/collections/fitness/{document-id} to retrieve the document:

  • cURL command (/v2)

  • Result

curl -sL \
-X GET --url http://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness/Janet \
--header "X-Cassandra-Token: $ASTRA_DB_APPLICATION_TOKEN" \
--header 'Content-Type: application/json'
{
  "documentId": "Janet",
  "data": {
    "email": "janet.doe@gmail.com",
    "favorite color": "grey",
    "firstname": "Janet",
    "lastname": "Doe"
  }
}

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.

Operator options for reading with a WHERE clause

Most data retrieval uses a WHERE clause containing operators to designate a range of rows to return.

The operators available are:

  • eq (equal)

  • notEq (not equal) - limited use

  • gt (greater than)

  • gte (greater than or equal to)

  • lt (less than)

  • lte (less than or equal to)

  • in (within) - limited use

  • nin (not within) - limited use

The WHERE clause can use any of these operators, as applicable to the data type defined. The storage schema used by the Document API internally indexes all values, so any column can be used with an operator.

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/myworld/collections/fitness?{where-clause} to get the same information:

  • cURL command (/v2)

  • Result

curl -sL -X  GET --url 'http://$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.

You can also search with a multiple where clause. Send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness?{where-clause} to get the same information:

  • cURL command (/v2)

  • Result

curl -sL -X  GET --url 'http://$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"
		}
	}
}

You can also retrieve documents using a WHERE clause that searches sub-documents:

  • cURL command (/v2)

  • Result

curl -sL -X  GET 'http://$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
			}
		}
	}
}

Multiple where can be used in a variety of cases. Here, a numerical value between to values is sought:

  • cURL command (/v2)

  • Result

curl -sL -X  GET 'http://$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 a specific portion of a document with document-path

To find a particular value, send a GET request to /api/rest/v2/namespaces/myworld/collections/fitness/{document-id}/{document-path} to retrieve the type of weights Joey has done in his workout:

  • cURL command (/v2)

  • Result

curl -sL -X  GET --url http://$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 command (/v2)

  • Result

curl -sL --request GET --url http://$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 command (/v2)

  • Result

curl -sL -X PUT 'http://$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/myworld/collections/fitness{document-path} to retrieve all the users that have, say, weight reps between 11 and 16:

  • cURL command (/v2)

  • Result

curl -sL -X  GET --url 'http://$ASTRA_CLUSTER_ID-$ASTRA_REGION.apps.astra.datastax.com/api/rest/v2/namespaces/myworld/collections/fitness?where=\{"*.reps":\{"$gt":11\},"*.reps":\{"$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
      }
    }
  }
}