Surqlize

https://github.com/surrealdb/surqlize
Admin
Surqlize is a type-safe TypeScript ORM for SurrealDB that provides full type inference, fluent query...
Tokens:105,236
Snippets:853
Trust Score:9.8
License:Apache-2.0
Update:1 month ago
Show doc for...
Tokens:
Raw
### Usage Example: Basic GET + POST

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/api-client.md

Example showing how to create an ApiClient and use get and post methods.

```APIDOC
## Usage Example: Basic GET + POST

### Description
Example showing how to create an ApiClient and use get and post methods.

### Example
```ts
// Basic GET + POST
const usersEndpoint = api("/users", {
  get: { response: t.array(user.schema) },
  post: { request: t.object({ name: t.string() }), response: user.schema },
});

const client = db.api(usersEndpoint);

const list = await client.get("/users");               // ApiResponse<User[]>
const created = await client.post("/users", { name: "Ada" });
```
```

--------------------------------

### Example usage of api()

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/schema.md

An example of defining a users endpoint with GET and POST methods, then initializing a client.

```ts
const usersEndpoint = api("/users", {
  get: { response: t.array(user.schema) },
  post: { request: t.object({ name: t.string() }), response: user.schema },
});
const client = db.api(usersEndpoint); // see api-client.md
```

--------------------------------

### Quick start with surqlize ORM

Source: https://github.com/surrealdb/surqlize/blob/main/README.md

Shows the basic setup of surqlize: define a table schema, create an ORM instance with a Surreal connection, and build a type-safe query. The inferred return type is demonstrated with a comment.

```typescript
import { Surreal } from "surrealdb";
import { orm, table, t } from "surqlize";

// Define a table schema
const user = table("user", {
  name: t.string(),
  email: t.string(),
  age: t.number(),
  created: t.date(),
});

// Create ORM instance
const db = orm(new Surreal(), user);

// Build type-safe queries
const query = db
  .select("user")
  .where((user) => user.age.gte(18))
  .return((user) => ({
    name: user.name,
    email: user.email,
  }));

// TypeScript knows the exact return type!
type Result = t.infer<typeof query>;
// Result: Array<{ name: string; email: string }>
```

--------------------------------

### SurrealQL file functions

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-file.md

SurrealQL examples for file functions: bucket, key, put, get, and list. The get example uses optional chaining and to_string to handle potential null results.

```surql
RETURN file::bucket(f"media:/avatar.png");
RETURN file::key(f"media:/avatar.png");
RETURN file::put(f"media:/avatar.png", <bytes>"data");
RETURN file::get(f"media:/avatar.png").?.to_string();
RETURN file::list("media", { prefix: "/avatars" }).map(|$v| $v.{ file, size });
```

--------------------------------

### SurrealQL HTTP function examples (get, post, patch, delete)

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-http.md

SurrealQL examples for the http::get, http::post, http::patch, and http::delete functions. These are async server functions that must be used within a query context.

```surql
RETURN http::get("https://example.com/data.json");
RETURN http::post("https://example.com/items", { name: "one" });
RETURN http::patch("https://example.com/items/1", { name: "two" });
RETURN http::delete("https://example.com/items/1");
```

--------------------------------

### Set up tables and edges for graph traversal

Source: https://github.com/surrealdb/surqlize/blob/main/README.md

Sets up tables and edges for graph traversal examples. Defines `user`, `post`, `tag` tables and `authored` and `tagged` edges, then creates an ORM instance with `orm(new Surreal(), ...)`. This setup is used by the traversal examples that follow.

```typescript
const user = table("user", { name: t.string() });
const post = table("post", { title: t.string() });
const tag = table("tag", { label: t.string() });
const authored = edge("user", "authored", "post", {
  created: t.date(),
  role: t.string(),
});
const tagged = edge("post", "tagged", "tag", {});

const db = orm(new Surreal(), user, post, tag, authored, tagged);
```

--------------------------------

### Development commands with Bun

Source: https://github.com/surrealdb/surqlize/blob/main/README.md

Development commands for the surqlize project using Bun. Install dependencies, build, run the example, execute unit and integration tests (integration requires SurrealDB), type-check, and run lint/format checks (qc, qa, qau).

```bash
# Install dependencies
bun install

# Build the project
bun run build

# Run the example file
bun run examples/demo.ts

# Run tests
bun run test:unit          # Unit tests
bun run test:integration   # Integration tests (requires SurrealDB)
bun run type-check         # TypeScript type checking

# Lint and format
bun run qc   # Check for issues
bun run qa   # Auto-fix issues
bun run qau  # Auto-fix with unsafe changes
```

--------------------------------

### Mutation return examples

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/mutation-queries.md

Examples demonstrating basic return modes, diff mode for raw results, and projection callbacks.

```ts
// Basic
const created = await db
  .create("user", "alice123")
  .set({ name: "Alice", age: 30 })
  .return("after");
// diff skips schema parsing entirely
const diff = await db.update("user", "alice").set({ age: 31 }).return("diff");
// projection callback
const nick = await db
  .update("user", "alice")
  .set({ age: 31 })
  .return((u) => ({ name: u.name }));
```

--------------------------------

### start() and limit() method signatures

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/select-query.md

Signatures for the start() and limit() methods. start() takes a row offset and renders ' START $n', while limit() takes a max row count and renders ' LIMIT $n'.

```TypeScript
start(start: number)
limit(limit: number)
```

--------------------------------

### TypeScript HTTP function examples (get, post, patch, delete)

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-http.md

TypeScript examples using the fn.http.get, fn.http.post, fn.http.patch, and fn.http.delete methods from surqlize. These functions are async server functions and must remain as Expr<T> until query execution. Generic response typing is supported, e.g., fn.http.get<MyShape>(url).

```ts
fn.http.get("https://example.com/data.json");
fn.http.post("https://example.com/items", { name: "one" });
fn.http.patch("https://example.com/items/1", { name: "two" });
fn.http.delete("https://example.com/items/1");
```

--------------------------------

### Install surqlize with Bun or npm

Source: https://github.com/surrealdb/surqlize/blob/main/README.md

Install surqlize using either the Bun or npm package manager. The npm command is provided as an alternative to the Bun command.

```bash
bun add surqlize
```

```bash
npm install surqlize
```

--------------------------------

### SURQL SELECT statement examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-select.md

Various examples of the SELECT statement in SURQL, including projections, index hints, grouping, ordering, and explain plans.

```surql
SELECT * FROM foo;
SELECT a AS b, c FROM foo, bar;
SELECT * FROM ONLY foo WITH INDEX a, b;
SELECT * FROM ONLY foo WITH NO INDEX WHERE 1 == 2 SPLIT ON a, b;
SELECT * FROM ONLY foo WHERE 1 == 2 GROUP BY a, b ORDER BY a LIMIT 1 START 1 VERSION 1 TIMEOUT 1s TEMPFILES;
SELECT count() FROM t GROUP ALL EXPLAIN;
EXPLAIN ANALYZE SELECT id FROM t WHERE id[1] = o:1 AND b = 2025;
```

--------------------------------

### start() / limit()

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/select-query.md

Methods to set the row offset and maximum number of rows for the select query. They render as START $n and LIMIT $n respectively.

```APIDOC
## start() / limit()

### Description
Sets the row offset and maximum number of rows for the select query. The start method renders as START $n, and the limit method renders as LIMIT $n.

### Method
start(start: number)
limit(limit: number)

### Parameters
- **start** (number) - Required - Row offset, renders START $n.
- **limit** (number) - Required - Max rows, renders LIMIT $n.

```

--------------------------------

### TypeScript file functions

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-file.md

TypeScript examples for the same file functions using the surqlize API. The get example uses optional() and fn.toString() to handle null results.

```ts
const avatar = q.file("media", "/avatar.png");

fn.file.bucket(avatar);
fn.file.key(avatar);
fn.file.put(avatar, q.bytes("data"));
fn.file.get(avatar).optional().fn.toString();

fn.file.list("media", { prefix: "/avatars" })
  .fn.map(($v) => $v.pick("file", "size"));
```

--------------------------------

### SurrealQL EXPLAIN examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-explain.md

Shows the prefix EXPLAIN form with and without ANALYZE, and the trailing EXPLAIN form with FULL option. The first example explains a SELECT with a nested condition, the second explains an ANALYZE of a grouped count query, the third uses trailing EXPLAIN on a SELECT with a full-text match, and the fourth uses trailing EXPLAIN FULL on an UPDATE with ONLY and RETURN DIFF.

```surql
EXPLAIN SELECT * FROM student WHERE marks.*.mark = 40;
EXPLAIN ANALYZE SELECT count() AS total FROM sale GROUP ALL;
SELECT name FROM person WHERE name @@ "Jaime" EXPLAIN;
UPDATE ONLY foo SET a += 1 RETURN DIFF EXPLAIN FULL;
```

--------------------------------

### SurrealQL search functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-search.md

Examples of search::analyze, search::score, search::highlight, search::linear, and search::rrf in SurrealQL.

```surql
RETURN search::analyze("simple", "The quick brown fox");
SELECT id, search::score(1) AS score FROM blog WHERE title @1@ "animals";
SELECT search::highlight("<b>", "</b>", 1) AS title FROM blog WHERE title @1@ "fox";
RETURN search::linear([0.1, 0.2], [0.1, 0.3]);
RETURN search::rrf([1, 2, 3], [3, 2, 1]);
```

--------------------------------

### Using val and at accessors

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Examples of using 'val()' to get the first element and 'at()' to access specific indices.

```ts
const user = await db.select("user", "alice123").then.val(); // User | undefined
const second = await db.select("user").then.at(1);
const last = await db.select("user").then.at(-1);
```

--------------------------------

### SURQL Method Syntax Examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-methods-functions.md

Demonstrates native method calls on various data types in SURQL, such as arrays, strings, time, and objects.

```surql
[1, 2, 3].len();
[1, 2, 3].map(|$v| $v + 1);
"hello".uppercase();
time::now().year();
{}.keys();
<set>[1, 2, 2].is_empty();
```

--------------------------------

### SURQL LET, SET, and TRANSACTION statements

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-let-set-transaction.md

Example demonstrating variable assignment with LET, data selection, and transaction control flow using BEGIN, COMMIT, and CANCEL in SURQL.

```surql
LET $name = "Tobie";
LET $items = SELECT * FROM item WHERE active = true;
BEGIN;
UPSERT test:name SET name = "Test";
RETURN test:name;
COMMIT;
CANCEL;
```

--------------------------------

### SurrealQL time function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-time.md

SurrealQL examples for the time functions: now, year, format, from_unix, set_month, and year in a SELECT query.

```surql
RETURN time::now();
RETURN time::year(time::now());
RETURN time::format(time::now(), "%Y-%m-%d");
RETURN time::from_unix(1700000000);
RETURN time::set_month(time::now(), 12);
SELECT time::year(time) AS year FROM temperature;
```

--------------------------------

### surqlize TypeScript EXPLAIN examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-explain.md

Shows the corresponding TypeScript query builder usage for the EXPLAIN statement. The first example uses db.explain() on a select query, the second uses db.explain() with an analyze option, the third uses the trailing .explain() method on a select query, and the fourth uses .explain({ full: true }) on an update query.

```ts
db.explain(db.select("student").where((s) => s.marks.all().mark.eq(40)));

db.explain(
  { analyze: true },
  db.select("sale").return({ total: fn.count() }).groupAll(),
);

db.select("person")
  .where((p) => p.name.matches("Jaime"))
  .explain();

db.update("foo")
  .only()
  .set((r) => [r.a.inc(1)])
  .return("DIFF")
  .explain({ full: true });
```

--------------------------------

### return() projection example

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/select-query.md

Example of using return() to project specific fields into a new object structure.

```ts
const q = db
  .select("user")
  .return((u) => ({ fullName: u.name, age: u.age }));
// Renders: (SELECT VALUE { fullName: $this.name, age: $this.age } FROM $tb)
```

--------------------------------

### SurrealQL string function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-string.md

Examples of calling various string functions in SurrealQL, including uppercase, split, distance, similarity, HTML sanitization, email check, and semver operations.

```surql
RETURN string::uppercase("hello");
RETURN "hello world".split(" ");
RETURN string::distance::levenshtein("kitten", "sitting");
RETURN string::similarity::jaro_winkler("martha", "marhta");
RETURN string::html::sanitize("<b>ok</b>");
RETURN string::is_email("root@example.com");
RETURN string::semver::inc::patch("1.2.3");
RETURN string::semver::set::major("1.2.3", 2);
```

--------------------------------

### TypeScript (surqlize) geo functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-geo.md

Examples of using fn.geo.distance, fn.geo.bearing, fn.geo.area, fn.geo.hash.encode, fn.geo.hash.decode, and fn.geo.isValid in TypeScript with surqlize.

```ts
fn.geo.distance(q.point(0, 0), q.point(1, 1));
fn.geo.bearing(q.point(0, 0), q.point(1, 1));
fn.geo.area(q.geometry.polygon([[[0, 0], [1, 0], [1, 1], [0, 0]]]));
fn.geo.hash.encode(q.point(52.1, 5.1));
fn.geo.hash.decode("u173z");
fn.geo.isValid(q.point(0, 0));
```

--------------------------------

### SurrealQL geo functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-geo.md

Examples of using geo::distance, geo::bearing, geo::area, geo::hash::encode, geo::hash::decode, and geo::is_valid in SurrealQL.

```surql
RETURN geo::distance((0, 0), (1, 1));
RETURN geo::bearing((0, 0), (1, 1));
RETURN geo::area({ type: "Polygon", coordinates: [[[0,0],[1,0],[1,1],[0,0]]] });
RETURN geo::hash::encode((52.1, 5.1));
RETURN geo::hash::decode("u173z");
RETURN geo::is_valid((0, 0));
```

--------------------------------

### Basic GET and POST usage

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/api-client.md

Shows how to define an endpoint schema with api() and use the client to perform GET and POST requests. The response types are inferred from the schema.

```typescript
// Basic GET + POST
const usersEndpoint = api("/users", {
  get: { response: t.array(user.schema) },
  post: { request: t.object({ name: t.string() }), response: user.schema },
});

const client = db.api(usersEndpoint);

const list = await client.get("/users");               // ApiResponse<User[]>
const created = await client.post("/users", { name: "Ada" });
```

--------------------------------

### SurQL Operator and Cast Examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-operators-casts.md

Demonstrates various SurQL operators including negation, boolean inversion, regex matching, type casting, and full-text search.

```surql
SELECT VALUE -number FROM thing;
SELECT VALUE !boolean FROM thing;
/foo.*/ = name;
<string> u"00000000-0000-0000-0000-000000000000" = /.*/;
field IN [1, 2, 3];
[5] IN field;
name @@ "Jaime";
title @1@ "animals";
```

--------------------------------

### SURQL Field Projections and Wildcards

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-field-projection.md

Examples of field selection and wildcard expansion using dot notation in SURQL.

```surql
person.name;
person.tags.*;
person.tags.*.*;
house:one.*;
emails.*.address;
tags.*.value;
```

--------------------------------

### Execute ml and mod functions in SURQL

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-ml-module.md

Example of calling nonexistent functions within the ml and mod namespaces using SURQL syntax.

```surql
RETURN ml::nonexistent<1.0.0>({ input: 1.0 });
RETURN mod::nonexistent();
```

--------------------------------

### SurrealQL recursion examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-recursion.md

Shows various recursion syntax in SurrealQL: depth, range, collect, path, shortest, inclusive, and repeat recursion. Covers graph traversal and record-link idioms.

```surql
a:1.{1}.links;
a:1.{0..}.link;
a:1.{..256}.link;
person:alice.{..+collect}->reports_to->person;
person:alice.{2..+collect+inclusive}->reports_to->person;
person:alice.{..+path}->reports_to->person;
person:alice.{..+shortest=person:ceo+inclusive}->reports_to->person;
planet:earth.{2+path}(.contains).name;
SELECT name, @{2}(->knows->person).name AS names_2nds FROM person;
SELECT VALUE @{..}.{ name, knows: ->knows->person.@ } FROM person;
```

--------------------------------

### SURQL General Functions and Custom Definitions

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-general.md

Examples of using built-in functions and defining a custom function in SURQL.

```surql
SELECT count() AS total FROM sale GROUP ALL;
RETURN not(true);
RETURN sleep(1s);
DEFINE FUNCTION fn::shout($text: string) { RETURN string::uppercase($text); };
RETURN fn::shout("hello");
```

--------------------------------

### SurrealQL BLOCK examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-block.md

Shows basic SurrealQL BLOCK syntax: multiple statements, LET bindings, and RETURN. Blocks return the last value unless RETURN exits earlier.

```surql
{ 1; 2; 3 };
```

```surql
{
  LET $x = 5;
  $x + 1
};
```

```surql
{
  LET $a = 5;
  LET $b = 10;
  $a + $b
};
```

```surql
{;};
```

```surql
{
  LET $x = 10;
  RETURN $x + 1
};
```

--------------------------------

### SURQL SELECT Projections

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-select-projection.md

Examples of using OMIT, field selection, nested object projection, FETCH, and subqueries in SURQL.

```surql
SELECT * OMIT password FROM person;
SELECT tags.{id, name} FROM person;
SELECT obj.{ a, c.{ e, f } } FROM person;
SELECT * FROM person FETCH tags.*.name;
SELECT *, (SELECT id, name FROM $this.tags) AS tags FROM person;
SELECT tags.{id, name}, array::len(tags) AS tag_count FROM person ORDER BY tag_count DESC;
```

--------------------------------

### TypeScript string function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-string.md

Examples of calling the same string functions using the surqlize TypeScript API, with nested namespaces for distance, similarity, HTML, email, and semver operations.

```ts
fn.string.uppercase("hello");
q.value("hello world").fn.split(" ");

fn.string.distance.levenshtein("kitten", "sitting");
fn.string.similarity.jaroWinkler("martha", "marhta");
fn.string.html.sanitize("<b>ok</b>");
fn.string.is.email("root@example.com");
fn.string.semver.inc.patch("1.2.3");
fn.string.semver.set.major("1.2.3", 2);
```

--------------------------------

### TypeScript surqlize crypto functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-crypto.md

Examples of crypto functions in the surqlize TypeScript library, using fn.crypto methods. The compare functions accept a parameter for the hash, e.g., q.param("hash").

```ts
fn.crypto.sha256("hello");
fn.crypto.blake3("hello");
fn.crypto.argon2.generate("secret");
fn.crypto.argon2.compare("secret", q.param("hash"));
fn.crypto.bcrypt.generate("secret");
fn.crypto.scrypt.compare("secret", q.param("hash"));
```

--------------------------------

### toString() method

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Renders the query as a SurrealQL string. The example demonstrates generating a SELECT statement from a query builder.

```ts
toString(): string
```

```ts
const db = orm(new Surreal(), user);
console.log(db.select("user").where((u) => u.age.gte(18)).toString());
// (SELECT * FROM $tb WHERE $this.age >= $_v0)
```

--------------------------------

### Using catch for error handling

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Example of using a try-catch block to handle raw SDK errors.

```ts
try {
  const users = await db.select("user");
} catch (e) {
  // e is the raw SDK error from surreal.query(...) — surqlize does not wrap it
}
```

--------------------------------

### fetch() usage example

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/select-query.md

Example of using fetch() to retrieve related records. After execution, posts[0].author is the full user object instead of a RecordId.

```TypeScript
const posts = await db
  .select("post")
  .fetch("author", "out.author")
  .execute();
// posts[0].author is the full user object, not a RecordId
```

--------------------------------

### Basic insert and error handling example

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/insert-query.md

Complete example showing basic inline insert and error handling when values() is misused with object-style insert. The catch block demonstrates the OrmError message.

```typescript
import { Surreal } from "surrealdb";
import { orm, table, t } from "surqlize";

const user = table("user", { name: t.string(), age: t.number(), email: t.string() });
const db = orm(new Surreal(), user);

// Basic inline insert
const users = await db.insert("user", [{ name: "A", age: 1 }, { name: "B", age: 2 }]);

// Error handling: assert-guard misuse with values()
try {
  db.insert("user", { name: "A" }).values(["x"]);
} catch (e) {
  // OrmError: "Cannot use values() with object-style insert"
}
```

--------------------------------

### SurrealQL vector function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-vector.md

Examples of vector operations in SurrealQL: add, dot, normalize, euclidean distance, cosine similarity, and KNN distance in a SELECT query.

```surql
RETURN vector::add([1, 2], [3, 4]);
RETURN vector::dot([1, 2, 3], [4, 5, 6]);
RETURN vector::normalize([3, 4]);
RETURN vector::distance::euclidean([1, 2], [3, 4]);
RETURN vector::similarity::cosine([1, 0], [0, 1]);
SELECT id, vector::distance::knn() AS distance FROM item WHERE embedding <|5|> [0.1, 0.2];
```

--------------------------------

### TypeScript API for LET, SET, and TRANSACTION

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-let-set-transaction.md

Example demonstrating how to perform variable assignment, transaction blocks, and explicit transaction control using the TypeScript SDK.

```ts
db.let("name").eq("Tobie");

db.let("items").eq(
  db.select("item").where((item) => item.active.eq(true)),
);

db.transaction((tx) => [
  tx.upsert(q.rid("test", "name")).set((r) => [r.name.assign("Test")]),
  q.return(q.rid("test", "name")),
]);

db.begin();
db.commit();
db.cancel();
```

--------------------------------

### SurrealQL crypto functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-crypto.md

Examples of crypto functions in SurrealQL, including sha256, blake3, argon2 generate/compare, bcrypt generate, and scrypt compare. Note that argon2::compare and scrypt::compare expect a hash string like '$argon2id$...' or '$scrypt$...'.

```surql
RETURN crypto::sha256("hello");
RETURN crypto::blake3("hello");
RETURN crypto::argon2::generate("secret");
RETURN crypto::argon2::compare("secret", "$argon2id$...");
RETURN crypto::bcrypt::generate("secret");
RETURN crypto::scrypt::compare("secret", "$scrypt$...");
```

--------------------------------

### LiveQuery subscribe() Method

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/live-query.md

Starts the query and subscribes to messages in one step, returning a cleanup function.

```ts
subscribe(handler: (message: LiveMessage<V>) => void): Promise<() => void>
```

```ts
// One-step subscribe (with cleanup)
const stop = await db
  .live("user")
  .where((u) => u.age.gte(18))
  .subscribe(({ action, value }) => {
    console.log(action, value.name);
  });
// later: await stop();  // off() + sub.kill()
```

--------------------------------

### Define and use sequence::nextval in SURQL

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-sequence.md

Demonstrates defining a sequence with a starting value and using nextval to retrieve the next value or assign it to a field during record creation.

```surql
DEFINE SEQUENCE order_id START 100;
RETURN sequence::nextval("order_id");
CREATE order SET id = sequence::nextval("order_id");
```

--------------------------------

### SurrealQL set functions: len, contains, union, map, filter

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-set.md

SurrealQL examples for set functions: len, contains, union, map, and filter. The map and filter examples use closures with the pipe syntax.

```surql
RETURN set::len(<set>[1, 2, 2]);
RETURN set::contains(<set>["a", "b"], "a");
RETURN set::union(<set>[1, 2], <set>[2, 3]);
RETURN <set>[1, 2, 3].map(|$v| $v * 2);
RETURN <set>[1, 2, 3].filter(|$v| $v > 1);
```

--------------------------------

### SurrealQL: DEFINE TABLE, FIELD, INDEX statements

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-define-table-field-index.md

A single SurrealQL block containing examples of DEFINE TABLE, DEFINE FIELD, and DEFINE INDEX statements.

```surql
DEFINE TABLE foo SCHEMAFULL DROP;
DEFINE TABLE foo AS SELECT * FROM bar;
DEFINE TABLE foo TYPE RELATION FROM a|b TO c|d ENFORCED;
DEFINE TABLE foo PERMISSIONS FOR select, delete FULL, FOR create NONE, FOR update WHERE 1 == 1;

DEFINE FIELD f ON t FLEXIBLE TYPE { a: int };
DEFINE FIELD f ON t COMPUTED 2 ASSERT 1 == 1;
DEFINE FIELD f ON t REFERENCE ON DELETE CASCADE;
DEFINE FIELD f ON t REFERENCE ON DELETE THEN 1 - 2;

DEFINE INDEX ft_name ON TABLE person COLUMNS name FULLTEXT ANALYZER simple BM25(1.2, 0.75) HIGHLIGHTS;
DEFINE INDEX idx ON t COUNT;

```

--------------------------------

### RelateQuery usage example

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/mutation-queries.md

Demonstrates how to construct a RELATE query using the builder pattern, including setting data and defining a return clause.

```ts
const q = db
  .relate("authored", new RecordId("user", "alice"), new RecordId("post", "p1"))
  .set({ created: new Date() })
  .return((e) => ({ id: e.id, from: e.in, to: e.out, created: e.created }));
console.log(q.toString());
```

--------------------------------

### SurrealQL type functions example

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-type.md

Shows usage of type::int, type::record, type::is_record, type::of, type::field, and type::fields in SurrealQL.

```surql
RETURN type::int("42");
RETURN type::record("person:one");
RETURN type::is_record(person:one);
RETURN type::of([1, 2, 3]);
SELECT * FROM person FETCH type::field("author");
SELECT type::fields("id", "name") FROM person;
```

--------------------------------

### SurrealQL rand() function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-rand.md

SurrealQL queries demonstrating rand(), rand::bool(), rand::enum(), rand::int(), rand::string(), rand::uuid::v4(), and rand::uuid::v7().

```surql
RETURN rand();
RETURN rand::bool();
RETURN rand::enum("red", "green", "blue");
RETURN rand::int(1, 10);
RETURN rand::string(16);
RETURN rand::uuid::v4();
RETURN rand::uuid::v7(time::now());
```

--------------------------------

### TypeScript: Array range and index expressions

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-indexing-ranges.md

TypeScript examples using the surqlize library to construct SurrealQL queries for array ranges, index expressions, and filtering with WHERE clauses.

```ts
q.array([3, 2, 1]).all().range(0, 1).fn.min();

q.array([[3, 2, 1], [1, 2, 3]])
  .all()
  .range(0, 1)
  .fn.min();

q.return(q.array([1, 2, 3, 4]).index(fn.custom("foo")()));

db.select(q.rid("documentation", "test")).return((d) => ({
  value: d.tags.where((tag) => tag.type.eq("library")).index(0).value,
}));

db.select(q.rid("documentation", "test")).return((d) => ({
  content: d.languages.index(q.param("lang")),
}));

db.select("documentation").return((d) => ({
  content: d.languages.index(d.primarylang),
}));
```

--------------------------------

### SURQL UPDATE and UPSERT syntax

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-update-upsert.md

Examples of UPDATE and UPSERT statements using SURQL, including clauses for index hints, field updates, and return projections.

```surql
UPDATE ONLY foo WITH INDEX foo SET a += 1, b.c -= 1 WHERE foo = bar RETURN DIFF TIMEOUT 1s EXPLAIN FULL;
UPSERT person:tobie SET name = "Tobie";
UPSERT ONLY user:one CONTENT { name: "One" } RETURN AFTER;
UPSERT ONLY foo WITH NOINDEX MERGE { a: 1 } WHERE foo = bar RETURN a AS b.c;
```

--------------------------------

### Session functions in SURQL

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-session.md

Examples of using session functions directly within SURQL queries to retrieve context information or filter data.

```surql
RETURN session::db();
RETURN session::ns();
RETURN session::id();
RETURN session::token();
SELECT * FROM person WHERE tenant = session::db();
```

--------------------------------

### SurrealQL: return parse functions for email and URL parts

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-parse.md

Example usage of parse functions in SurrealQL, covering email host/user and URL domain/path/query extraction.

```surql
RETURN parse::email::host("root@example.com");
RETURN parse::email::user("root@example.com");
RETURN parse::url::domain("https://docs.surrealdb.com/path?q=1");
RETURN parse::url::path("https://docs.surrealdb.com/path?q=1");
RETURN parse::url::query("https://docs.surrealdb.com/path?q=1");
```

--------------------------------

### infer helper

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/types-system.md

Maps a type or workable to its TypeScript type. The example shows using t.infer on a query result to get Array<{ name: string }>.

```typescript
// The `infer` helper — map a type/workable to its TS type
type InferType<T extends AbstractType | Workable> =
	T extends Workable<WorkableContext, infer T> ? T["infer"]
	: T extends AbstractType ? T["infer"] : never;

const query = db.select("user").return((u) => ({ name: u.name }));
type Result = t.infer<typeof query>; // Array<{ name: string }>
```

--------------------------------

### SurrealQL object function calls

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-object.md

SurrealQL examples for the object functions: keys, values, entries, from_entries, extend, and remove. Each line returns the result of the corresponding function call.

```surql
RETURN object::keys({ a: 1, b: 2 });
RETURN object::values({ a: 1, b: 2 });
RETURN object::entries({ a: 1, b: 2 });
RETURN object::from_entries([["a", 1], ["b", 2]]);
RETURN object::extend({ a: 1 }, { b: 2 });
RETURN object::remove({ a: 1, b: 2 }, "a");
```

--------------------------------

### SurrealQL duration functions and arithmetic

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-duration.md

SurrealQL examples for duration conversion functions (days, hours, from_secs, from_millis) and duration arithmetic (ttl += 1h).

```surql
RETURN duration::days(2w);
RETURN duration::hours(1d);
RETURN duration::from_secs(90);
RETURN duration::from_millis(1500);
UPDATE counter SET ttl += 1h;
```

--------------------------------

### Reference Lookup and Graph Traversal in SurrealQL

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-reference-lookup.md

SurrealQL examples for reference lookup and graph traversal. Defines a reference field and shows forward access, reverse lookup, and graph edge comparisons.

```surql
DEFINE FIELD comics ON person TYPE option<array<record<comic_book>>> REFERENCE;
person:one.comics;
person:one.comics.*.*;
<~person;
cat:one<-likes<-person;
cat:one<~person;
country:canada.{..+collect}.next = country:canada.{..+collect}->next->?;
```

--------------------------------

### surqlize TypeScript recursion examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-recursion.md

Shows the surqlize TypeScript API for recursion: depth/range, collect, path, shortest, inclusive, and repeat recursion. Uses q.rid, q.repeat, and db.select.

```ts
q.rid("a", 1).recurse({ depth: 1 }).links;
q.rid("a", 1).recurse({ range: [0, undefined] }).link;
q.rid("a", 1).recurse({ range: [undefined, 256] }).link;

q.rid("person", "alice")
  .recurse({ range: [undefined, undefined], collect: true })
  .out("reports_to")
  .out("person");

q.rid("person", "alice")
  .recurse({ range: [2, undefined], collect: true, inclusive: true })
  .out("reports_to")
  .out("person");

q.rid("person", "alice")
  .recurse({ range: [undefined, undefined], path: true })
  .out("reports_to")
  .out("person");

q.rid("person", "alice")
  .recurse({ shortest: q.rid("person", "ceo"), inclusive: true })
  .out("reports_to")
  .out("person");

q.rid("planet", "earth").recurse({ depth: 2, path: true, via: q.field("contains") }).name;

db.select("person").return((p) => ({
  name: p.name,
  names_2nds: q.repeat({ depth: 2 }, p.out("knows").out("person")).name,
}));
```

--------------------------------

### get()

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/api-client.md

Performs a GET request to the specified endpoint path. The path must be registered for the get method.

```APIDOC
## get()

### Description
Performs a GET request to the specified endpoint path. The path must be registered for the get method.

### Method
GET

### Parameters
- **path** (P) - Required - Must be an endpoint registered for get.

### Returns
Promise<ApiResponse<ResponseType<EndpointsMap<E>, P, "get">>>

### Example
```ts
get<P extends PathsForMethod<EndpointsMap<E>, "get">>(
	path: P,
): Promise<ApiResponse<ResponseType<EndpointsMap<E>, P, "get">>>
```
```

--------------------------------

### get() method signature

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/api-client.md

Signature for the get() method. The path must be an endpoint registered for the get method.

```typescript
get<P extends PathsForMethod<EndpointsMap<E>, "get">>(
	path: P,
): Promise<ApiResponse<ResponseType<EndpointsMap<E>, P, "get">>>
```

--------------------------------

### ArrayType usage examples

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/type-functions.md

Examples demonstrating the use of containsAny() for filtering and at() for field access.

```ts
db.select("user").where((u) => u.tags.containsAny(["a", "b"]));
db.select("post").return((p) => ({ firstTag: p.tags.at(0), tags: p.tags.len() }));
```

--------------------------------

### TypeScript search functions examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-search.md

Examples of fn.search.analyze, fn.search.score, fn.search.highlight, fn.search.linear, and fn.search.rrf in TypeScript.

```ts
fn.search.analyze("simple", "The quick brown fox");

db.select("blog")
  .return((b) => ({ id: b.id, score: fn.search.score(1) }))
  .where((b) => b.title.search(1, "animals"));

fn.search.highlight("<b>", "</b>", 1);
fn.search.linear([0.1, 0.2], [0.1, 0.3]);
fn.search.rrf([1, 2, 3], [3, 2, 1]);
```

--------------------------------

### Usage Example: Error Handling

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/api-client.md

Example showing error handling when a malformed response rejects during parse.

```APIDOC
## Usage Example: Error Handling

### Description
Example showing error handling when a malformed response rejects during parse.

### Example
```ts
// Error handling — a malformed response rejects during parse
try {
  const res = await client.get("/users"); // body does not match User[]
} catch (e) {
  // TypeParseError: `Expected array<...> but found ...` — body would have
  // been `res.body` if the shape had matched; parse errors reject instead.
}
```
```

--------------------------------

### execute()

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Renders the query against a fresh variable store, sends it to the SDK's surreal.query() with bound variables, takes the first statement result, and runs it through parseResult. Errors from the server propagate as-is.

```APIDOC
## execute()

### Description
Renders the query against a fresh variable store, sends it to the SDK's `surreal.query()` with the bound variables, takes the first statement result, and runs it through `parseResult`. Errors from the server propagate as-is (rejected promise, not wrapped).

### Method
execute()

### Signature
async execute()

### Implementation
```ts
async execute() {
	const ctx = displayContext();
	const query = this[__display](ctx);
	const [result] = await this[__ctx].orm.surreal.query<[this["type"]]>(
		query,
		ctx.variables,
	);
	return this.parseResult(result);
}
```
```

--------------------------------

### Batch execution example with type mapping

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/batch-transaction.md

Shows executing a batch of create, update, and select queries, with the typed tuple following the input query order 1:1 via BatchResult<Q>.

```typescript
const [created, updated, all] = await db
  .batch(
    db.create("user").set({ name: "Alice", age: 30 }),
    db.update("user", "bob").set({ age: 31 }),
    db.select("user"),
  )
  .execute();
// created: User[] (CreateQuery result), updated: User[], all: User[]
// typed tuple follows the input query order 1:1 via BatchResult<Q>
```

--------------------------------

### TypeScript fn.time function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-time.md

TypeScript examples using the fn.time API for the same time functions, including a select query with a computed year field.

```ts
fn.time.now();
fn.time.year(fn.time.now());
fn.time.format(fn.time.now(), "%Y-%m-%d");
fn.time.from.unix(1700000000);
fn.time.set.month(fn.time.now(), 12);

db.select("temperature").return((t) => ({
  year: fn.time.year(t.time),
}));
```

--------------------------------

### Basic orm() usage with individual schema arguments

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/orm.md

Demonstrates initializing the ORM with individual table schemas and performing a basic select operation.

```ts
// Basic form — individual schema arguments
import { Surreal } from "surrealdb";
import { orm, table, t } from "surqlize";

const user = table("user", { name: t.string(), age: t.number() });
const db = orm(new Surreal(), user);
const users = await db.select("user");
```

--------------------------------

### SurrealQL: Array range and index expressions

Source: https://github.com/surrealdb/surqlize/blob/main/validation/idiom-indexing-ranges.md

SurrealQL examples showing array range operations with .*[0..1].min(), index expressions with function calls, and filtering array elements with WHERE clauses.

```surql
[3, 2, 1].*[0..1].min();
[[3, 2, 1], [1, 2, 3]].*[0..1].min();
RETURN [1, 2, 3, 4][fn::foo()];
SELECT tags[WHERE type = "library"][0].value FROM documentation:test;
SELECT languages[$lang] AS content FROM documentation:test;
SELECT languages[primarylang] AS content FROM documentation;
```

--------------------------------

### SurrealQL LIVE, KILL, SHOW statements

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-live-kill-show.md

SurrealQL syntax for LIVE SELECT, KILL, and SHOW CHANGES statements. LIVE SELECT supports select-like clauses and DIFF. KILL accepts a UUID literal or a parameter. SHOW CHANGES requires a typed scope (TABLE or DATABASE), SINCE, and an expression-based LIMIT.

```surql
LIVE SELECT * FROM person WHERE active = true;
LIVE SELECT DIFF FROM person;
KILL u"2ba318c4-2267-4319-becd-3c60c237f1e2";
KILL $param;
SHOW CHANGES FOR TABLE foo SINCE 1 LIMIT 1 + 1;
SHOW CHANGES FOR DATABASE SINCE d"0000-01-01T00:00:00Z" LIMIT 1 + 1;
```

--------------------------------

### TypeScript vector function examples

Source: https://github.com/surrealdb/surqlize/blob/main/validation/functions-vector.md

TypeScript examples using fn.vector for add, dot, normalize, euclidean distance, cosine similarity, and KNN distance in a select query.

```ts
fn.vector.add([1, 2], [3, 4]);
fn.vector.dot([1, 2, 3], [4, 5, 6]);
fn.vector.normalize([3, 4]);
fn.vector.distance.euclidean([1, 2], [3, 4]);
fn.vector.similarity.cosine([1, 0], [0, 1]);

db.select("item")
  .return((i) => ({ id: i.id, distance: fn.vector.distance.knn() }))
  .where((i) => i.embedding.knn(5, [0.1, 0.2]));
```

--------------------------------

### prepare() method

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Compiles the query into a BoundQuery for the surrealdb SDK. Unlike execute(), the raw result is not parsed, making it useful for manual transactions.

```ts
prepare(): BoundQuery<[this["type"]]>
```

```ts
const prepared = orm
  .select("user")
  .return((user) => ({ fullName: user.name, email: user.email }))
  .prepare();

const [users] = await db.query(prepared); // users fully typed
```

--------------------------------

### SurrealQL: Embedding statements in LET and RETURN

Source: https://github.com/surrealdb/surqlize/blob/main/validation/statement-actionable-embedding.md

Shows how to embed UPSERT and CREATE statements in LET bindings and RETURN expressions, including accessing fields and using subqueries.

```surql
LET $id = (UPSERT tester:test);
RETURN $id;

LET $id = (UPSERT tester:test).id;
RETURN $id;

LET $id = (SELECT VALUE id FROM (UPSERT tester:test))[0];
RETURN $id;

SELECT *, (SELECT id, name FROM $this.tags) AS tags FROM person;
RETURN string::concat("id=", (CREATE ONLY thing).id);
```

--------------------------------

### Using standalone functions from surqlize

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/functions-standalone.md

Example of using standalone functions like `count`, `math.mean`, `time.now`, `crypto.sha256`, `rand.uuid`, `parse.emailHost`, and `math.pi` in a query. Note that `math.pi` is a constant and requires a context source.

```ts
import { count, math, time, crypto, rand, parse } from "surqlize";

const q = db.select("user").groupAll().return((u) => ({
  total: count(u),
  avgAge: math.mean(u.age),
  now: time.now(u),
  hash: crypto.sha256(u.email),
  id: rand.uuid(u),
  host: parse.emailHost(u.email),
  pi: math.pi(u), // constant — needs a context source
}));
```

--------------------------------

### execute() method

Source: https://github.com/surrealdb/surqlize/blob/main/_autodocs/api-reference/query.md

Renders the query, sends it to the SDK's surreal.query() with bound variables, and parses the result. Server errors propagate as rejected promises.

```ts
async execute() {
	const ctx = displayContext();
	const query = this[__display](ctx);
	const [result] = await this[__ctx].orm.surreal.query<[this["type"]]>(
		query,
		ctx.variables,
	);
	return this.parseResult(result);
}
```
Tokens:
Raw