Skip to content
ParticleDB

Browser / Web SDK

The @particledb/web package in this repo is a browser-oriented SDK built around a WebSocket transport abstraction. Important caveat: the default ParticleDB server path today exposes SSE streaming over HTTP, not a production WebSocket upgrade endpoint. Treat this SDK as experimental unless you have explicitly wired a compatible WebSocket endpoint into your deployment.

Installation

Section titled “Installation”
Terminal window
npm install @particledb/web

Status

Section titled “Status”
  • Good fit if you are extending the repo and controlling both client and server
  • Not the default quickstart path for a stock ParticleDB server build
  • For browser-friendly incremental results today, use the HTTP/SSE path documented in HTTP API

Example

Section titled “Example”
import { ParticleDBWeb } from '@particledb/web';


const db = new ParticleDBWeb({ wsUrl: 'ws://localhost:8080' });
await db.connect();


// SQL queries
const result = await db.query('SELECT * FROM users WHERE id = 1');
console.log(result.rows);


// Vector search
const results = await db.vector.search('docs', 'embedding', [0.1, 0.2, 0.3], 5);


// Key-value
await db.kv.set('key', 'value');
const val = await db.kv.get('key');


// RAG
const answer = await db.rag.query('What is ParticleDB?',
  'documents', 'embedding', 'content');


// AI
const embedding = await db.ai.embed('Hello world');


// Pub/sub
db.subscribe('events', (payload) => console.log('Event:', payload));


db.disconnect();

Configuration

Section titled “Configuration”
const db = new ParticleDBWeb({
  wsUrl: 'ws://localhost:8080',     // Custom WebSocket endpoint
  httpUrl: 'http://localhost:8080', // HTTP API URL (future use)
  apiKey: 'your-api-key',          // Authentication token
  reconnect: true,                  // Auto-reconnect (default: true)
  maxRetries: 5,                    // Max reconnect attempts (default: 5)
});

SQL Queries

Section titled “SQL Queries”
// Query with results
const result = await db.query('SELECT * FROM users');
console.log(result.rows);


// Execute DML
const affected = await db.execute('INSERT INTO users (id, name) VALUES (1, "alice")');
Section titled “Vector Search”
const results = await db.vector.search('documents', 'embedding', [0.1, 0.2, 0.3], 5);
for (const { row, distance } of results) {
  console.log(`${row.title}: ${distance}`);
}

Key-Value Operations

Section titled “Key-Value Operations”
await db.kv.set('session:123', '{"user":"alice"}');
const val = await db.kv.get('session:123');
await db.kv.delete('session:123');

RAG (Retrieval-Augmented Generation)

Section titled “RAG (Retrieval-Augmented Generation)”
const answer = await db.rag.query(
  'What is ParticleDB?',
  'documents', 'embedding', 'content'
);
console.log(answer);

AI Functions

Section titled “AI Functions”
const embedding = await db.ai.embed('Hello world');
const text = await db.ai.generate('Explain vector databases');
const label = await db.ai.classify('Great!', ['positive', 'negative']);

Real-Time Pub/Sub

Section titled “Real-Time Pub/Sub”

Subscribe to server-side events in real time:

// Subscribe to a channel
db.subscribe('events', (payload) => {
  console.log('Received event:', payload);
});


// Multiple subscriptions
db.subscribe('cdc_users', (event) => {
  console.log(`User ${event.event}: ${event.payload}`);
});

Architecture

Section titled “Architecture”

The SDK uses a layered architecture:

  • WebSocketTransport — Manages WebSocket connection lifecycle, message correlation, reconnection, and pub/sub routing
  • ParticleDBWeb — Main client providing query(), execute(), subscribe(), and lazy-initialized operation modules
  • SqlBuilder — Pure-function SQL generation (no dependencies, independently testable)
  • VectorOps / KVOps / RAGOps / AIOps — Typed operation wrappers composing SqlBuilder + client query functions
Section titled “Recommended default for most users”

If you are not specifically working on the WebSocket transport itself, start with:

Next Steps

Section titled “Next Steps”