SDK Reference

VectorScaleDB provides native SDKs for Python, Rust, and Node.js. All three offer full type safety, async support, and WebSocket subscription support. Every SDK is generated from one live OpenAPI 3.1 specification — none are hand-maintained — so all three stay in guaranteed feature parity with the API and never drift. Go SDK is planned. For AI agent integration, see the MCP Server section below.

Installation

Available at launch

SDK packages publish to PyPI, crates.io, and npm at launch. Until then, request early access for pre-release builds. The commands below show how installation will work once packages are published.

Python

pip install vectorscaledb

Rust (Cargo.toml)

[dependencies]
vectorscale-client = "0.1"

Node.js

npm install @vectorscaledb/client

Python SDK

Connecting

Python

from vectorscaledb import Client

# Basic connection
client = Client("https://api.vectorscaledb.com")

# With authentication
client = Client(
    "https://api.vectorscaledb.com",
    api_key="your-api-key",
    tenant_id="your-tenant"
)

Tip

Store your API key in an environment variable and pass it via os.environ["VSDB_API_KEY"] rather than hardcoding it in source files.

Ingesting Data

Python

# Single vector
client.ingest(
    entity_id="vehicle-001",
    vector=[0.1, 0.8, 0.3, 0.9, 0.2, 0.7],
    entity_type="TRACKED_OBJECT"
)

# Batch ingestion
vectors = [
    {"entity_id": f"sensor-{i}", "vector": [...], "entity_type": "LINK_METRIC"}
    for i in range(10000)
]
result = client.ingest_batch(vectors, parallelism=4)
print(f"Ingested: {result.ingested}, Compressed: {result.compressed}")

Info

Batch ingestion automatically partitions data across parallel writers. The parallelism parameter controls the number of concurrent connections used.

Querying

Python

# Temporal KNN
results = client.temporal_knn(
    query_vector=[0.1, 0.7, 0.4, 0.8],
    start_time="2025-01-01T00:00:00Z",
    end_time="2025-12-31T23:59:59Z",
    k=10
)

# Trajectory similarity
similar = client.trajectory_similarity(
    entity_id="vehicle-001",
    time_range=("2025-06-01T00:00:00Z", "2025-06-01T01:00:00Z"),
    k=5
)

# Anomaly detection
anomalies = client.anomaly_score(
    entity_id="sensor-42",
    lookback_hours=24
)

Streaming

Python

# Subscribe to changes
for event in client.stream_changes(entity_types=["TRACKED_OBJECT"]):
    print(f"Entity {event.entity_id} updated: {event.change_type}")

Tip

The streaming API uses server-sent events under the hood. The iterator blocks until a new event arrives, so run it in a background thread or async task for non-blocking consumption.

Rust SDK

Connecting

Rust

use vectorscale_client::Client;

// Basic connection
let client = Client::builder()
    .url("https://api.vectorscaledb.com")
    .build()?;

// With authentication
let client = Client::builder()
    .url("https://api.vectorscaledb.com")
    .api_key("your-api-key")
    .tenant_id("your-tenant")
    .build()?;

Ingesting Data

Rust

// Single vector
client.ingest("vehicle-001", &[0.1, 0.8, 0.3, 0.9])
    .entity_type("TRACKED_OBJECT")
    .send().await?;

// Batch ingestion
let batch: Vec<IngestRequest> = (0..10000)
    .map(|i| IngestRequest {
        entity_id: format!("sensor-{}", i),
        vector: vec![0.1, 0.8, 0.3, 0.9],
        entity_type: "LINK_METRIC".into(),
    })
    .collect();

let result = client.ingest_batch(batch)
    .parallelism(4)
    .send().await?;

Querying

Rust

use chrono::{Utc, TimeZone};

let start = Utc.with_ymd_and_hms(2025, 1, 1, 0, 0, 0).unwrap();
let end = Utc.with_ymd_and_hms(2025, 12, 31, 23, 59, 59).unwrap();

// Temporal KNN
let results = client.temporal_knn(&[0.1, 0.7, 0.4, 0.8])
    .time_range(start, end)
    .k(10)
    .send().await?;

// Trajectory similarity
let similar = client.trajectory_similarity("vehicle-001")
    .time_range(start, end)
    .k(5)
    .send().await?;

// Anomaly detection
let anomalies = client.anomaly_score("sensor-42")
    .lookback_hours(24)
    .send().await?;

Streaming

Rust

use futures::StreamExt;

let mut stream = client.stream_changes()
    .entity_types(&["TRACKED_OBJECT"])
    .subscribe().await?;

while let Some(event) = stream.next().await {
    let event = event?;
    println!("Entity {} updated: {:?}", event.entity_id, event.change_type);
}

Node.js SDK

Connecting

JavaScript

import { VectorScaleClient } from '@vectorscaledb/client';

// Basic connection
const client = new VectorScaleClient({
  url: 'https://api.vectorscaledb.com'
});

// With authentication
const client = new VectorScaleClient({
  url: 'https://api.vectorscaledb.com',
  apiKey: 'your-api-key',
  tenantId: 'your-tenant'
});

Ingesting Data

JavaScript

// Single vector
await client.ingest({
  entityId: 'sensor-42',
  vector: [0.1, 0.8, 0.3, 0.9],
  entityType: 'LINK_METRIC'
});

// Batch ingestion
const vectors = Array.from({ length: 10000 }, (_, i) => ({
  entityId: `sensor-${i}`,
  vector: [0.1, 0.8, 0.3, 0.9],
  entityType: 'LINK_METRIC'
}));

const result = await client.ingestBatch(vectors, { parallelism: 4 });
console.log(`Ingested: ${result.ingested}, Compressed: ${result.compressed}`);

Querying

JavaScript

// Temporal KNN
const results = await client.temporalKnn({
  queryVector: [0.1, 0.7, 0.4, 0.8],
  startTime: '2025-01-01T00:00:00Z',
  endTime: '2025-12-31T23:59:59Z',
  k: 5
});

// Trajectory similarity
const similar = await client.trajectorySimilarity({
  entityId: 'vehicle-001',
  timeRange: ['2025-06-01T00:00:00Z', '2025-06-01T01:00:00Z'],
  k: 5
});

// Anomaly detection
const anomalies = await client.anomalyScore({
  entityId: 'sensor-42',
  lookbackHours: 24
});

Streaming

JavaScript

// Subscribe to changes
const stream = client.streamChanges({
  entityTypes: ['AUTONOMOUS_VEHICLE']
});

stream.on('data', (event) => {
  console.log(`Entity ${event.entityId} updated: ${event.changeType}`);
});

stream.on('error', (err) => {
  console.error('Stream error:', err);
});

Error Handling

All SDKs use structured error types that map directly to API error responses. Errors include a machine-readable code, a human-readable message, and the originating request ID for tracing.

Python

from vectorscaledb.exceptions import (
    VsdbError,
    AuthenticationError,
    RateLimitError,
    EntityNotFoundError
)

try:
    result = client.temporal_knn(
        query_vector=[0.1, 0.7, 0.4, 0.8],
        start_time="2025-01-01T00:00:00Z",
        end_time="2025-12-31T23:59:59Z",
        k=5
    )
except AuthenticationError:
    print("Invalid or expired API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except VsdbError as e:
    print(f"Error {e.code}: {e.message} (request: {e.request_id})")

Rust

use vectorscale_client::Error;

match client.temporal_knn(&query).k(10).send().await {
    Ok(results) => { /* process results */ }
    Err(Error::Authentication) => {
        eprintln!("Invalid or expired API key");
    }
    Err(Error::RateLimit { retry_after }) => {
        eprintln!("Rate limited. Retry after {}s", retry_after);
    }
    Err(e) => {
        eprintln!("Error: {} (request: {})", e.message(), e.request_id());
    }
}

Node.js

JavaScript

import { VsdbError, AuthenticationError, RateLimitError } from '@vectorscaledb/client';

try {
  const results = await client.temporalKnn({
    queryVector: [0.1, 0.7, 0.4, 0.8],
    startTime: '2025-01-01T00:00:00Z',
    endTime: '2025-12-31T23:59:59Z',
    k: 5
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Invalid or expired API key');
  } else if (err instanceof RateLimitError) {
    console.error(`Rate limited. Retry after ${err.retryAfter}s`);
  } else if (err instanceof VsdbError) {
    console.error(`Error ${err.code}: ${err.message} (request: ${err.requestId})`);
  }
}

Info

All error responses include a request_id field. Include this ID when contacting support to help with diagnosis.

MCP Server (AI Agent Integration)

The VectorScaleDB MCP server exposes 30+ tools across 6 categories via the Model Context Protocol, enabling AI agents like Claude to interact with your database directly. The server supports three operating modes: client (HTTP proxy to a running instance), standalone (embedded engine), and network (federated node). It communicates with AI agents over stdio transport.

Capabilities (24 Categories)

Ingest tools -- Vector ingestion, batch operations, entity management
Query tools -- Temporal KNN, trajectory similarity, anomaly scoring
Analysis tools -- Regime detection, pattern matching, compression metrics
Exploration tools -- Entity search, history browsing, segment inspection
Cross-domain tools -- Cascade detection, domain composition, cross-domain alerting
Health tools -- Readiness, liveness, startup probes, and cluster status
IoT tools -- Sensor anomaly detection, predictive maintenance, fleet health
NPC / Social tools -- NPC response prediction, faction cohesion, social cascades
BCI / Consent tools -- BCI session management, consent gate operations, skill distillation
Genomics tools -- Expression regime detection, variant impact analysis, cell trajectory tracking
Neuroscience tools -- Operating modes, consolidation, criticality, pattern separation
Trust tools -- Trust scoring, threshold operations, license verification
Inventory tools -- Container management, item tracking, audit log replay
Storage tools -- Document, graph, blob, and full-text search operations
Deployment tools -- Deployment configuration, hardware resource profiling, and adaptive resource tuning

Configuration

Add the MCP server to your AI agent's configuration to enable database access:

JSON

{
  "mcpServers": {
    "vectorscaledb": {
      "command": "vectorscale-mcp",
      "args": ["--url", "https://api.vectorscaledb.com", "--token", "your-api-key"]
    }
  }
}

Tip

The MCP server works with any MCP-compatible AI client, including Claude Code and Claude Desktop. It uses stdio transport, so the AI agent spawns it as a subprocess.