Skip to main content
POST
/
api
/
v2
/
tenants
/
{tenant}
/
databases
/
{database}
/
collections
/
{collection_id}
/
search
curl --request POST \
  --url https://api.trychroma.com/api/v2/tenants/{tenant}/databases/{database}/collections/{collection_id}/search \
  --header 'Content-Type: application/json' \
  --header 'x-chroma-token: <api-key>' \
  --data '
{
  "read_level": "IndexAndWal",
  "searches": [
    {
      "n_results": 10,
      "query_embeddings": [
        [
          0.1,
          0.2,
          0.3
        ]
      ]
    }
  ]
}
'
{
  "documents": [
    [
      "<string>"
    ]
  ],
  "embeddings": [
    [
      [
        123
      ]
    ]
  ],
  "ids": [
    [
      "<string>"
    ]
  ],
  "metadatas": [
    [
      "<unknown>"
    ]
  ],
  "scores": [
    [
      123
    ]
  ],
  "select": [
    [
      "Document"
    ]
  ]
}

Authorizations

​
x-chroma-token
string
header
required

Path Parameters

​
tenant
string
required

Tenant UUID

​
database
string
required

Database name

​
collection_id
string
required

Collection UUID

Body

application/json

Search request payload

​
searches
object[]
required
​
read_level
enum<string>

Specifies whether to include unindexed data in the search results.

Available options:
index_and_wal,
index_only

Response

Records searched from the collection

​
documents
((string | null)[] | null)[]
required
​
embeddings
((number<float>[] | null)[] | null)[]
required
​
ids
string[][]
required
​
metadatas
((null | object)[] | null)[]
required
​
scores
((number<float> | null)[] | null)[]
required
​
select
enum<string> · enum<string> · enum<string> · enum<string> · object[][]
required

Represents a field key in search queries.

Used for both selecting fields to return and building filter expressions. Predefined keys access special fields, while custom keys access metadata.

Predefined Keys

  • Key::Document - Document text content (#document)
  • Key::Embedding - Vector embeddings (#embedding)
  • Key::Metadata - All metadata fields (#metadata)
  • Key::Score - Search scores (#score)

Custom Keys

Use Key::field() or Key::from() to reference metadata fields:

use chroma_types::operator::Key;

let key = Key::field("author");
let key = Key::from("title");

Examples

Building filters

use chroma_types::operator::Key;

// Equality
let filter = Key::field("status").eq("published");

// Comparisons
let filter = Key::field("year").gte(2020);
let filter = Key::field("score").lt(0.9);

// Set operations
let filter = Key::field("category").is_in(vec!["tech", "science"]);
let filter = Key::field("status").not_in(vec!["deleted", "archived"]);

// Document content
let filter = Key::Document.contains("machine learning");
let filter = Key::Document.regex(r"\bAPI\b");

// Combining filters
let filter = Key::field("status").eq("published")
    & Key::field("year").gte(2020);

Selecting fields

use chroma_types::plan::SearchPayload;
use chroma_types::operator::Key;

let search = SearchPayload::default()
    .select([
        Key::Document,
        Key::Score,
        Key::field("title"),
        Key::field("author"),
    ]);
Available options:
Document