Query

One of the most important types in Surrealize is the Query type. You can get a Query object using the query builder, the repository API or the surql function.

Internally, a Query object contains a SurrealQL string with optional bindings.

Using SurrealQL strings

The simplest but not the most convenient way to create a Query object is by using a raw SurrealQL string.

To create a query from a raw SurrealQL string you can use the surql function and pass it as an template string.

import { surql } from "@surrealize/core";

const query = surql`SELECT * FROM users`;

This way you can also pass variables to the query by using the powerful template syntax, which are also SQL injection safe.

import { Table, surql } from "@surrealize/core";

const table = new Table("user");
const name = "John";

const query = surql`SELECT * FROM ${table} WHERE name = ${name}`;

Using the Query Builder

A way more convenient way to create a Query is by using the query builder.

import { q } from "@surrealize/core";

const query = q.select().from("users").toQuery();

More information about the Query Builder can be found here.

Using the Repository API

Another way to create a Query object is by using the repository API. This is especially useful when doing CRUD operations.

import { Repository } from "@surrealize/core";

const repository = new Repository();

const query = repository.findBy({ name: "John" });

More information about the Repository API can be found here.

Executing a query

A Query that got never executed is not very useful. To execute a query against the database and get the corresponding result, you can use multiple ways.

Using a Surrealize instance

Executing a single query can be done like this:

import { Surrealize } from "@surrealize/core";

const surrealize = new Surrealize();

// execute a single query
const result = await surrealize.execute(query);

Also you can execute multiple queries at once:

import { Surrealize } from "@surrealize/core";

const surrealize = new Surrealize();

// execute the queries in one go
const [result1, result2] = await surrealize.executeAll([query1, query2]);

info

Using executeAll will NOT execute the queries in a transaction.

To execute multiple queries in a transaction, use the executeTransaction method.

import { Surrealize } from "@surrealize/core";

const surrealize = new Surrealize();

// execute the queries in a transaction
const [result1, result2] = await surrealize.executeTransaction([
	query1,
	query2,
]);

Using the .execute() method

Every Query comes with an execute method which is internally calling the Surrealize instance but is easier to access.

import { q } from "@surrealize/core";

const query = q.select().from("users").toQuery();

// execute the query
const result = await query.execute();

info

The above example is only working when a default Surrealize instance configured (see Basic Usage).

Alternatively you can pass a Surrealize instance to the execute method.

import { Surrealize, q } from "@surrealize/core";

const surrealize = new Surrealize();

const query = q.select().from("users").toQuery();

// execute the query
const result = await query.execute({ connection: surrealize });