API: Query

Search vectors within a namespace using vector similarity (ANN), full-text (BM25), or hybrid queries.

Endpoint

POST /v2/namespaces/:namespace/query

Vector Search (ANN)

Find the closest vectors by cosine or euclidean distance:

{
  "rank_by": ["vector", "ANN", [0.1, 0.2, 0.3, ...]],
  "top_k": 10,
  "include_attributes": true
}

Full-Text Search (BM25)

Rank documents by BM25 text relevance:

{
  "rank_by": ["text", "BM25", "search query here"],
  "top_k": 10,
  "include_attributes": ["title", "content"]
}

Request Fields

Field	Type	Required	Description
`rank_by`	array	Yes	Ranking mode — see above
`top_k`	number	No	Number of results (default: 10, max: 10,000)
`filters`	Filter	No	Attribute filter expression
`include_vectors`	boolean	No	Include vector data in results
`include_attributes`	boolean or string[]	No	Include attributes (all or specified fields)

Filters

Filter expressions are recursive arrays:

{
  "rank_by": ["vector", "ANN", [...]],
  "top_k": 10,
  "filters": ["And", [
    ["category", "Eq", "article"],
    ["price", "Lt", 100]
  ]]
}

Operators

Operator	Description
`Eq`	Equal
`NotEq`	Not equal
`Gt` / `Gte`	Greater than / greater than or equal
`Lt` / `Lte`	Less than / less than or equal
`In`	Value in array
`NotIn`	Value not in array
`And`	All conditions must match
`Or`	Any condition must match

Response

{
  "rows": [
    {
      "id": 42,
      "dist": 0.123,
      "attributes": {
        "title": "Machine Learning Basics",
        "category": "article"
      }
    }
  ],
  "performance": {
    "cache_hit_ratio": 0.85,
    "cache_temperature": "warm",
    "server_total_ms": 8,
    "query_execution_ms": 5
  }
}

Example (TypeScript SDK)

const results = await ns.query({
  rank_by: ["vector", "ANN", queryVector],
  top_k: 20,
  filters: ["And", [
    ["category", "Eq", "article"],
    ["published", "Eq", true],
  ]],
  include_attributes: ["title", "url"],
});

for (const row of results.rows) {
  console.log(#${row.id} (dist: ${row.dist}) — ${row.attributes.title});
}