SQL drivers SurrealDB extras

The native client has a few methods beyond SQL. They use the same connection, namespace, database and authentication as your SQL queries.

SurrealQL

The surql template runs SurrealQL. Each value binds as a variable, and a RecordId binds as type::record(...). The result has one entry for each SurrealQL statement.

const [people] = await sql.surql`SELECT * FROM person WHERE age > ${18}`;

Live queries

live subscribes to a table over a WebSocket. It yields { action, id, result } for each change, and kills the query when the loop ends. It throws if the WebSocket drops. LISTEN and NOTIFY are not emulated.

for await (const message of sql.live("person")) {
    console.log(message.action, message.id, message.result);
}

A client pinned to HTTP throws UnsupportedOnTransportError.

Describe

describe returns the column metadata and parameter types of a statement without running it.

const { columns, params } = await sql.describe("SELECT name FROM person WHERE name = $1");

Capabilities

capabilities() returns { supported, reason?, version?, transport }. It reports supported: false with a reason when the instance denies the method or the dialect route.

console.log(await sql.capabilities());

Another database

withDatabase returns a client for another database on the same instance.

const archive = sql.withDatabase("archive");

Vector parameters

In @surrealdb/pg, sql.vector(values) binds a vector parameter, for use with a vector distance operator.

await sql`SELECT id FROM item ORDER BY embedding <-> ${sql.vector([0.1, 0.2, 0.3])} LIMIT 5`;

Vector columns decode to Float32Array in both packages.