TypeScript SDK
npm install @zysec-ai/relata-sdk — zero runtime dependencies. Uses native fetch, so it runs unchanged in Node.js 18+, Deno, Bun, modern browsers, and edge runtimes (Cloudflare Workers, Vercel Edge). Optional peer deps: apache-arrow + @grpc/grpc-js for Arrow Flight, @langchain/* for the adapters.
See the SDK overview for the cross-language parity matrix. This page is the TypeScript capability catalog.
Quickstart
npm install @zysec-ai/relata-sdkimport { createClient } from "@zysec-ai/relata-sdk";
const relata = createClient("http://localhost:9090", {
defaultPurpose: "analytics",
bearerToken: process.env.RELATA_TOKEN,
});
await relata.query(
"INSERT INTO Person (_pk, name, email) VALUES ('p1', 'Alice', 'a@x.com')",
);
const result = await relata.query("SELECT * FROM Person LIMIT 5");
for (const row of result.rows) console.log(row.name, row.email);The SDK is async-native — every method returns a Promise. Native fetch means no connection pool to close.
The query surface
| Path | Method | Returns |
|---|---|---|
| SQL | query<T>(sql, opts?) | QueryResult<T> — opts.dialect: "sql" | "cypher" | "gql" |
| Parameterized | queryWithParams<T>(sql, params, opts?) | QueryResult<T> |
| Arrow Flight (gRPC) | queryFlight<T>(sql, opts?) | apache-arrow Table (optional peer) |
| GraphQL | graphql(query, variables?, operationName?) | unknown — variables bound server-side (#3260) |
| SPARQL | sparql(query) | Record |
| Cypher | any MATCH-prefixed string via query() | auto-routed, governed |
| GQL (ISO 39075) | query(stmt, { dialect: "gql" }) | header-selected, governed (#3265) |
| Fluent builder | relata.select("Person").where(...).limit(10).execute<T>() | QueryResult<T> |
| Paths builder | relata.select("Person").pathsBetween("a","b",{maxHops:5}).execute() | QueryResult |
import { createClient } from "@zysec-ai/relata-sdk";
const relata = createClient("http://localhost:9090", { defaultPurpose: "investigation" });
const paths = await relata.select("Person")
.pathsBetween("alice-id", "bob-id", { maxHops: 5 })
.withProvenance()
.execute();Typed domain clients
Each typed client has a static fromClient(client) factory inheriting auth/tenant/purpose/timeout:
import {
GovernanceClient, IdentityClient, ObjectClient, IngestClient,
VectorClient, SearchClient, StreamingClient, AuditClient,
TenantAdminClient, BackupClient, TokenClient, LogClient,
SystemClient, A2AClient, McpClient, S3Client,
} from "@zysec-ai/relata-sdk";| Client | Key methods | Cross-ref |
|---|---|---|
GovernanceClient | rules CRUD, Sigma import, retention/WORM/legal-holds, breakglass, alerts, DSAR | Detection Rules |
IdentityClient | label, recordUncertainty, registerLookup/listLookups/invokeLookup, eraseSubject | Identity |
ObjectClient | upsert, typedUpsert, batchUpsert, get, delete, list (TS-only) | — |
IngestClient | bulk, bulkCsv, ingestAuto, ingestCdr, otlpTraces/Logs/Metrics, ingestIter (AsyncIterable) | Ingestion |
VectorClient | knnSearch, hybridSearch, similarTo, embed/embedBatch + embedImage/Face/Audio/Video | Hybrid Search |
SearchClient | typed /search JSON door: query<T>({from, text, rankBy, filters, limit, ...}) | Search reference |
StreamingClient | queryRows (NDJSON), queryArrowRaw, watch (SSE), alerts (SSE) — all async generators | — |
AuditClient | count, entries, findByRequestId, signReceipt, exportPdf → Uint8Array | — |
TenantAdminClient | tenant CRUD, quota, sharing, platform usage/license | Multi-Tenancy |
BackupClient | create, list, restore, restoreStatus, compact, waitForRestore | Backup & Restore |
TokenClient | remember, check, revoke, stats | — |
LogClient | append, head, loadLeaves | — |
SystemClient | LLM config/test, jobs/workflows, feeds, notifications, pipelines | — |
A2AClient | submitTask, getTask, checkpoints, agentCard | — |
McpClient | initialize, listTools, callTool + 68 typed wrappers | MCP Tools |
S3Client | http, listBuckets, createBucket, putObject, getObject, deleteObject | S3 door |
Vectors & embeddings
const vc = new VectorClient(relata);
// Pure KNN over a named slot
const knn = await vc.knnSearch("Document", "embedding", [0.1,...], { k: 10, efSearch: 200 });
// Hybrid: BM25 + vector + graph, RRF-fused
const hybrid = await vc.hybridSearch("Document",
{ queryText: "graph retrieval", k: 10, rerank: true, weights: [0.2, 0.5, 0.3] });
// Embedding (6 modalities)
const e = await vc.embed("Alice Smith"); // → {embedding, model, dim}
await vc.embedImage(b64); await vc.embedFace(b64);
await vc.embedAudio(b64); await vc.embedVideo(b64);Graph & intelligence operators
All on RelataClient — 10 graph algorithms + 10 AML/financial + 3 maritime:
await relata.graphPageRank("Person", { damping: 0.85, maxIter: 20 });
await relata.graphShortestPath("alice-id", "bob-id", { maxHops: 5 });
await relata.graphCommunity("Person");
await relata.sanctionsScreen("Acme Holdings", { threshold: 0.85 });
await relata.beneficialOwnershipChain("Acme Holdings", { maxDepth: 6 });
await relata.cryptoTrace("0xabc...", "compliance");
await relata.vesselTrack(123456789, { windowSecs: 86400 });
await relata.darkFleetDetect({ maxGapHours: 48 });See Graph Analytics.
Agent memory — 10 cognitive verbs + recall-quality knobs
import { Memory } from "@zysec-ai/relata-sdk";
const mem = new Memory("http://localhost:9090", { purpose: "agent", bearerToken: "<token>" });
const id = await mem.add("Alice prefers dark mode", { confidence: 0.9 });
// retrieval-quality operators
const results = await mem.search("ui preferences", {
topK: 10, minConfidence: 0.6, recencyHalfLifeSecs: 259200,
budgetTokens: 1500, cancelThreshold: 0.92,
});
const detail = await mem.searchDetailed("ui preferences", { /* same opts */ });
// detail.recall_cost_tokens + detail.cancelled — observe the knobs' effectFull verb set: add, addBatch, search, searchDetailed, get, update, forget, associate, episodes, justify, resolve, summarise. See Agent memory reference.
Ecosystem (TS extras)
| Extra | Surface |
|---|---|
| LangChain adapter | RelataMemory — duck-typed BaseMemory (loadMemoryVariables, saveContext, clear) |
| LlamaIndex adapter | RelataMemory — put/get/getAll/reset |
| LangGraph checkpointer | RelataCheckpointer — real BaseCheckpointSaver subclass (getTuple/list/put/putWrites; deleteThread throws — server has no DELETE route) |
| Arrow Flight transport | ArrowFlightTransport + createArrowFlightTransport() — hand-rolled protobuf codec, no proto-loader |
| CLI binary | npx @zysec-ai/relata-sdk — health, status, audit (exit 2 on broken chain), nodes, query <sql>; reads RELATA_TOKEN/RELATA_PURPOSE |
Install the optional peers (@langchain/langgraph-checkpoint, @langchain/core, apache-arrow, @grpc/grpc-js) to activate the matching surface.
Authentication & multi-tenant
const relata = createClient("http://localhost:9090", {
bearerToken: process.env.RELATA_TOKEN,
defaultPurpose: "analytics",
tenant: "org-acme", // X-Relata-Tenant-Id on every request
actingAs: "user-42", // X-Acting-As (delegation)
delegatedBy: "admin-1", // X-Delegated-By
timeoutMs: 15_000,
maxRetries: 3,
retryBackoffMs: 500,
adminBaseUrl: "http://admin.internal:9090", // /admin/* + /platform/* split
});Runtime compatibility
Native fetch, zero deps — runs in Node.js 18+, Deno, Bun, modern browsers, Cloudflare Workers, Vercel Edge Functions.
Examples
~25 runnable examples in sdks/typescript/examples/. Run with Node 23+ (--experimental-strip-types), Deno, or Bun:
RELATA_TOKEN=secret node --experimental-strip-types examples/basic-query.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/memory-quickstart.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/intelligence.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/graph-algorithms.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/streaming.ts
RELATA_TOKEN=secret node --experimental-strip-types examples/face-search.tsFull set: sdks/typescript/examples/.
Next steps
- Search and retrieval — typed
/search, multi-query batch + RRF - Agent memory reference — 10 verbs + recall-quality knobs
- Graph analytics — 10+ algorithms,
gds.*portability - Query cookbook
- Full TypeScript SDK source