query - Vector query

query() is used to execute vector similarity search to find documents most similar to the query vector.

info

This API can only be used when connected with SeekdbClient. For more information about SeekdbClient, see SeekdbClient.

Prerequisites

• You have installed seekdb-js. For more information, see Quick start.

• You have installed the server mode of seekdb. For more information, see Deploy seekdb by using yum install.

• You have connected to the database. For more information, see SeekdbClient.

• You have created a collection and inserted corresponding data. For more information, see createCollection and add.

Request parameters

query()

Parameter	Type	Required	Description	Example Value
queryEmbeddings	number[] | number[][]	Yes	A single vector or a list of vectors for batch queries. If provided, it will be used directly (ignoring the embeddingFunction). If not provided, queryText must be provided, and collection must have an embeddingFunction.	[1.0, 2.0, 3.0]
queryTexts	string | string[]	No	A single vector or a list of vectors. If provided, it will be used directly (ignoring embeddingFunction). If not provided, documents must be provided, and collection must have an embeddingFunction.	["my query text"]
nResults	number	Yes	The number of similar results to return. Default value is 10	`3
where	Where	No	Metadata filter conditions.	{"category": {"$eq": "AI"}}
whereDocument	WhereDocument	No	Document filter conditions.	{"$contains": "machine"}
include	readonly ("documents" | "metadatas" | "embeddings" | "distances")[][str]	No	A list of fields to include: ["documents", "metadatas", "embeddings"].	["documents", "metadatas", "embeddings"]
distance	DistanceMetric	No	The distance metric.
approximate	boolean	No	Whether to use approximate search.	true

info

• The embeddingFunction used is associated with the collection (set during createCollection() or getCollection()). You cannot override it for each operation.

• If queryEmbeddings is provided: The vectors will be used directly without calling embeddingFunction.

• If queryEmbeddings is not provided but queryTexts is:

  • If the collection has an embeddingFunction, the query vector will be automatically generated from the text.

  • If the collection does not have an embeddingFunction, a ValueError will be returned.

• If neither queryEmbeddings nor queryTexts is provided, a ValueError will be returned.

Request example

import { SeekdbClient } from "seekdb";

// 1. Connect
const client = new SeekdbClient({
  host: "127.0.0.1",
  port: 2881,
  user: "root",
  password: "",
  database: "test",
});

// 2. Create collection
const collection = await client.createCollection({ name: "my_collection" });

// 3. Add data (auto-vectorized)
await collection.add({
  ids: ["1", "2"],
  documents: ["Hello world", "seekdb is fast"],
});

// 4. Search
const results = await collection.query({
  queryTexts: "Hello",
  nResults: 5,
});
console.log(results);

Response parameters

Parameter	Type	Required	Description
ids	readonly (readonly string[])[]	Yes	The ID to be added or modified. It can be a single ID or an array of IDs.
embeddings	[List[List[List[float]]]]	No	Vectors. If provided, they will be used directly (ignoring embeddingFunction). If not provided, documents can be provided to automatically generate vectors.
documents	[List[List[Dict]]]	No	Documents. If vectors are not provided, documents will be converted to vectors using the collection's embeddingFunction.
metadatas	[List[List[Dict]]]	No	Metadata.
distances	[List[List[Dict]]]	No

Response example

{
  ids: [ [ '1', '2' ] ],
  distances: [ [ 0.24884326749104657, 0.9389671014508124 ] ],
  documents: [ [ 'Hello world', 'seekdb is fast' ] ],
  metadatas: [ [ null, null ] ],
  embeddings: undefined
}

Related operations

• Retrieve
• Hybrid search
• Operators