Query

Finds the nearest neighbors of one or more query vectors. With queryContents, the service embeds the text first (the index needs an embeddingModel). With text, the query becomes hybrid: BM25 full-text ranking is fused with the vector ranking.

async query({
    queryVectors?: number[] | number[][] | Float32Array,
    queryContents?: string,
    topK?: number,
    nProbes?: number,
    filters?: FilterExpression,
    include?: string[],
    greedy?: boolean,
    rerankMult?: number,
    dimension?: number,
    text?: string,
    textFields?: string[],
    textFieldWeights?: number[],
    requireAllTerms?: boolean,
    alpha?: number,
    rrfK?: number,
    windowMult?: number,
}): Promise<QueryResponse>

Parameters

Parameter	Type	Default	Description
`queryVectors`	`number[]`, `number[][]`, or `Float32Array`	`undefined`	(Optional) One query vector, a batch, or a batch packed back to back in a `Float32Array` (sent in a faster binary format).
`queryContents`	`string`	`undefined`	(Optional) Text for the service to embed and search with. Requires an index created with `embeddingModel`.
`topK`	`number`	`undefined` (service default: `100`)	(Optional) Results to return per query. Must be at least `1`.
`nProbes`	`number`	`undefined` (service default: auto)	(Optional) Clusters to probe. Higher values improve recall and add latency.
`filters`	`FilterExpression`	`undefined`	(Optional) Metadata filter. See Metadata filtering.
`include`	`string[]`	`undefined` (service default: `[]`)	(Optional) Extra fields per result: `'distance'` and `'metadata'`. `id` is always returned. See Result fields.
`greedy`	`boolean`	`undefined` (service default: `false`)	(Optional) Use greedy search.
`rerankMult`	`number`	`undefined` (service default: `50`)	(Optional) Stage 1 returns `topK * rerankMult` candidates before reranking narrows them to `topK`. Higher values trade latency for recall.
`dimension`	`number`	`undefined`	Required when `queryVectors` is a `Float32Array`, to split it into vectors. Ignored otherwise.
`text`	`string`	`undefined`	(Optional) Query text for a BM25 leg, which makes the query hybrid. Requires an index with at least one full-text field. `queryVectors` is still required.
`textFields`	`string[]`	`undefined` (all full-text fields)	(Optional) Full-text fields the BM25 leg searches. Naming a field that isn’t full-text throws `CyborgDBValidationError`.
`textFieldWeights`	`number[]`	`undefined` (`1.0` each)	(Optional) Weight per searched field, in the same order as `textFields`.
`requireAllTerms`	`boolean`	`undefined` (service default: `false`)	(Optional) Match only items containing every query term (AND) instead of any term (OR).
`alpha`	`number`	`undefined` (service default: `0.5`)	(Optional) Blend of the two legs, in `[0, 1]`: `0` is pure BM25, `1` is pure vector. At exactly `0` or `1` the other leg isn’t run.
`rrfK`	`number`	`undefined` (service default: `60`)	(Optional) Reciprocal rank fusion smoothing constant. Must be `> 0`.
`windowMult`	`number`	`undefined` (service default: `3`)	(Optional) Candidates retrieved per leg, as a multiple of `topK`. Must be `>= 1`.

Returns

Promise<QueryResponse>, whose results is:

One number[] query vector: QueryResultItem[], one item per neighbor.
Two or more query vectors (number[][] or Float32Array): QueryResultItem[][], one inner array per query vector.

A query with exactly one vector always returns single results, even when it’s sent as a batch or through the binary path. QueryResponse.results is typed QueryResultItem[] | QueryResultItem[][]. Since the call shape decides which one you get, narrow it with a cast: response.results as QueryResultItem[] for one vector, or as QueryResultItem[][] for a batch.

Result fields

{
    id: string,         // Always returned
    distance?: number,  // Vector queries, when 'distance' is in include. Lower is closer.
    score?: number,     // Hybrid queries only, instead of distance. Higher is more relevant.
    metadata?: object,  // When 'metadata' is in include
}

query() never returns vector or contents, even when they’re listed in include. To read them, pass the result IDs to get().

Exceptions

CyborgDBValidationError

Neither queryVectors nor queryContents is passed, or a Float32Array is passed without dimension. Thrown before any request is sent.
The service rejects the query (HTTP 400/422): wrong vector dimension, text on an index without full-text fields, or an out-of-range alpha, rrfK, or windowMult. Other numeric parameters aren’t range-checked.

CyborgDBAuthenticationError

The indexKey or apiKey is invalid (HTTP 401).

CyborgDBServiceError

The service returns 5xx.

See Errors for the full hierarchy.

Example Usage

Single vector

import type { QueryResultItem } from 'cyborgdb';

const response = await index.query({
    queryVectors: [0.1, 0.2, 0.3, 0.4],
    topK: 2,
    include: ['distance', 'metadata'],
});
const results = response.results as QueryResultItem[];

for (const r of results) {
    console.log(r.id, Number(r.distance?.toFixed(4)), r.metadata);
}
// Output:
// doc1 0 { category: 'news' }
// doc2 0.8 { category: 'research' }

Batch of vectors

import type { QueryResultItem } from 'cyborgdb';

const response = await index.query({
    queryVectors: [
        [0.1, 0.2, 0.3, 0.4],
        [0.5, 0.6, 0.7, 0.8],
    ],
    topK: 1,
});
const batch = response.results as QueryResultItem[][];

batch.forEach((results, i) => console.log(i, results.map((r) => r.id)));
// Output:
// 0 [ 'doc1' ]
// 1 [ 'doc2' ]

Float32Array

import type { QueryResultItem } from 'cyborgdb';

const queries = new Float32Array([0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]);
const response = await index.query({ queryVectors: queries, dimension: 4, topK: 1 });
const batch = response.results as QueryResultItem[][];

console.log(batch.length);
// Output: 2

Text, embedded by the service

import type { QueryResultItem } from 'cyborgdb';

// The index must have been created with embeddingModel
const response = await index.query({
    queryContents: 'machine learning in healthcare',
    topK: 3,
});
console.log((response.results as QueryResultItem[]).map((r) => r.id));

Hybrid (BM25 + vector)

The index needs at least one full-text field, set with textFields or { fullText: true } in createIndex().

import type { QueryResultItem } from 'cyborgdb';

const response = await index.query({
    queryVectors: [0.1, 0.2, 0.3, 0.4],
    text: 'encrypted search',
    topK: 2,
    alpha: 0.5,
    include: ['metadata'],
});

for (const r of response.results as QueryResultItem[]) {
    console.log(r.id, Number(r.score?.toFixed(4)));
}
// Output:
// doc1 0.0164
// doc2 0.0161

Filters and search options

import type { QueryResultItem } from 'cyborgdb';

const response = await index.query({
    queryVectors: [0.1, 0.2, 0.3, 0.4],
    topK: 20,
    nProbes: 5,
    rerankMult: 20,
    greedy: true,
    filters: { category: 'news' },
    include: ['distance', 'metadata'],
});

for (const r of response.results as QueryResultItem[]) {
    console.log(r.id, r.metadata?.category);
}
// Output: doc1 news

Introduction

Client

Encrypted Index

Types & Helpers

Parameters

Returns

Result fields

Exceptions

Example Usage

Single vector

Batch of vectors

Float32Array

Text, embedded by the service

Hybrid (BM25 + vector)

Filters and search options

​Parameters

​Returns

​Result fields

​Exceptions

​Example Usage

​Single vector

​Batch of vectors

​Float32Array

​Text, embedded by the service

​Hybrid (BM25 + vector)

​Filters and search options

Parameters

Returns

Result fields

Exceptions

Example Usage

Single vector

Batch of vectors

Float32Array

Text, embedded by the service

Hybrid (BM25 + vector)

Filters and search options