Replace documents reference

Documents represent a single row or record of data in Astra DB Serverless databases. You use the Collection class to work with documents through the Data API. For instructions to get a Collection object, see the Collections reference.

Astra DB APIs use the term keyspace to refer to both namespaces and keyspaces.

For general information about working with documents, including common operations and operators, see the Documents reference.

Prerequisites

Review the prerequisites and other information in Intro to Astra DB APIs.
Create a Serverless (Vector) database.
Learn how to instantiate a DataAPIClient object and connect to your database.

Find and replace a document

Find one document that matches a filter condition, replace it with a new document, and then return the document itself. This command is similar to Find and update a document.

Sort and filter operations can use only indexed fields.

If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

Python
TypeScript
Java
curl

For more information, see the Client reference.

Find a document matching a filter condition, and then replace the matching document with the given replacement:

collection.find_one_and_replace(
    {"_id": "rule1"}, # filter
    {"text": "some animals are more equal!"}, # replacement
)

Locate and replace a document, returning the document itself, and create a new one if no match is found:

collection.find_one_and_replace(
    {"_id": "rule1"},
    {"text": "some animals are more equal!"},
    upsert=True,
)

Locate and replace the document most similar to a query vector from either $vector or $vectorize. In this example, the filter object is empty, and only the sort object is used to locate the document to replace. Including the empty filter object ensures that the replacement object is read correctly.

collection.find_one_and_replace(
    {}, # empty filter
    {"name": "Zoo", "desc": "the new best match"}, # replacement
    sort={"$vector": [0.1, 0.2, 0.3]}, # sort object, to locate the document to replace
)

Returns:

Dict[str, Any] - Either the original or the replaced document. The exact fields returned depend on the projection parameter. If you request the original document, and there are no matches, then None is returned.

Example response

{'_id': 'rule1', 'text': 'all animals are equal'}

Parameters:

Name Type Summary

filter

Dict[str, Any]

A predicate expressed as a dictionary according to the Data API filter syntax. For example: {}, {"name": "John"}, {"price": {"$lt": 100}}, {"$and": [{"name": "John"}, {"price": {"$lt": 100}}]}. For a list of available operators, see Data API operators. For additional examples, see Find documents using filtering options.

replacement

Dict[str, Any]

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

Find and replace is intended to replace an existing document and retain the original document’s _id. An error occurs if the provided replacement has a different _id. In most cases, it is best to omit the _id field from the replacement.

projection

Optional[Union[Iterable[str], Dict[str, bool]]]

See Find a document and Projection operations.

sort

Optional[Dict[str, Any]]

See Find a document and Sort operations.

upsert

bool = False

This parameter controls the behavior if there are no matches. If true and there are no matches, then the operation inserts the replacement as a new document. If false and there are no matches, then the operation silently does nothing.

return_document

str

A flag controlling what document is returned. If set to ReturnDocument.BEFORE or the string "before", then the original document is returned. If set to ReturnDocument.AFTER or the string "after", then the replacement document is returned. The default is "before".

max_time_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.my_collection
import astrapy

collection.insert_one({"_id": "rule1", "text": "all animals are equal"})

collection.find_one_and_replace(
    {"_id": "rule1"},
    {"text": "some animals are more equal!"},
)
# prints: {'_id': 'rule1', 'text': 'all animals are equal'}
collection.find_one_and_replace(
    {"text": "some animals are more equal!"},
    {"text": "and the pigs are the rulers"},
    return_document=astrapy.constants.ReturnDocument.AFTER,
)
# prints: {'_id': 'rule1', 'text': 'and the pigs are the rulers'}
collection.find_one_and_replace(
    {"_id": "rule2"},
    {"text": "F=ma^2"},
    return_document=astrapy.constants.ReturnDocument.AFTER,
)
# (returns None for no matches)
collection.find_one_and_replace(
    {"_id": "rule2"},
    {"text": "F=ma"},
    upsert=True,
    return_document=astrapy.constants.ReturnDocument.AFTER,
    projection={"_id": False},
)
# prints: {'text': 'F=ma'}

For more information, see the Client reference.

Find a document matching a filter condition, and then replace the matching document with the given replacement:

const docBefore = await collection.findOneAndReplace(
  { _id: 123 }, // filter
  { text: 'some animals are more equal!' }, // replacement
);

Locate and replace a document, returning the document itself, and creating a new one if no match is found:

const docBefore = await collection.findOneAndReplace(
  { _id: 123 },
  { text: 'some animals are more equal!' },
  { upsert: true  },
);

const docBefore = await collection.findOneAndReplace(
  {}, // empty filter
  { name: 'Zoe', desc: 'The new best match' }, // replacement
  { sort: { $vector: [0.1, 0.2, 0.3] } }, // sort object, to locate the document to replace
);

Parameters:

Name Type Summary

filter

Filter<Schema>

A filter to select the document to replace. For a list of available operators, see Data API operators. For additional examples, see Find documents using filtering options.

replacement

NoId<Schema>

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

options

FindOneAndReplaceOptions

The options for this operation.

Options (FindOneAndReplaceOptions):

Name Type Summary

Name	Type	Summary
returnDocument	`'before' \| 'after'`	Specifies whether to return the original (`'before'`) or replacement (`'after'`) document.
upsert?	`boolean`	This parameter controls the behavior if there are no matches. If true and there are no matches, then the operation inserts the `replacement` as a new document. If false and there are no matches, then the operation silently does nothing.
projection?	`Projection`	See Find a document and Projection operations.
sort?	`Sort`	See Find a document and Sort operations.
maxTimeMS?	`number`	The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.
includeResultMetadata?	`boolean`	When true, returns `ok: 1`, in addition to the document, if the command executed successfully.

returnDocument

'before' | 'after'

Specifies whether to return the original ('before') or replacement ('after') document.

upsert?

boolean

projection?

Projection

See Find a document and Projection operations.

sort?

Sort

See Find a document and Sort operations.

maxTimeMS?

number

The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.

includeResultMetadata?

boolean

When true, returns ok: 1, in addition to the document, if the command executed successfully.

Returns:

Promise<WithId<Schema> | null> - The document before/after the update, depending on the type of returnDocument, or null if no matches are found.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts';

// Reference an untyped collection
const client = new DataAPIClient('TOKEN');
const db = client.db('ENDPOINT', { keyspace: 'KEYSPACE' });
const collection = db.collection('COLLECTION');

(async function () {
  // Insert some document
  await collection.insertOne({ _id: 'rule1', text: 'all animals are equal' });

  // { _id: 'rule1', text: 'all animals are equal' }
  await collection.findOneAndReplace(
    { _id: 'rule1' },
    { text: 'some animals are more equal!' },
    { returnDocument: 'before' }
  );

  // { _id: 'rule1', text: 'and the pigs are the rulers' }
  await collection.findOneAndReplace(
    { text: 'some animals are more equal!' },
    { text: 'and the pigs are the rulers' },
    { returnDocument: 'after' }
  );

  // null
  await collection.findOneAndReplace(
    { _id: 'rule2' },
    { text: 'F=ma^2' },
    { returnDocument: 'after' }
  );

  // { text: 'F=ma' }
  await collection.findOneAndReplace(
    { _id: 'rule2' },
    { text: 'F=ma' },
    { upsert: true, returnDocument: 'after', projection: { _id: false } }
  );
})();

Operations on documents are performed at the Collection level. Collection is a generic class with the default type of Document. You can specify your own type, and the object is serialized by Jackson. For more information, see the Client reference.

Most methods have synchronous and asynchronous flavors, where the asynchronous version is suffixed by Async and returns a CompletableFuture:

// Synchronous
Optional<T> findOneAndReplace(Filter filter, T replacement);
Optional<T> findOneAndReplace(Filter filter, T replacement, FindOneAndReplaceOptions options);

// Asynchronous
CompletableFuture<Optional<T>> findOneAndReplaceAsync(Filter filter, T replacement);
CompletableFuture<Optional<T>> findOneAndReplaceAsync(Filter filter, T replacement, FindOneAndReplaceOptions options);

Returns:

Optional<T> - Return the a document that matches the filter. Whether returnDocument is set to before or after it will return the document before or after update accordingly.

Parameters:

Name Type Summary

filter (optional)

Filter

Filter criteria to find the document to replace. The filter is a JSON object that can contain any valid Data API filter expression. For a list of available operators, see Data API operators. For examples and options, including projection and sort, see Find documents using filtering options.

replacement

T

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

options (optional)

FindOneAndReplaceOptions

Set the different options for the find and replace operation, including the following:

sort(): See Find a document and Sort operations.
projection(): See Find a document and Projection operations.
upset(): Controls the behavior if there are no matches. If true and there are no matches, then the operation inserts the replacement as a new document. If false and there are no matches, then the operation silently does nothing.
returnDocument*(): Specifies whether to return the original (returnDocumentBefore()) or replacement (returnDocumentAfter()) document.

Example:

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.FindOneAndReplaceOptions;
import com.datastax.astra.client.model.Projections;
import com.datastax.astra.client.model.Sorts;

import java.util.Optional;

import static com.datastax.astra.client.model.Filters.lt;

public class FindOneAndReplace {
    public static void main(String[] args) {
        Collection<Document> collection = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT")
                .getCollection("COLLECTION_NAME");

        // Building a filter
        Filter filter = Filters.and(
                Filters.gt("field2", 10),
                lt("field3", 20),
                Filters.eq("field4", "value"));

        FindOneAndReplaceOptions options = new FindOneAndReplaceOptions()
                .projection(Projections.include("field1"))
                .sort(Sorts.ascending("field1"))
                .upsert(true)
                .returnDocumentAfter();

        Document docForReplacement = new Document()
                .append("field1", "value1")
                .append("field2", 20)
                .append("field3", 30)
                .append("field4", "value4");

        // It will return the document before deleting it
        Optional<Document> docBeforeReplace = collection
                .findOneAndReplace(filter, docForReplacement, options);
    }
}

Example with sort and projection:

 FindOneAndReplaceOptions options = FindOneAndReplaceOptions.Builder
  .projection(Projections.include("field1"))
  .sort(Sorts.ascending("field1"))
  .upsert(true)
  .returnDocumentAfter();

findOneAndReplace doesn’t support dot notation in the replacement object.

Find a document matching a filter condition, and then replace that document with a new one:

curl -sS --location -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 '{
  "findOneAndReplace": {
    "filter": { "_id": "14" },
    "replacement": { "customer": { "name": "Ann Jones" }, "account": { "status": "inactive } }
  }
}' | jq

Locate and replace a document or insert a new one if no match is found:

curl -sS --location -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 '{
  "findOneAndReplace": {
    "filter": { "_id": "16" },
    "replacement": { "customer": { "name": "Ann Jones" }, "account": { "status": "inactive } },
    "options": { "upsert": true }
  }
}' | jq

Locate and replace the document most similar to a query vector from either $vector or $vectorize:

curl -sS --location -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 '{
  "findOneAndReplace": {
    "sort": { "$vector": [0.1, 0.2, 0.3] },
    "replacement": { "customer": { "name": "Ann Jones" }, "account": { "status": "inactive } },
    "projection": { "$vector": 1 },
    "options": { "returnDocument": "after" }
  }
}' | jq

Parameters:

Name Type Summary

findOneAndReplace

command

The Data API command to find and replace one document in a collection based on filter, sort, replacement, projection, and options.

sort, filter

object

Search criteria to find the document to replace. For a list of available operators, see Data API operators. For examples and parameters, see Find a document and Sort operations.

replacement

object

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

projection

object

Select a subset of fields to include in the response for the returned document. If empty or unset, the default projection is used. The default projection doesn’t always include all document fields. For more information and examples, see Projection operations.

options.upsert

boolean

options.returnDocument

string

A flag controlling what document is returned. If set to "before", then the original document is returned. If set to "after", then the replacement document is returned. The default is "before".

Returns:

A successful response returns an object representing the original or replacement document, based on the returnDocument and projection options.

Replace a document

Find one document that matches a filter condition, and then replace it with a new document.

replaceOne is similar to findOneAndReplace, except that the response includes only the result of the operation. The response doesn’t include a document object, and the request doesn’t support response-related parameters, such as projection or returnDocument.

Sort and filter operations can use only indexed fields.

If you apply selective indexing when you create a collection, you can’t reference non-indexed fields in sort or filter queries.

Python
TypeScript
Java
curl

For more information, see the Client reference.

Find a document matching a filter condition, and then replace the matching document with the given replacement:

replace_result = collection.replace_one(
    {"Marco": {"$exists": True}}, # filter
    {"Buda": "Pest"}, # replacement
)

Locate and replace a document or create a new one if no match is found:

replace_result = collection.replace_one(
    {"Marco": {"$exists": True}},
    {"Buda": "Pest"},
    upsert=True,
)

collection.replace_one(
    {}, # empty filter
    {"name": "Zoo", "desc": "the new best match"}, # replacement
    sort={"$vector": [0.1, 0.2, 0.3]}, # sort object, to locate the document to replace
)

Returns:

UpdateResult - An object representing the response from the database after the replace operation. It includes information about the operation.

Example response

UpdateResult(update_info={'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1}, raw_results=...)

Parameters:

Name Type Summary

filter

Dict[str, Any]

replacement

Dict[str, Any]

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

sort

Optional[Dict[str, Any]]

See Find a document and Sort operations.

upsert

bool = False

max_time_ms

Optional[int]

A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

Example:

from astrapy import DataAPIClient
client = DataAPIClient("TOKEN")
database = client.get_database("API_ENDPOINT")
collection = database.my_collection

collection.insert_one({"Marco": "Polo"})
collection.replace_one({"Marco": {"$exists": True}}, {"Buda": "Pest"})
# prints: UpdateResult(update_info={'n': 1, 'updatedExisting': True, 'ok': 1.0, 'nModified': 1}, raw_results=...)
collection.find_one({"Buda": "Pest"})
# prints: {'_id': '8424905a-...', 'Buda': 'Pest'}
collection.replace_one({"Mirco": {"$exists": True}}, {"Oh": "yeah?"})
# prints: UpdateResult(update_info={'n': 0, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0}, raw_results=...)
collection.replace_one({"Mirco": {"$exists": True}}, {"Oh": "yeah?"}, upsert=True)
# prints: UpdateResult(update_info={'n': 1, 'updatedExisting': False, 'ok': 1.0, 'nModified': 0, 'upserted': '931b47d6-...'}, raw_results=...)

For more information, see the Client reference.

Find a document matching a filter condition, and then replace the matching document with the given replacement:

const result = await collection.replaceOne(
  { 'Marco': 'Polo' }, // filter
  { 'Buda': 'Pest' }, // replacement
);

Locate and replace a document or create a new one if no match is found:

const result = await collection.replaceOne(
  { 'Marco': 'Polo' },
  { 'Buda': 'Pest' },
  { upsert: true },
);

const result = await collection.replaceOne(
  {}, // empty filter
  { name: "Zoe", desc: "The new best match" }, // replacement
  { sort: { $vector: [0.1, 0.2, 0.3] } }, // sort object, to locate the document to replace
);

Parameters:

Name Type Summary

filter

Filter<Schema>

A filter to select the document to replace. For a list of available operators, see Data API operators. For additional examples, see Find documents using filtering options.

replacement

NoId<Schema>

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

options?

ReplaceOneOptions

The options for this operation.

Options (ReplaceOneOptions):

Name Type Summary

Name	Type	Summary
upsert?	`boolean`	This parameter controls the behavior if there are no matches. If true and there are no matches, then the operation inserts the `replacement` as a new document. If false and there are no matches, then the operation silently does nothing.
sort?	`Sort`	See Find a document and Sort operations.
maxTimeMS?	`number`	The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.

upsert?

boolean

sort?

Sort

See Find a document and Sort operations.

maxTimeMS?

number

The maximum time in milliseconds that the client should wait for the operation to complete each underlying HTTP request.

Returns:

Promise<ReplaceOneResult<Schema>> - The result of the replacement operation.

Example:

import { DataAPIClient } from '@datastax/astra-db-ts';

// Reference an untyped collection
const client = new DataAPIClient('TOKEN');
const db = client.db('ENDPOINT', { keyspace: 'KEYSPACE' });
const collection = db.collection('COLLECTION');

(async function () {
  // Insert some document
  await collection.insertOne({ 'Marco': 'Polo' });

  // { modifiedCount: 1, matchedCount: 1, upsertedCount: 0 }
  await collection.replaceOne(
    { 'Marco': { '$exists': true } },
    { 'Buda': 'Pest' }
  );

  // { _id: '3756ce75-aaf1-430d-96ce-75aaf1730dd3', Buda: 'Pest' }
  await collection.findOne({ 'Buda': 'Pest' });

  // { modifiedCount: 0, matchedCount: 0, upsertedCount: 0 }
  await collection.replaceOne(
    { 'Mirco': { '$exists': true } },
    { 'Oh': 'yeah?' }
  );

  // { modifiedCount: 0, matchedCount: 0, upsertedId: '...', upsertedCount: 1 }
  await collection.replaceOne(
    { 'Mirco': { '$exists': true } },
    { 'Oh': 'yeah?' },
    { upsert: true }
  );
})();

Most methods have synchronous and asynchronous flavors, where the asynchronous version is suffixed by Async and returns a CompletableFuture:

// Synchronous
UpdateResult replaceOne(Filter filter, T replacement);
UpdateResult replaceOne(Filter filter, T replacement, ReplaceOneOptions options);

// Asynchronous
CompletableFuture<UpdateResult> replaceOneAsync(Filter filter, T replacement);
CompletableFuture<UpdateResult> replaceOneAsync(Filter filter, T replacement, ReplaceOneOptions options);

Returns:

UpdateResult - Return a wrapper object with the result of the operation. The object contains the number of documents matched (matchedCount) and updated (modifiedCount)

Parameters:

Name Type Summary

filter (optional)

Filter

replacement

T

The new document to write into the collection. Define all fields that the replacement document must include, except for the _id.

options(optional)

ReplaceOneOptions

Set the different options for the replaceOne() operation, including the following:

sort(): See Find a document and Sort operations.
upset(): Controls the behavior if there are no matches. If true and there are no matches, then the operation inserts the replacement as a new document. If false and there are no matches, then the operation silently does nothing.

Example:

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.FindOneAndReplaceOptions;
import com.datastax.astra.client.model.Projections;
import com.datastax.astra.client.model.Sorts;

import java.util.Optional;

import static com.datastax.astra.client.model.Filters.lt;

public class FindOneAndReplace {
    public static void main(String[] args) {
        Collection<Document> collection = new DataAPIClient("TOKEN")
                .getDatabase("API_ENDPOINT")
                .getCollection("COLLECTION_NAME");

        // Building a filter
        Filter filter = Filters.and(
                Filters.gt("field2", 10),
                lt("field3", 20),
                Filters.eq("field4", "value"));

        FindOneAndReplaceOptions options = new FindOneAndReplaceOptions()
                .projection(Projections.include("field1"))
                .sort(Sorts.ascending("field1"))
                .upsert(true)
                .returnDocumentAfter();

        Document docForReplacement = new Document()
                .append("field1", "value1")
                .append("field2", 20)
                .append("field3", 30)
                .append("field4", "value4");

        // It will return the document before deleting it
        Optional<Document> docBeforeReplace = collection
                .findOneAndReplace(filter, docForReplacement, options);
    }
}

This operation has no literal equivalent in HTTP. Instead, you can use Find and replace a document with "projection": {"*": false}, which excludes all document fields from the response.

Replace documents reference

Prerequisites

Find and replace a document

Replace a document

Was this helpful?

Give Feedback