VectorSearch

KIT · class · Runtime value

Exact cosine search for a bounded embedded corpus. Identity and metadata are App-owned.

Vectors arrive as plain arrays and are stored normalized in Float32Array form, so query time only needs a dot product per candidate.

Import

TypeScript

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

JavaScript

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

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

Definition

class VectorSearch<Document>

Type parameters

Type parameter	Constraint	Default type
Document	{ id: string }	—

Constructor

new VectorSearch<Document extends { id: string; }>(space: VectorSearchSpace): VectorSearch<Document>

Parameter	Type	Passing	Description
space	VectorSearchSpace	Required	—

Fields of space

Field	Type	Required	Description
identity	string	Required	Read-only. Non-blank space name, for example model@revision; reported back by VectorSearch.
dimensions	number	Required	Read-only. Expected vector length, 1..16384.

Returns: VectorSearch<Document>.

Instance properties

Field	Type	Required	Description
space	VectorSearchSpace	Required	Read-only. The declared space; compare it before mixing vectors from another source.

Member index

Member	Purpose
upsert	Insert or replace one document and its embedding.
remove	Remove one document; returns whether it was present.
clear	Drop the whole corpus while keeping the declared space.
search	Score every candidate and return the best hits.

Member details

upsert

Instance method.

Insert or replace one document and its embedding.

upsert({ document, vector }: { document: Document; vector: readonly number[]; }): void

Insert or replace one document and its embedding.

Parameter	Type	Passing	Description
__0	{ document: Document; vector: readonly number[]; }	Required	—

Fields of __0

Field	Type	Required	Description
document	Document	Required	See the type definition and usage context.
vector	readonly number[]	Required	See the type definition and usage context.

Returns: void.

remove

Instance method.

Remove one document; returns whether it was present.

remove(id: string): boolean

Remove one document; returns whether it was present.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

clear

Instance method.

Drop the whole corpus while keeping the declared space.

clear(): void

Drop the whole corpus while keeping the declared space.

No call parameters.

Returns: void.

search

Instance method.

Score every candidate and return the best hits.

search(options: VectorSearchQuery<Document> & { vector: readonly number[]; }): VectorSearchHit<Document>[]

Score every candidate and return the best hits.

Parameter	Type	Passing	Description
options	VectorSearchQuery<Document> & { vector: readonly number[]; }	Required	—

Fields of options

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.
vector	readonly number[]	Required	See the type definition and usage context.

Returns: VectorSearchHit<Document>[].

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

Related definitions

• VectorSearchHit
• VectorSearchQuery
• VectorSearchSpace