Skip to main content
POST
/
api
/
v2
/
tenants
/
{tenant}
/
databases
/
{database}
/
collections
/
{collection_id}
/
search
Search records from a collection with hybrid criterias.
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 '
{
  "searches": [
    {
      "filter": {
        "query_ids": [
          "<string>"
        ],
        "where_clause": {}
      },
      "group_by": {
        "aggregate": {},
        "keys": [
          "<string>"
        ]
      },
      "limit": {
        "limit": 123,
        "offset": 123
      },
      "rank": {},
      "select": {
        "keys": [
          "<string>"
        ]
      }
    }
  ],
  "read_level": "index_and_wal"
}
'
{
  "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 ID

​
database
string
required

Database name for the collection

​
collection_id
string
required

Collection ID to search records from

Body

application/json
​
searches
object[]
required
​
read_level
enum<string>

Specifies the read level for consistency vs performance tradeoffs. Defaults to IndexAndWal (full consistency).

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