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-client

Requires: 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 backoff

Exception 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:coverage

Building

npm run build

Running Examples

npx tsx examples/01_hello_world.ts [server_address]

Support

For support, feature requests, and bug reports, visit Actian Support.