TypeScript SDK

TypeScript SDK

Connect RPC Node.js Browser

The QQL TypeScript SDK is a Connect RPC client that wraps the QQL gateway. Works in Node.js and browser environments.

Prerequisites

Start the QQL gateway:

Start gateway

qql-go serve --qdrant-url http://localhost:6334

Install

The QQL TypeScript SDK is not yet published to npm. Build from the repository:

npm:

npm install qql-client

yarn:

yarn add qql-client

from source:

cd sdks/typescript
npm install
npm run build

Quick Start

import { QQLClient } from "qql-client";

const client = new QQLClient("http://localhost:50051");

// Execute a query
const result = await client.exec("QUERY 'emergency triage' FROM docs LIMIT 5 USING HYBRID");
console.log(result.data);

// Batch queries
const results = await client.execBatch([
    "QUERY 'emergency triage' FROM docs LIMIT 5",
    "QUERY 'cardiac arrest' FROM docs LIMIT 5",
]);

// Explain without executing
const plan = await client.explain("QUERY 'search' FROM docs LIMIT 5 USING HYBRID RERANK");
console.log(plan);

// Health check
const health = await client.health();
console.log(health);

With Authentication

const client = new QQLClient("http://localhost:50051", {
    token: "eyJhbGciOiJSUzI1NiIs..."  // JWT bearer token
});

API

Method	Description
client.exec(query)	Execute a single QQL statement
client.execBatch(queries)	Execute multiple statements
client.explain(query)	Return execution plan without running
client.health()	Check gateway + Qdrant connectivity

Module Support

The TypeScript SDK ships dual CJS/ESM builds:

{
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/types/index.d.ts"
}

Response Type

interface ExecResult {
  ok: boolean;
  operation: string;
  message: string;
  data: unknown;  // decoded JSON
}

Using with curl (HTTP JSON)

The gateway also accepts raw HTTP calls without any SDK:

curl example

curl -X POST http://localhost:50051/qql.QQL/Exec
-H "Content-Type: application/json"
-d '{"query": "QUERY "search" FROM docs LIMIT 5 USING HYBRID"}'