OriginChainDB for TypeScript and JavaScript

The client for OriginChainDB: SQL, graph, vector and full-text search over one HTTP API. It runs on Node.js 18+ and in the browser, and ships with TypeScript types.

Install

npm install originchaindb

Connect

You need your database's endpoint, its tenant id and an API key. All three are in the OriginChain console, in your database's connection details.

import { Configuration, SqlApi, GraphApi, VectorApi, FtsApi } from "originchaindb";

const config = new Configuration({
  basePath: "https://your-database-endpoint",
  accessToken: process.env.ORIGINCHAIN_API_KEY,
});
const tenant = "your-tenant-id";

SQL

const result = await new SqlApi(config).sqlExec({
  tenant,
  sqlExecRequest: { sql: "SELECT id, name FROM people WHERE id = $1", params: ["bob"] },
});
console.log(result.columns, result.rows);

params binds $1, $2, … in order. A NULL cell is an absent key, so read cells by name against columns.

Graph

// One-hop neighbours of a node along a relation: their primary keys.
const managers = await new GraphApi(config).graphNeighbors({
  tenant, schema: "public.people", rel: "reports_to", pk: "bob",
});

Vector search

// The k stored vectors nearest to a query vector, best match first: [{ id, score }].
const nearest = await new VectorApi(config).vectorTopk({
  tenant, table: "doc_vectors", vectorTopkRequest: { query: [0.12, 0.98, 0.05], k: 5, dim: 3 },
});

Full-text search

// The ids of the documents whose `body` field matches.
const ids = await new FtsApi(config).ftsSearch({ tenant, table: "docs", field: "body", q: "vectors" });

Errors and request ids

A failed call throws a ResponseError. Its requestId is the database's id for that request. Quote it when you report a problem.

import { ResponseError } from "originchaindb";

try {
  await new SqlApi(config).sqlExec({ tenant, sqlExecRequest: { sql: "SELECT * FROM missing" } });
} catch (e) {
  if (e instanceof ResponseError) {
    console.error(e.response.status, e.requestId);
  }
}

Diagnostics (off by default)

You can opt in to send call diagnostics to your own database. They contain the method, the path, the outcome, the timing, the status and the request ids, and never SQL, parameters, row data, search text or error messages.

import { enableDiagnostics, flushDiagnostics } from "originchaindb";

enableDiagnostics(config);
// ... your calls ...
await flushDiagnostics(); // before the process exits

More

Every endpoint is documented at originchain.ai/docs.

License

MIT