Update a document
Finds a single document in a collection using filter and sort clauses, and then updates properties in that document. Optionally, if no document matches the filter, inserts a new document.
This method and the method to find and update a document have the same database effect but differ in their return value. This method returns details about the success of the update. The method to find and update a document returns the document that was found and updated.
Result
-
Python
-
TypeScript
-
Java
-
curl
Updates a document that matches the specified parameters and returns an UpdateResult
object that includes details about the success of the operation.
Example response:
UpdateResult(update_info={'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1}, raw_results=...)
Updates a document that matches the specified parameters and returns a promise that resolves to an UpdateOneResult<Schema>
object that includes details about the success of the operation.
Example resolved response:
{ modifiedCount: 1, matchedCount: 1, upsertedCount: 0 }
Updates a document that matches the specified parameters and returns UpdateResults<T>
that includes details about the success of the operation.
Updates a document that matches the specified parameters and returns an object that includes details about the success of the operation.
Example response:
{
"status": {
"matchedCount": 1,
"modifiedCount": 1
}
}
Parameters
-
Python
-
TypeScript
-
Java
-
curl
Name | Type | Summary |
---|---|---|
|
|
A predicate expressed as a dictionary according to the Data API filter syntax.
For example: |
|
|
The update prescription to apply to the document, expressed as a dictionary as per Data API syntax.
For example: |
|
|
See Find a document and Sort clauses. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries. |
|
|
This parameter controls the behavior if there are no matches.
If true and there are no matches, then the operation inserts a new document by applying the |
|
|
A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default. |
Name | Type | Summary |
---|---|---|
|
A filter to select the document to update. For a list of available operators, see Data API operators. For additional examples, see Find a document. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries. |
|
|
The update to apply to the selected document. For examples and a list of available operators, see Find and update a document and Data API operators. |
|
|
The options for this operation. |
Options (UpdateOneOptions
):
Name | Type | Summary |
---|---|---|
|
This parameter controls the behavior if there are no matches.
If true and there are no matches, then the operation inserts a new document by applying the |
|
See Find a document and Sort clauses. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries. |
||
|
The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request. |
Name | Type | Summary |
---|---|---|
|
Criteria list to filter the document. The filter is a JSON object that can contain any valid Data API filter expression. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries. |
|
|
The update prescription to apply to the selected document. For examples and a list of available operators, see Find and update a document and Data API operators. |
Name | Type | Summary |
---|---|---|
|
|
The Data API command to updates a single document matching a query. |
|
|
Used to select the document to be updated.
For a list of available operators, see Data API operators.
For |
|
|
The update prescription to apply to the document.
For example: |
|
|
This parameter controls the behavior if there are no matches.
If true and there are no matches, then the operation inserts a new document by applying the |
Examples
The following examples demonstrate how to update a document in a collection.
Update a document by ID
All documents have a unique _id
property. You can use a filter to find a document with a specific _id
, and then update that document.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{"_id": "101"},
{"$set": {"color": "blue"}}
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{ _id: "101" },
{$set: {color: "blue"}}
);
console.log(result);
})();
package com.datastax.astra.client.collection;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.Update;
import com.datastax.astra.client.model.UpdateResult;
import com.datastax.astra.client.model.Updates;
import java.util.Optional;
public class UpdateOne {
public static void main(String[] args) {
// Get an existing collection
Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
.getDatabase("ASTRA_DB_API_ENDPOINT")
.getCollection("COLLECTION_NAME");
// Update a document
Filter filter = Filters.eq("_id", "101");
Update update = Updates.set("color", "blue");
UpdateResult result = collection.updateOne(filter, update);
System.out.println(result.getMatchedCount());
System.out.println(result.getModifiedCount());
}
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {
"_id": "101"
},
"update": { "$set": { "color": "blue" } }
}
}'
Update a document that matches a filter
You can use a filter to find a document that matches specific criteria.
For example, you can find a document with an isCheckedOut
value of false
and a numberOfPages
value less than 300.
For a list of available filter operators and more examples, see Data API operators.
Filters can use only indexed fields. If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in a filter.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{
"$and": [
{"isCheckedOut": False},
{"numberOfPages": {"$lt": 300}},
]
},
{"$set": {"color": "blue"}}
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{
$and: [
{ isCheckedOut: false },
{ numberOfPages: { $lt: 300 } }
],
},
{$set: {color: "blue"}}
);
console.log(result);
})();
package com.datastax.astra.client.collection;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.Update;
import com.datastax.astra.client.model.UpdateResult;
import com.datastax.astra.client.model.Updates;
import java.util.Optional;
public class UpdateOne {
public static void main(String[] args) {
// Get an existing collection
Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
.getDatabase("ASTRA_DB_API_ENDPOINT")
.getCollection("COLLECTION_NAME");
// Update a document
Filter filter = Filters.and(
Filters.eq("isCheckedOut", false),
Filters.lt("numberOfPages", 300));
Update update = Updates.set("color", "blue");
UpdateResult result = collection.updateOne(filter, update);
System.out.println(result.getMatchedCount());
System.out.println(result.getModifiedCount());
}
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {"$and": [
{"isCheckedOut": false},
{"numberOfPages": {"$lt": 300}}
]},
"update": { "$set": { "color": "blue" } }
}
}'
Update a document that is most similar to a search vector
To find the document whose $vector
value is most similar to a given vector, use a sort with the vector embeddings that you want to match. For more information, see Perform a vector search.
Vector search is only available for vector-enabled collections. For more information, see Vector and vectorize.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{},
{"$set": {"color": "blue"}},
sort={"$vector": [0.1, 0.2, 0.3]},
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{},
{$set: {color: "blue"}},
{ sort: { $vector: [0.1, 0.2, 0.3] } },
);
console.log(result);
})();
The Java client does not support vector search with updateOne
. Instead, you can use findOne
to find the _id
of a document with vector search, and then use updateOne
and the document’s _id
to update the document.
Or, you can use findOneAndUpdate
.
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"sort": {
"$vector": [0.1, 0.2, 0.3]
},
"update": { "$set": { "color": "blue" } }
}
}'
Update a document that is most similar to a search string
To find the document whose $vector
value is most similar to the $vector
value of a given search string, use a sort with the search string that you want to vectorize and match. For more information, see Perform a vector search.
Vector search with vectorize is only available for collections that have vectorize enabled. For more information, see Vector and vectorize.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{},
{"$set": {"color": "blue"}},
sort={"$vectorize": "Text to vectorize"}
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{},
{$set: {color: "blue"}},
{ sort: { $vectorize: "Text to vectorize" } }
);
console.log(result);
})();
The Java client does not support vector search with updateOne
. Instead, you can use findOne
to find the _id
of a document with vector search, and then use updateOne
and the document’s _id
to update the document.
Or, you can use findOneAndUpdate
.
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"sort": { "$vectorize": "Text to vectorize" },
"update": { "$set": { "color": "blue" } }
}
}'
Update multiple properties
You can combine multiple operators and properties in a single call. For the full list of operators, see Data API operators.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{"_id": "101"},
{
"$set": {
"color": "blue",
"classes": ["biology", "algebra", "swimming"]
},
"$unset": {
"phone": ""
},
"$inc": {
"age": 1
}
}
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{ _id: '101' },
{
$set: {
color: "blue",
classes: ["biology", "algebra", "swimming"]
},
$unset: {
phone: ""
},
$inc: {
age: 1
}
}
);
console.log(result);
})();
package com.datastax.astra.client.collection;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.Update;
import com.datastax.astra.client.model.UpdateResult;
import com.datastax.astra.client.model.Updates;
import java.util.Arrays;
import java.util.Optional;
public class UpdateOne {
public static void main(String[] args) {
// Get an existing collection
Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
.getDatabase("ASTRA_DB_API_ENDPOINT")
.getCollection("COLLECTION_NAME");
// Update a document
Filter filter = Filters.eq("_id", "101");
Update update = Updates
.set("color", "blue")
.set("classes", Arrays.asList("biology", "algebra", "swimming"))
.unset("phone")
.inc("age", 1.0);
UpdateResult result = collection.updateOne(filter, update);
System.out.println(result.getMatchedCount());
System.out.println(result.getModifiedCount());
}
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {
"_id": "101"
},
"update": {
"$set": {
"color": "blue",
"classes": ["biology", "algebra", "swimming"]
},
"$unset": {
"phone": ""
},
"$inc": {
"age": 1
}
}
}
}'
Update nested properties
To update a nested property, use dot notation.
For example, field.subfield.subsubfield
.
To update an item in a list, specify a numeric index.
For example, listProperty.3
.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{"_id": "101"},
{
"$set": {
"color": "blue",
"address.city": "Austin",
"classes.2": "biology"
}
}
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{ _id: '101' },
{
$set: {
color: "blue",
"address.city": "Austin",
"classes.2": "biology"
}
}
);
console.log(result);
})();
package com.datastax.astra.client.collection;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.Update;
import com.datastax.astra.client.model.UpdateResult;
import com.datastax.astra.client.model.Updates;
import java.util.Optional;
public class UpdateOne {
public static void main(String[] args) {
// Get an existing collection
Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
.getDatabase("ASTRA_DB_API_ENDPOINT")
.getCollection("COLLECTION_NAME");
// Update a document
Filter filter = Filters.eq("_id", "101");
Update update = Updates
.set("color", "blue")
.set("address.city", "Austin")
.set("classes.2", "biology");
UpdateResult result = collection.updateOne(filter, update);
System.out.println(result.getMatchedCount());
System.out.println(result.getModifiedCount());
}
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {
"_id": "101"
},
"update": {
"$set": {
"color": "blue",
"address.city": "Austin",
"classes.2": "biology"
}
}
}
}'
Insert a new document if no matching document exists
If no document matches the filter criteria, you can use upsert
to specify that a new document should be created.
-
Python
-
TypeScript
-
Java
-
curl
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{
"$and": [
{"isCheckedOut": False},
{"numberOfPages": {"$lt": 300}},
]
},
{"$set": {"color": "blue"}},
upsert=True,
)
print(result)
You can also use the setOnInsert
operator specify additional fields to set if a new document is created:
from astrapy import DataAPIClient
# Get an existing collection
client = DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
database = client.get_database("ASTRA_DB_API_ENDPOINT")
collection = database.get_collection("COLLECTION_NAME")
# Update a document
result = collection.update_one(
{
"$and": [
{"isCheckedOut": False},
{"numberOfPages": {"$lt": 300}},
]
},
{
"$set": {"color": "blue"},
"$setOnInsert": {
"customer.name": "James"
}
},
upsert=True,
)
print(result)
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{
$and: [
{ isCheckedOut: false },
{ numberOfPages: { $lt: 300 } }
],
},
{ $set: {color: "blue"} },
{ upsert: true },
);
console.log(result);
})();
You can also use the setOnInsert
operator specify additional fields to set if a new document is created:
import { DataAPIClient } from '@datastax/astra-db-ts';
// Get an existing collection
const client = new DataAPIClient('ASTRA_DB_APPLICATION_TOKEN');
const database = client.db('ASTRA_DB_API_ENDPOINT');
const collection = database.collection('COLLECTION_NAME');
// Update a document
(async function () {
const result = await collection.updateOne(
{
$and: [
{ isCheckedOut: false },
{ numberOfPages: { $lt: 300 } }
],
},
{
$set: {color: "blue"},
$setOnInsert: {
"customer.name": "James"
}
},
{ upsert: true },
);
console.log(result);
})();
package com.datastax.astra.client.collection;
import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.model.Document;
import com.datastax.astra.client.model.Filter;
import com.datastax.astra.client.model.Filters;
import com.datastax.astra.client.model.Update;
import com.datastax.astra.client.model.UpdateResult;
import com.datastax.astra.client.model.Updates;
import java.util.Optional;
public class UpdateOne {
public static void main(String[] args) {
// Get an existing collection
Collection<Document> collection = new DataAPIClient("ASTRA_DB_APPLICATION_TOKEN")
.getDatabase("ASTRA_DB_API_ENDPOINT")
.getCollection("COLLECTION_NAME");
// Update a document
Filter filter = Filters.and(
Filters.eq("isCheckedOut", false),
Filters.lt("numberOfPages", 300));
Update update = Updates.set("color", "blue");
UpdateOneOptions options = new UpdateOneOptions().upsert(true);
UpdateResult result = collection.updateOne(filter, update, options);
System.out.println(result.getMatchedCount());
System.out.println(result.getModifiedCount());
System.out.println(result.getUpsertedId());
}
}
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {"$and": [
{"isCheckedOut": false},
{"numberOfPages": {"$lt": 300}}
]},
"update": { "$set": { "color": "blue" } },
"options": { "upsert": true }
}
}'
You can also use the setOnInsert
operator specify additional fields to set if a new document is created:
curl -sS -L -X POST "ASTRA_DB_API_ENDPOINT/api/json/v1/ASTRA_DB_KEYSPACE/ASTRA_DB_COLLECTION" \
--header "Token: ASTRA_DB_APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"updateOne": {
"filter": {"$and": [
{"isCheckedOut": false},
{"numberOfPages": {"$lt": 300}}
]},
"update": {
"$set": { "color": "blue" },
"$setOnInsert": {
"customer.name": "James"
}
},
"options": { "upsert": true }
}
}'
Client reference
-
Python
-
TypeScript
-
Java
-
curl
For more information, see the client reference.
For more information, see the client reference.
For more information, see the client reference.
Client reference documentation is not applicable for HTTP.