Package Exports
- @actian/vectorai-client
Readme
Node.js/TypeScript client library for Actian VectorAI Database.
Actian VectorAI Node.js Client
Official Node.js/TypeScript client library for Actian VectorAI — a high-performance vector database. Provides a namespace-based API with full TypeScript types, TLS/mTLS support, a type-safe Filter DSL, and hybrid fusion utilities.
Features
- Namespace API —
client.collections,client.points,client.vde - Full TypeScript — Complete type definitions for all operations
- gRPC transport — High-performance binary protocol with configurable retry, timeouts, and interceptors
- TLS / mTLS — Secure connections with custom CA, client certificates
- Auth — API key and dynamic token provider support
- Filter DSL — Type-safe query building with
Field.of('x').eq(y),FilterBuilder, datetime ranges - Hybrid Fusion — Reciprocal Rank Fusion (RRF) and Distribution-Based Score Fusion (DBSF)
- Smart Batcher — Configurable auto-flushing with byte limits and concurrent flushes
- Resilience — Circuit breaker, backpressure controller, and retry configuration
- Rich Exceptions — Typed error hierarchy with
PointNotFoundError,DimensionMismatchError,CircuitBreakerOpenError, etc.
Installation
npm install @actian/vectorai-clientRequires: Node.js 18 or higher
Quick Start
import { VectorAIClient, Field, Filter } from '@actian/vectorai-client';
const client = new VectorAIClient('localhost:6574');
// Create a collection
await client.collections.create('products', {
dimension: 128,
distanceMetric: 'COSINE',
});
// Insert points
await client.points.upsert('products', [
{ id: 1, vector: new Array(128).fill(0.1), payload: { category: 'electronics' } },
{ id: 2, vector: new Array(128).fill(0.2), payload: { category: 'books' } },
]);
// Search with a filter
const filter = Filter.and(
Field.of('category').eq('electronics'),
);
const results = await client.points.search('products', new Array(128).fill(0.15), {
limit: 5,
filter,
});
console.log(results);
// Cleanup
await client.collections.delete('products');
client.close();Constructor Options
const client = new VectorAIClient('localhost:6574', {
tls: true,
tlsCaCert: '/path/to/ca.pem',
accessToken: 'vdai_my-secret-key',
timeout: 30,
maxRetries: 3,
});| Option | Type | Default | Description |
|---|---|---|---|
tls |
boolean |
false |
Enable TLS transport |
tlsCaCert |
string |
— | Path to CA certificate PEM file |
tlsClientCert |
string |
— | Path to client certificate (mTLS) |
tlsClientKey |
string |
— | Path to client private key (mTLS) |
accessToken |
string |
— | Access token for Bearer auth (or set ACTIAN_VECTORAI_ACCESS_TOKEN) |
tokenProvider |
() => string | Promise<string> |
— | Dynamic token provider |
restUrl |
string |
derived | REST API base URL for auth admin operations |
timeout |
number |
30 |
Per-RPC timeout in seconds (0 = no deadline) |
maxRetries |
number |
3 |
Max retry attempts on transient errors |
maxMessageSize |
number |
256 MiB |
Max gRPC message size in bytes |
enableTracing |
boolean |
true |
Add x-request-id / x-request-timestamp headers |
enableLogging |
boolean |
false |
Log RPC method + elapsed time |
logger |
(msg: string) => void |
console.log |
Custom logger for the logging interceptor |
metadata |
Record<string, string> |
— | Static metadata injected into every call |
grpcOptions |
Record<string, unknown> |
— | Additional gRPC channel options |
poolSize |
number |
1 |
Number of gRPC channels to pool |
circuitBreaker |
CircuitBreaker |
— | Circuit breaker instance for failure protection |
backpressure |
BackpressureConfig |
— | Backpressure configuration for flow control |
retryConfig |
RetryConfig |
— | Full retry config (overrides maxRetries) |
Authentication
The client supports static tokens, dynamic token providers, and environment-variable configuration via the Settings class.
Static token
const client = new VectorAIClient('localhost:6574', {
accessToken: 'vdai_abc123...',
});Environment variables
export ACTIAN_VECTORAI_URL=localhost:6574
export ACTIAN_VECTORAI_ACCESS_TOKEN=vdai_abc123...// No args needed — reads from env
const client = new VectorAIClient();
await client.healthCheck();AuthManager (admin operations)
import { AuthManager } from '@actian/vectorai-client';
const auth = new AuthManager('http://localhost:6573');
await auth.login('admin-password'); // obtain JWT
const key = await auth.createApiKey({ // create API key
name: 'my-service',
permission: 'read,write',
});
console.log(key.apiKey); // vdai_...Or via the client shortcut:
const client = new VectorAIClient('localhost:6574');
await client.auth.login('admin-password');
const keys = await client.auth.listApiKeys();Namespace Overview
client.collections — 8 methods
create, getInfo, list, delete, exists, update, recreate, getOrCreate
client.points — 17 methods
upsert, upsertSingle, delete, deleteByIds, get, setPayload, overwritePayload, deletePayload, clearPayload, updateVectors, search, searchBatch, count, query, queryBatch, scroll, scrollAll
client.vde — 15 methods
openCollection, closeCollection, getState, getVectorCount, getStats, getOptimizations, rebuildIndex, optimize, flush, importDataset, compactCollection, triggerRebuild, getRebuildTask, listRebuildTasks, cancelRebuildTask
Top-level helpers
healthCheck, connect, close, shutdown, uploadPoints, getAddress, isConnected (property)
Filter DSL
import { Field, Filter, FilterBuilder, hasId, hasVector, nested, isEmpty, isNull } from '@actian/vectorai-client';
// Field conditions
const f1 = Field.of('price').lt(100);
const f2 = Field.of('category').in(['electronics', 'books']);
const f3 = Field.of('tags').contains('sale');
// Aliases
const f2b = Field.of('category').anyOf(['electronics', 'books']); // same as .in()
// Datetime filters
const f9 = Field.of('created_at').datetimeGt(new Date('2024-01-01'));
const f10 = Field.of('expires').datetimeBetween(new Date('2024-01-01'), new Date('2024-12-31'));
// Geo conditions
const f4 = Field.of('location').geoRadius({ lat: 40.7, lon: -74.0 }, 5000);
// Utility conditions
const f5 = hasId([1, 2, 3]);
const f6 = hasVector('image_embedding');
const f7 = isEmpty('description'); // standalone factory
const f8 = nested('address', Filter.and(Field.of('city').eq('NYC')));
// Combine
const filter = Filter.and(f1, f2, Filter.not(f3));
// FilterBuilder (fluent must/should/mustNot composition)
const fb = new FilterBuilder();
fb.must(f1);
fb.should(f2).should(f3);
fb.withMinShould(1);
const builtFilter = fb.build(); // returns a Filter (recommended)
// Use with search
await client.points.search('products', queryVector, { filter, limit: 10 });Resilience
import { CircuitBreaker, BackpressureController, RetryConfig, createCircuitBreakerInterceptor } from '@actian/vectorai-client';
// Circuit breaker (standalone — not auto-wired to client)
const cb = new CircuitBreaker(/* failureThreshold */ 5, /* recoveryTimeout */ 30_000);
cb.ensureClosed(); // throws CircuitBreakerOpenError if open
cb.recordSuccess(); // after successful call
cb.recordFailure(); // after failed call
// Use as gRPC interceptor
const interceptor = createCircuitBreakerInterceptor(cb);
// Backpressure controller (adaptive concurrency)
const bp = new BackpressureController({ initialConcurrency: 16 });
await bp.acquire();
try { /* ... call ... */ } finally { bp.release(); }
// Retry config (standalone utility)
const rc = new RetryConfig({ maxRetries: 5, initialBackoffMs: 200 });
const delay = rc.computeDelay(/* attempt */ 2); // jittered exponential backoffException Hierarchy
VectorAIError
├── ConnectionError
│ ├── ConnectionRefusedError
│ ├── ConnectionTimeoutError
│ ├── NotConnectedError
│ ├── ChannelClosedError
│ └── ClientClosedError
├── AuthenticationError
│ ├── InvalidCredentialsError
│ └── PermissionDeniedError
├── CollectionError
│ ├── CollectionNotFoundError
│ ├── CollectionExistsError
│ ├── CollectionNotOpenError
│ └── CollectionNotReadyError
├── PointError
│ ├── PointNotFoundError (ids, collectionName)
│ └── DimensionMismatchError (expected, actual)
├── IndexError
├── PayloadKeyNotFoundError (key, collectionName)
├── ValidationError
├── ServerError
├── UnimplementedError
├── TimeoutError
├── RateLimitError (retryAfter?)
├── VectorLimitExceededError (currentCount?, maxAllowed?)
├── BatchError (total, failed, succeeded)
├── MaxRetriesExceededError (attempts, lastError)
└── CircuitBreakerOpenError (recoveryTime, failureCount)Documentation
- API Reference — Full method reference
- Examples — Runnable code samples
- License — Actian VectorAI DB License and Support Services Agreement
Development
Running Tests
# Unit tests (no server required)
npm test
# Integration tests (requires VectorAI server on localhost:6574)
npm run test:integration
# All tests
npm run test:all
# Unit tests with coverage
npm run test:coverageBuilding
npm run buildRunning Examples
npx tsx examples/01_hello_world.ts [server_address]Support
For support, feature requests, and bug reports, visit Actian Support.
Copyright © 2025 Actian Corporation. All Rights Reserved.