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)
cURL command (/v1)
Result

curl --location --request PUT 'http://localhost:8180/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."
}'

curl --location --request PUT 'http://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)
cURL command (/v1)
Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

curl -L \
-X GET 'http://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)
cURL command (/v1)
Result

curl --location --request PATCH 'http://localhost:8180/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!"
}'

curl --location --request PATCH 'http://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)
cURL command (/v1)
Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

curl -L \
-X GET 'http://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)
cURL command (/v1)
Result

curl --location --request PATCH 'http://localhost:8180/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"
  ]
}'

curl --location --request PATCH 'http://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)
cURL command (/v1)
Result

curl -L \
-X GET 'http://localhost:8180/v2/namespaces/test/collections/library/2545331a-aaad-45d2-b084-9da3d8f4c311' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

curl -L \
-X GET 'http://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)
cURL command (/v1)
Result

curl -X 'PUT' \
  'http://localhost:8180/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" }'

curl -X 'PUT' \
  'http://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)
cURL command (/v1)
Result

curl -X 'PATCH' \
  'http://http://localhost:8180/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"
    ]
  }
}'

curl -X 'PATCH' \
  'http://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)
cURL command (/v1)
Result

curl -X GET 'http://localhost:8180/v2/schemas/namespaces/test/functions' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json'

curl -X GET 'http://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)
cURL command (/v1)
Result

curl --location --request GET 'http://localhost:8180/v2/namespaces/test/collections/library/native-son-doc-id/book/genre' \
--header "X-Cassandra-Token: $AUTH_TOKEN" \
--header 'Content-Type: application/json' \

curl --location --request GET 'http://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)
cURL command (/v1)
Result

curl --location --request POST 'http://localhost:8180/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" 
}'

curl --location --request POST 'http://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)
cURL command (/v1)
Result

curl --location --request POST 'http://localhost:8180/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)
cURL command (/v1)
Result

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