VectorSearchQuery

KIT · interface · Type contract

Search options excluding the query vector, which search takes alongside them.

Import

TypeScript

import type { VectorSearchQuery } from '@jangts/agent-core/kits/vector-search';

JavaScript

/** @typedef {import('@jangts/agent-core/kits/vector-search').VectorSearchQuery} VectorSearchQuery */

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/kits, @jangts/agent-core/kits/vector-search.

Definition

interface VectorSearchQuery<Document>

Type parameters

Type parameter	Constraint	Default type
Document	—	—

Field structure

Field	Type	Required	Description
limit	number	Required	Read-only. Maximum hits returned, 1..1000.
filter	(document: Readonly<Document>) => boolean	Required	Read-only. Synchronous predicate over a document snapshot; false excludes the candidate.
minScore	number | undefined	Optional	Read-only. Minimum cosine score in [-1, 1]; defaults to -1, which keeps every candidate.
groupBy	((document: Readonly<Document>) => string) | undefined	Optional	Read-only. Optional group key; only the best hit per group is kept, defaulting to the document id.

Member index

Member	Purpose
filter	Synchronous predicate over a document snapshot; false excludes the candidate.

Member details

filter

Synchronous predicate over a document snapshot; false excludes the candidate.

VectorSearchQuery.filter(document: Readonly<Document>): boolean

Parameter	Type	Passing	Description
document	Readonly<Document>	Required	—

Returns: boolean.

Examples

• VectorSearch: bounded exact cosine retrieval: Given the same vector space, filter documents first and then rank by cosine similarity.

First retrieve documentation fragments in the same space

Beginner · Node.js

Two-dimensional vectors are used to show the contract; they do not represent real text embeddings or retrieval quality.

TypeScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch<{ id: string; text: string }>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));

JavaScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'workflow', text: '工作流说明' }, vector: [1, 0] });
index.upsert({ document: { id: 'model', text: '模型说明' }, vector: [0, 1] });
console.log(index.search({ vector: [0.9, 0.1], limit: 2, filter: () => true }));

Add permissions, a threshold, and document grouping to the same search

Configuration · Node.js

TypeScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
type Chunk = { id: string; documentId: string; audience: string; text: string };
const index = new VectorSearch<Chunk>({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));

JavaScript

import { VectorSearch } from '@jangts/agent-core/kits/vector-search';
const index = new VectorSearch({ identity: 'demo-direction-v1', dimensions: 2 });
index.upsert({ document: { id: 'manual-1', documentId: 'manual', audience: 'public', text: '工作流定义' }, vector: [1, 0] });
index.upsert({ document: { id: 'manual-2', documentId: 'manual', audience: 'public', text: '工作流调用' }, vector: [0.95, 0.05] });
index.upsert({ document: { id: 'private-1', documentId: 'private', audience: 'owner', text: '内部说明' }, vector: [1, 0] });
console.log(index.search({ vector: [1, 0], limit: 5, minScore: 0.5, filter: row => row.audience === 'public', groupBy: row => row.documentId }));

Related policy source

• Vector validation, normalization, filtering, and grouped ordering