Search overview

Search is the retrieval layer for the knowledge and memory stored in LambdaDB collections. A search query, or query, requests documents that match an application’s current context or criteria. LambdaDB supports several search methods:

Search for exact values: search for exact values or ranges of numbers, dates, IPs, or strings.
Full-text search: use query strings and the field’s configured text analyzers to match unstructured text.
Vector search: use dense vector queries with approximate nearest neighbor (ANN) retrieval, or sparse vector queries with weighted terms or dimensions.
Hybrid search: combine two retrieval paths with RRF, Min-Max, L2, or Bayesian fusion.

For dense vector fields, supply your own embeddings with knn.queryVector, or configure native embeddings and search with knn.queryText so LambdaDB generates the query vector with the field’s model. To evaluate and reorder retrieved candidates with a model provided by LambdaDB, add query-level native reranking. This is separate from vector retrieval and hybrid fusion. To count matching documents by keyword value, add keyword facets to a supported lexical query or omit the query for match-all counts. Facets cannot be combined with vector, sparse vector, or hybrid queries. Common parameters for the request body of a query are as follows:

Parameter	Description	Type	Required	Default
size	The number of results to return (1–100, or 0 when at least one facet is requested). Omitted or `null` uses the default.	integer or null		10
query	Query object (details in the subsections). Omit or use `null` to match all documents in the selected read scope.	object or null		All documents
candidateSize	Candidate budget for Bayesian hybrid search without reranking; require `size <= candidateSize <= 100`. Omit for other queries or when using `rerank.candidateSize`.	integer	Bayesian without reranking
rerank	Optional native reranking after candidate merge; requires a scoring query and positive `size`, and cannot be combined with `sort`. Omitted or `null` preserves existing search behavior.	object or null
facets	Counts by keyword field value (see Keyword facets). Supported with `queryString`, `bool` combinations of supported lexical queries, or no query.	object or null
includeVectors	Indicates whether vector values are included in the response	boolean		false
consistentRead	Determines the read consistency model: If set to true, then the operation uses strongly consistent reads; otherwise, the operation uses eventually consistent reads.	boolean		false
fields	A list of field names to include and/or exclude in the result. Use dot notation (e.g., user.name) to specify nested fields.	object
sort	Specifies the sorting criteria for the results (details in the subsection); omitted or `null` means no explicit sort	object[] or null
partitionFilter	Select physical partitions by values of the configured partition field; unselected partitions are not searched. See Partition selection.	object		All partitions
ref	Branch, tag, or alias selector as `{ "kind": "...", "name": "..." }`	object		`main` branch

Depending on your data and your query, you may get fewer than size results. This happens when size is larger than the number of possible matching documents for your query.

Setting includeVectors (or include_vectors in Python) to true will increase response size significantly, especially for high-dimensional vectors. Use this option only when vector data is specifically needed for your application.

include is applied first, and then exclude is applied to the included fields when you set both in the fields parameter.

LambdaDB is eventually consistent by default, so there can be a slight delay before new or changed documents are visible to queries. If your application requires strong (read-after-write) consistency, set consistentRead (or consistent_read in Python) to true when querying a branch directly, at the expense of potential higher latency and cost. Tag and alias reads reject consistentRead: true, including an alias that targets a branch.This overlays eligible pending writes; pending bulk imports remain invisible until committed. A pending payload above the consistent-read limit returns 429. See Consistent reads.

Query results are returned in the following format:

Field	Description	Type
took	Milliseconds it took LambdaDB to execute the request	long
maxScore	Highest final returned document `score`; omitted for empty results or when no score is computed	number
total	Number of documents returned, not the count of all matches	long
rerank	Optional reranking status, model, counts, and stage timing	object
facets	Requested keyword fields mapped to `buckets` containing `value` and `count`; counts cover all matches and remain inline even when documents use `docsUrl`	object
docs	Contains returned documents and metadata	object[]
isDocsInline	Whether `docs` is included inline in the REST response	boolean
docsUrl	Presigned download URL when `isDocsInline` is `false`	string

total counts the returned documents even when they are delivered through docsUrl; it is not a count of every document matching the query. A document’s score can be omitted when the query does not compute one. Applied reranking uses score for the final evaluation value in [0,1] and adds the original search score as retrievalScore alongside doc. Fallback preserves search scores and omits retrievalScore. Check rerank.status before interpreting scores; evaluation scores are not relevance probabilities. See Reranking responses. Large results may be returned through docsUrl instead of inline docs. See Large results for REST download instructions and SDK behavior.

Select partitions to search

Partitioning is configured by the application through the collection’s partitionConfig. On a partitioned collection, top-level partitionFilter limits the request to the physical partitions associated with the supplied field values. Other partitions are not searched. Without partitionFilter, the search scope includes all partitions. For example, assume the collection has a tenant_id keyword index, a content text index, and partitionConfig set to { "fieldName": "tenant_id", "dataType": "keyword", "numPartitions": 4 }. Send this query body to search the authorized tenant’s data:

{
  "partitionFilter": {
    "field": "tenant_id",
    "in": ["tenant_42"]
  },
  "query": {
    "queryString": {
      "query": "refund",
      "defaultField": "content"
    }
  },
  "size": 10
}

field must match the configured partition field, and in contains field values, not physical partition IDs. Hash partitioning can place several field values in the same physical partition; the request also restricts matches to the supplied values. Derive permitted values in your backend from the caller’s authorization. Use query predicates, including knn.filter, for additional document conditions within that search scope. A document predicate alone does not replace partitionFilter for skipping physical partitions. Internal sharding distributes query execution and has no user-facing configuration; it is separate from this explicit partition selection. See Create a partitioned collection for setup and Read usage for the effect of partition selection on billing.

Example

from lambdadb import LambdaDB

with LambdaDB(project_api_key="YOUR_API_KEY", base_url="YOUR_BASE_URL", project_name="YOUR_PROJECT_NAME") as client:
    coll = client.collection("my_collection")
    results = coll.query(query={"queryString": {"query": "*:*"}}, size=10)
    # `results.docs` contains items (each item includes `doc` and `score`).
    # `results.documents` contains document bodies only (no scores).

Python: LambdaDB supports context manager usage. __enter__ returns the client, and __exit__ calls client.close() (closing the SDK-owned HTTP client) and makes the client unusable after the with block. If you don’t use with, call client.close() when you’re done. If you pass a custom client=/async_client=, you own closing it.

import { LambdaDBClient } from "@functional-systems/lambdadb";

const client = new LambdaDBClient({
  projectApiKey: "YOUR_API_KEY",
  baseUrl: "YOUR_BASE_URL",
  projectName: "YOUR_PROJECT_NAME",
});
const results = await client.collection("my_collection").query({
  query: { queryString: { query: "*:*" } },
  size: 10,
});

package main

import (
  "context"
  "log"
  lambdadb "github.com/lambdadb/go-lambdadb"
)

func main() {
  ctx := context.Background()
  client := lambdadb.New(
    lambdadb.WithBaseURL("YOUR_BASE_URL"),
    lambdadb.WithProjectName("YOUR_PROJECT_NAME"),
    lambdadb.WithAPIKey("YOUR_API_KEY"),
  )
  coll := client.Collection("my_collection")
  results, err := coll.Query(ctx, lambdadb.QueryInput{
    Query: map[string]interface{}{"queryString": map[string]interface{}{"query": "*:*"}},
    Size:  lambdadb.Int64(10),
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = results
}

To query a specific ref over REST, add "ref": { "kind": "branch", "name": "candidate" } alongside query and size. Omitting ref selects main. See Branches, tags, and aliases. The response will look like this:

{
  "took": 76,
  "maxScore": 1.0,
  "total": 1,
  "docs": [
    {
      "collection": "example_collection",
      "score": 1.0,
      "doc": {
        "id": "33201222",
        "url": "https://en.wikipedia.org/wiki/LambdaDB",
        "title": "LambdaDB is awesome",
        "text": null
      }
    }
  ],
  "isDocsInline": true
}

Without explicit sorting or applied reranking, scored results are ordered by descending retrieval score: BM25 for full-text search, the configured similarity metric for vector search, or the selected fusion method for hybrid search. Applied reranking orders candidates by their final evaluation score and preserves the retrieval score in retrievalScore.

Get started

Migrations

Collections

Data versioning

Documents

Search

Manage Costs

Security

Select partitions to search

Example

​Select partitions to search

​Example

Select partitions to search

Example