JSPM

@actian/vectorai-client

1.0.2
  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 13
  • Score
    100M100P100Q56861F
  • License SEE LICENSE IN LICENSE

Node.js/TypeScript client for Actian VectorAI Database

Package Exports

  • @actian/vectorai-client

Readme

Actian   Node.js

Node.js/TypeScript client library for Actian VectorAI Database.

npm version Node.js 18+

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 APIclient.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.


Copyright © 2025 Actian Corporation. All Rights Reserved.