TypeScript and JavaScript SDK

Use the client from a Node.js service to run SQL and search your database. This guide describes the 1.0.0-rc.1 source candidate. It requires Node.js 18 or newer at runtime and Node.js 24 or newer to build the source checkout.

Get the SDKCopy Anchor Link

The SDK is available on GitHub. Follow the source-install steps in that README, then return here to run your first query. The 1.0 candidate package has not been released on registries; the examples below use its source API.

npm install @originchain/sdk@0.5.1

Connect and run SQLCopy Anchor Link

Set OC_URL to the complete database address from Connect and OC_TOKEN to its credential. Keep both in your server environment. Do not trim the URL path or derive a tenant ID from it.

With the candidate installed, save this as query.mjs and run node query.mjs:

import { Client } from "@originchain/sdk";

const db = Client.fromEnv();
const result = await db.sql.run("SELECT $1 AS value", [7]);
console.log(result.rows);

Expect one row with value equal to 7. It checks the connection without creating or changing data.

This query needs no table. $1 binds the first value in the array. Parameters substitute values, not table or column names. Reuse db for later requests instead of creating a client for every call. Keep database credentials out of browser bundles.

Choose the right credentialsCopy Anchor Link

Use the connection offered by Connect. Access-token support depends on the database configuration; other configurations retain their instance credentials. See authentication before changing a working integration. A PostgreSQL username and password are separate from the HTTP SDK credential.

Search other data modelsCopy Anchor Link

The following calls reuse db and require the named data to exist.

Full-text searchCopy Anchor Link

After indexing a text field, search it and read the hits:

const result = await db.fts.search("documents", "body", "account setup", {
  mode: "bm25",
  k: 10,
});
console.log(result.hits);

Inspect each hit's document ID to connect it to your source data. Scores rank results within the selected method; they are not confidence percentages. An empty hit list is a valid no-match result. Ranked, boolean and phrase searches expose the same hits-and-facets result structure; BM25 is the default mode.

Vector searchCopy Anchor Link

Use an embedding from the same model and dimension as the stored vectors. This three-number query is only a request-shape example.

const hits = await db.vector.search("embeddings", [0.1, 0.2, 0.3], {
  k: 5,
  metric: "cosine",
});
console.log(hits);

Graph queriesCopy Anchor Link

Use db.graph for Cypher, neighbors and breadth-first traversal. Prepare the tables and relationships with the graph quickstart before querying them. Cypher parameters are named; SQL parameters are positional.

Database and management APIsCopy Anchor Link

The candidate's common database namespaces are sql, schemas, rows, vector, fts and graph. Usage and query metrics are also available. Organization management uses a separate API and credential contract; a database connection does not grant organization permissions.

Handle results and errorsCopy Anchor Link

• Read result.rows for records and result.columns for column order.
• Preserve column_types, rows_affected, rows_buffered and nested results when your application needs them. The original envelope is in raw.
• A failed statement inside a batch raises BatchError; its result retains partial outcomes. A batch is not assumed atomic.
• HTTP errors expose status and request ID when supplied. Log those identifiers rather than a token or private response body.

Unsafe JSON numeric values remain strings to avoid JavaScript precision loss. Do not convert them to Number unless the value fits your application's range.

Timeouts and cancellationCopy Anchor Link

The default timeout is 60 seconds, with no automatic retries. Explicit retry options exist for compatibility; leave them off until the operation is proven safe to repeat. An aborted request can still have committed a write.

Missing write counts remain unknown. Inspect uncertain results before resubmitting SQL. See retry behavior.

ContinueCopy Anchor Link

SDK availability · SQL guide · HTTP API