Find a document

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 clients. For instructions to get a Collection object, see Work with collections.

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

For more information about the Data API and clients, see Get started with the Data API.

Find a single document

Retrieve a single document from a collection using various filter and query options.

Sort and filter clauses 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.

Retrieve a single document from a collection by its _id:

document = collection.find_one({"_id": 101})

Retrieve a single document from a collection by any property, as long as the property is covered by the collection’s indexing configuration:

document = collection.find_one({"location": "warehouse_C"})

Retrieve a single document from a collection by an arbitrary filtering clause:

document = collection.find_one({"tag": {"$exists": True}})

Retrieve the document that is most similar to a given vector:

result = collection.find_one({}, sort={"$vector": [.12, .52, .32]})

Retrieve the most similar document by running a vector search with vectorize:

result = collection.find_one({}, sort={"$vectorize": "Text to vectorize"})

Use a projection to specify the fields returned from each document. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

result = collection.find_one({"_id": 101}, projection={"name": True})

Parameters:

Name Type Summary

Name	Type	Summary
`filter`	`Optional[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-filter-options].
`projection`	`Optional[Union[Iterable[str], Dict[str, bool]]]`	Select a subset of fields to include in the response for each 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 clauses.
`include_similarity`	`Optional[bool]`	If true, the response includes a `$similarity` key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. Only valid for vector ANN search with `$vector` or `$vectorize`.
`sort`	`Optional[Dict[str, Any]]`	Use this dictionary parameter to perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either `$vector` or `$vectorize`, but not both in the same request. For more information and examples, see Sort clauses.
`max_time_ms`	`Optional[int]`	A timeout, in milliseconds, for the underlying HTTP request. This method uses the collection-level timeout by default.

filter

Optional[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-filter-options].

projection

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

Select a subset of fields to include in the response for each 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 clauses.

include_similarity

Optional[bool]

If true, the response includes a $similarity key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. Only valid for vector ANN search with $vector or $vectorize.

sort

Optional[Dict[str, Any]]

Use this dictionary parameter to perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either $vector or $vectorize, but not both in the same request. For more information and examples, see Sort clauses.

max_time_ms

Optional[int]

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

Returns:

Union[Dict[str, Any], None] - Either the found document as a dictionary or None if no matching document is found.

Example response

{'_id': 101, 'name': 'John Doe', '$vector': [0.12, 0.52, 0.32]}

Example:

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

collection.find_one()
# prints: {'_id': '68d1e515-...', 'seq': 37}
collection.find_one({"seq": 10})
# prints: {'_id': 'd560e217-...', 'seq': 10}
collection.find_one({"seq": 1011})
# (returns None for no matches)
collection.find_one(projection={"seq": False})
# prints: {'_id': '68d1e515-...'}
collection.find_one(
    {},
    sort={"seq": astrapy.constants.SortDocuments.DESCENDING},
)
# prints: {'_id': '97e85f81-...', 'seq': 69}
collection.find_one(sort={"$vector": [1, 0]}, projection={"*": True})
# prints: {'_id': '...', 'tag': 'D', '$vector': [4.0, 1.0]}

For more information, see the Client reference.

Retrieve a single document from a collection by its _id:

const doc = await collection.findOne({ _id: '101' });

Retrieve a single document from a collection by any property, as long as the property is covered by the collection’s indexing configuration:

const doc = await collection.findOne({ location: 'warehouse_C' });

Retrieve a single document from a collection by an arbitrary filtering clause:

const doc = await collection.findOne({ tag: { $exists: true } });

Retrieve the document that is most similar to a given vector:

const doc = await collection.findOne({}, { sort: { $vector: [.12, .52, .32] } });

Retrieve the most similar document by running a vector search with vectorize:

const doc = await collection.findOne({}, { sort: { $vectorize: 'Text to vectorize' } });

const doc = await collection.findOne({ _id: '101' }, { projection: { name: 1 } });

Parameters:

Name Type Summary

Name	Type	Summary
`filter`	`Filter<Schema>`	A filter to select the document to find. For a list of available operators, see Data API operators. For additional examples, see [find-documents-using-filter-options].
`options?`	`FindOneOptions`	The options for this operation.

filter

Filter<Schema>

A filter to select the document to find. For a list of available operators, see Data API operators. For additional examples, see [find-documents-using-filter-options].

options?

FindOneOptions

The options for this operation.

Options (FindOneOptions):

Name Type Summary

Name	Type	Summary
`projection?`	`Projection`	Specifies which fields to include or exclude in the returned documents. 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 clauses. When specifying a projection, make sure that you handle the return type carefully. Consider type-casting.
`includeSimilarity?`	`boolean`	If true, the response includes a `$similarity` key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid when performing a vector search with `$vector` or `$vectorize`.
`sort?`	`Sort`	Perform a vector similarity search or set the order in which documents are returned. For similarity searches, `sort` can use either `$vector` or `$vectorize`, but not both in the same request. For more information and examples, see Sort clauses.
`maxTimeMS?`	`number`	The maximum time in milliseconds that the client should wait for the operation to complete.

projection?

Projection

Specifies which fields to include or exclude in the returned documents. 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 clauses.

When specifying a projection, make sure that you handle the return type carefully. Consider type-casting.

includeSimilarity?

boolean

If true, the response includes a $similarity key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid when performing a vector search with $vector or $vectorize.

sort?

Sort

Perform a vector similarity search or set the order in which documents are returned. For similarity searches, sort can use either $vector or $vectorize, but not both in the same request. For more information and examples, see Sort clauses.

maxTimeMS?

number

The maximum time in milliseconds that the client should wait for the operation to complete.

Returns:

Promise<FoundDoc<Schema> | null> - A promise that resolves to the found document (inc. $similarity if applicable), or null if no matching document is 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 documents
  await collection.insertMany([
    { name: 'John', age: 30, $vector: [1, 1, 1, 1, 1] },
    { name: 'Jane', age: 25, },
    { name: 'Dave', age: 40, },
  ]);

  // Unpredictably prints one of their names
  const unpredictable = await collection.findOne({});
  console.log(unpredictable?.name);

  // Failed find by name (null)
  const failed = await collection.findOne({ name: 'Carrie' });
  console.log(failed);

  // Find by $gt age (Dave)
  const dave = await collection.findOne({ age: { $gt: 30 } });
  console.log(dave?.name);

  // Find by sorting by age (Jane)
  const jane = await collection.findOne({}, { sort: { age: 1 } });
  console.log(jane?.name);

  // Find by vector similarity (John, 1)
  const john = await collection.findOne({}, { sort: { $vector: [1, 1, 1, 1, 1] }, includeSimilarity: true });
  console.log(john?.name, john?.$similarity);
})();

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> findOne(Filter filter);
Optional<T> findOne(Filter filter, FindOneOptions options);
Optional<T> findById(Object id); // build the filter for you

// Asynchronous
CompletableFuture<Optional<DOC>> findOneAsync(Filter filter);
CompletableFuture<Optional<DOC>> findOneAsync(Filter filter, FindOneOptions options);
CompletableFuture<Optional<DOC>> findByIdAsync(Filter filter);

You can retrieve documents in various ways, for example:

Retrieve a single document from a collection by its _id.
Retrieve a single document from a collection by any property, as long as the property is covered by the collection’s indexing configuration.
Retrieve a single document from a collection by an arbitrary filtering clause.
Retrieve the document that is most similar to a given vector.
Retrieve the most similar document by running a vector search with vectorize.

Additionally, you can use a projection to specify the fields returned from each document. A projection is required if you want to return certain reserved fields, like $vector and $vectorize, that are excluded by default.

In the underlying HTTP request, a filter is a JSON object containing filter and sort parameters, for example:

{
  "findOne": {
    "filter": {
      "$and": [
        { "field2": { "$gt": 10 } },
        { "field3": { "$lt": 20 } },
        { "field4": { "$eq": "value" } }
      ]
    },
    "projection": {
      "_id": 0,
      "field": 1,
      "field2": 1,
      "field3": 1
    },
    "sort": {
      "$vector": [0.25, 0.25, 0.25,0.25, 0.25]
    },
    "options": {
      "includeSimilarity": true
    }
  }
}

You can define the preceding JSON object in Java as follows:

collection.findOne(
  Filters.and(
   Filters.gt("field2", 10),
   Filters.lt("field3", 20),
   Filters.eq("field4", "value")
  ),
  new FindOneOptions()
   .projection(Projections.include("field", "field2", "field3"))
   .projection(Projections.exclude("_id"))
   .vector(new float[] {0.25f, 0.25f, 0.25f,0.25f, 0.25f})
   .includeSimilarity()
  )
);

// with the import Static Magic
collection.findOne(
  and(
   gt("field2", 10),
   lt("field3", 20),
   eq("field4", "value")
  ),
  vector(new float[] {0.25f, 0.25f, 0.25f,0.25f, 0.25f})
   .projection(Projections.include("field", "field2", "field3"))
   .projection(Projections.exclude("_id"))
   .includeSimilarity()
);

Parameters:

Name Type Summary

Name	Type	Summary
`filter`	`Filter`	Criteria list to filter the document. 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 additional examples, see [find-documents-using-filter-options].
`options` (optional)	`FindOneOptions`	Set the different options for the `findOne` operation, including the following: `sort()`: Perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either `$vector` or `$vectorize`, but not both in the same request. For more information and examples, see Sort clauses. `projection()`: A list of flags that select a subset of fields to include in the response for each 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 clauses. `includeSimilarity()`: If true, the response includes a `$similarity` key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid for vector ANN search with `$vector` or `$vectorize`.

filter

Filter

Criteria list to filter the document. 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 additional examples, see [find-documents-using-filter-options].

options (optional)

FindOneOptions

Set the different options for the findOne operation, including the following:

sort(): Perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either $vector or $vectorize, but not both in the same request. For more information and examples, see Sort clauses.
projection(): A list of flags that select a subset of fields to include in the response for each 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 clauses.
includeSimilarity(): If true, the response includes a $similarity key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid for vector ANN search with $vector or $vectorize.

Returns:

Optional<T> - Return the working document matching the filter or Optional.empty() if no document is found.

Example:

package com.datastax.astra.client.collection;

import com.datastax.astra.client.Collection;
import com.datastax.astra.client.DataAPIClient;
import com.datastax.astra.client.DataAPIOptions;
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.FindOneOptions;

import java.util.Optional;

import static com.datastax.astra.client.model.Filters.and;
import static com.datastax.astra.client.model.Filters.eq;
import static com.datastax.astra.client.model.Filters.gt;
import static com.datastax.astra.client.model.Filters.lt;
import static com.datastax.astra.client.model.Projections.exclude;
import static com.datastax.astra.client.model.Projections.include;

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

        // Complete FindOne
        Filter filter = Filters.and(
                Filters.gt("field2", 10),
                lt("field3", 20),
                Filters.eq("field4", "value"));
        FindOneOptions options = new FindOneOptions()
                .projection(include("field", "field2", "field3"))
                .projection(exclude("_id"))
                .sort(new float[] {0.25f, 0.25f, 0.25f,0.25f, 0.25f})
                .includeSimilarity();
        Optional<Document> result = collection.findOne(filter, options);

        // with the import Static Magic
        collection.findOne(and(
                gt("field2", 10),
                lt("field3", 20),
                eq("field4", "value")),
               new FindOneOptions().sort(new float[] {0.25f, 0.25f, 0.25f,0.25f, 0.25f})
                .projection(include("field", "field2", "field3"))
                .projection(exclude("_id"))
                .includeSimilarity()
        );

        // find one with a vectorize
        collection.findOne(and(
                        gt("field2", 10),
                        lt("field3", 20),
                        eq("field4", "value")),
                new FindOneOptions().sort("Life is too short to be living somebody else's dream.")
                        .projection(include("field", "field2", "field3"))
                        .projection(exclude("_id"))
                        .includeSimilarity()
        );

        collection.insertOne(new Document()
                .append("field", "value")
                .append("field2", 15)
                .append("field3", 15)
                .vectorize("Life is too short to be living somebody else's dream."));

    }
}

Use the findOne command to retrieve a document.

Retrieve a single document from a collection by its _id:

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 '{
  "findOne": {
    "filter": { "_id": "018e65c9-df45-7913-89f8-175f28bd7f74" }
  }
}' | jq

Retrieve a single document from a collection by any property, as long as the property is covered by the collection’s indexing configuration:

"findOne": {
  "filter": { "purchase_date": { "$date": 1690045891 } }
}

Retrieve a single document from a collection by an arbitrary filtering clause:

"findOne": {
  "filter": { "preferred_customer": { "$exists": true } }
}

Retrieve the document that is most similar to a given vector:

"findOne": {
  "sort": { "$vector": [0.15, 0.1, 0.1, 0.35, 0.55] }
}

Retrieve the most similar document by running a vector search with vectorize:

"findOne": {
  "sort": { "$vectorize": "I'd like some talking shoes" }
}

"findOne": {
  "sort": { "$vector": [0.15, 0.1, 0.1, 0.35, 0.55] },
  "projection": { "$vector": 1 }
}

Parameters:

Name Type Summary

Name	Type	Summary
`findOne`	`command`	The Data API command to retrieve a document in a collection based on one or more of `filter`, `sort`, `projection`, and `options`.
`filter`	`object`	An object that defines filter criteria using 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-filter-options].
`sort`	`object`	Perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either `$vector` or `$vectorize`, but not both in the same request. For more information and examples, see Sort clauses.
`projection`	`object`	Select a subset of fields to include in the response for each 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 clauses.
`options.includeSimilarity`	`boolean`	If true, the response includes a `$similarity` key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid for vector ANN search with `$vector` or `$vectorize`. `"options": { "includeSimilarity": true }`

findOne

command

The Data API command to retrieve a document in a collection based on one or more of filter, sort, projection, and options.

filter

object

An object that defines filter criteria using 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-filter-options].

sort

object

Perform a vector similarity search or set the order in which documents are returned. For similarity searches, this parameter can use either $vector or $vectorize, but not both in the same request. For more information and examples, see Sort clauses.

projection

object

options.includeSimilarity

boolean

If true, the response includes a $similarity key with the numeric similarity score that represents the closeness of the sort vector and the document’s vector. This is only valid for vector ANN search with $vector or $vectorize.

"options": { "includeSimilarity": true }

Returns:

A successful response includes a data object that contains a document object representing the document matching the given query. The returned document fields depend on the findOne parameters, namely the projection and options.

"data": {
  "document": {
    "_id": "14"
  }
}

Example:

This request retrieves a document from a collection by its _id with the default projection and options:

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 '{
  "findOne": {
    "filter": { "_id": "14" }
  }
}' | jq

The response contains the document’s _id and all regular fields. The default projection excludes $vector and $vectorize.

{
  "data": {
    "document": {
      "_id": "14",
      "amount": 110400,
      "customer": {
        "address": {
          "address_line": "1414 14th Pl",
          "city": "Brooklyn",
          "state": "NY"
        },
        "age": 44,
        "credit_score": 702,
        "name": "Kris S.",
        "phone": "123-456-1144"
      },
      "items": [
        {
          "car": "Tesla Model X",
          "color": "White"
        }
      ],
      "purchase_date": {
        "$date": 1698513091
      },
      "purchase_type": "In Person",
      "seller": {
        "location": "Brooklyn NYC",
        "name": "Jasmine S."
      }
    }
  }
}

Find a document

Find a single document

Was this helpful?

Give Feedback