TypeScript SDK

Relata DB 3.0
SDK method names are mostly unchanged in 3.0, but the SDKs call the new /v1 routes and some wrappers are removed or reshaped (tenant administration, cluster operations, webhooks, dedup tokens, media embedding). See the SDK changes. Python, TypeScript and Go are the only supported SDKs.

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-sdk
import { createClient, IngestClient } from "@zysec-ai/relata-sdk";
 
const relata = createClient("http://localhost:9090", {
  defaultPurpose: "analytics",
  bearerToken: process.env.RELATA_TOKEN,
});
 
// /query is read-only (#782) — writes go through the governed ingest door.
const ingest = IngestClient.fromClient(relata);
await ingest.bulk("Person", [{ id: "p1", name: "Alice", email: "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

PathMethodReturns
SQLquery<T>(sql, opts?)QueryResult<T> — opts.dialect: "sql" | "cypher" | "gql"
ParameterizedqueryWithParams<T>(sql, params, opts?)QueryResult<T>
Arrow Flight (gRPC)queryFlight<T>(sql, opts?)apache-arrow Table (optional peer)
GraphQLgraphql(query, variables?, operationName?)unknown — variables bound server-side (#3260)
SPARQLsparql(query)Record
Cypherany MATCH-prefixed string via query()auto-routed, governed
GQL (ISO 39075)query(stmt, { dialect: "gql" })header-selected, governed (#3265)
Fluent builderrelata.select("Person").where(...).limit(10).execute<T>()QueryResult<T>
Paths builderrelata.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";
ClientKey methodsCross-ref
GovernanceClientrules CRUD, Sigma import, retention/WORM/legal-holds, breakglass, alerts, DSARDetection Rules
IdentityClientlabel, recordUncertainty, registerLookup/listLookups/invokeLookup, eraseSubjectIdentity
ObjectClientupsert, typedUpsert, batchUpsert, get, delete, list (TS-only)—
IngestClientbulk, bulkCsv, ingestAuto, ingestCdr, otlpTraces/Logs/Metrics, ingestIter (AsyncIterable)Ingestion
VectorClientknnSearch, hybridSearch, similarTo, embed/embedBatch + embedImage/Face/Audio/VideoHybrid Search
SearchClienttyped /search JSON door: query<T>({from, text, rankBy, filters, limit, ...})Search reference
StreamingClientqueryRows (NDJSON), queryArrowRaw, watch (SSE), alerts (SSE) — all async generators—
AuditClientcount, entries, findByRequestId, signReceipt, exportPdf → Uint8Array—
TenantAdminClienttenant CRUD, quota, sharing, platform usage/licenseEnterprise edition only; the open build has one tenant
BackupClientcreate, list, restore, restoreStatus, compact, waitForRestoreBackup & Restore
TokenClientremember, check, revoke, stats—
LogClientappend, head, loadLeaves—
SystemClientLLM config/test, jobs/workflows, feeds, notifications, pipelines—
A2AClientsubmitTask, getTask, checkpoints, agentCard—
McpClientinitialize, listTools, callTool + 68 typed wrappersMCP Tools
S3Clienthttp, listBuckets, createBucket, putObject, getObject, deleteObjectS3 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' effect

Full verb set: add, addBatch, search, searchDetailed, get, update, forget, associate, episodes, justify, resolve, summarise. See Agent memory reference.

Ecosystem (TS extras)

ExtraSurface
LangChain adapterRelataMemory — duck-typed BaseMemory (loadMemoryVariables, saveContext, clear)
LlamaIndex adapterRelataMemory — put/get/getAll/reset
LangGraph checkpointerRelataCheckpointer — real BaseCheckpointSaver subclass (getTuple/list/put/putWrites; deleteThread throws — server has no DELETE route)
Arrow Flight transportArrowFlightTransport + createArrowFlightTransport() — hand-rolled protobuf codec, no proto-loader
CLI binarynpx @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.ts

Full set: sdks/typescript/examples/.

Next steps