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 command (/v2)

  • Result

curl --location --request PUT 'https://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 command (/v2)

  • Result

curl -L \
-X GET 'https://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 command (/v2)

  • Result

curl --location --request PATCH 'https://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 command (/v2)

  • Result

curl -L \
-X GET 'https://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!"
  }
}

PATCH updates are upserts. If the document doesn’t exist, it will be created. If it does exist, it will be updated with the new document data.

Another example with PATCH

  • cURL command (/v2)

  • Result

curl --location --request PATCH 'https://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 command (/v2)

  • Result

curl -L \
-X GET 'https://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 command (/v2)

  • Result

curl -X 'PUT' \
  'http://https://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 command (/v2)

  • Result

curl -X 'PATCH' \
  'http://https://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 command (/v2)

  • Result

curl -X GET 'https://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 command (/v2)

  • Result

curl --location --request GET 'https://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 command (/v2)

  • Result

curl --location --request POST 'https://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 command (/v2)

  • Result

curl --location --request POST 'https://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 command (/v2)

  • Result

curl --location --request GET 'https://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"
  ]
}