Bound queries

When composing dynamic queries, it is important to avoid string interpolation to prevent injection vulnerabilities. The JavaScript SDK provides bound queries and the surql template tag to safely parameterize values, along with an expressions API for composing dynamic conditions.

API References

Using the surql template tag

The surql tagged template literal is the recommended way to compose parameterized queries. Interpolated values are automatically bound as parameters, preventing injection and preserving type safety.

import { surql } from 'surrealdb';

const name = 'John';
const minAge = 18;

const query = surql`SELECT * FROM users WHERE name = ${name} AND age > ${minAge}`;
const [users] = await db.query(query);

The surrealql export is an alias for surql if you prefer the longer name.

import { surrealql } from 'surrealdb';

const query = surrealql`CREATE person CONTENT ${{ name: 'Tobie' }}`;

Note

The SurrealQL VSCode extension provides syntax highlighting for surql template literals.

Building queries with BoundQuery

The BoundQuery class provides manual control over query composition. You can construct a query with initial bindings, and incrementally append fragments with additional parameters.

import { BoundQuery } from 'surrealdb';

const query = new BoundQuery(
    'SELECT * FROM users WHERE status = $status',
    { status: 'active' },
);

await db.query(query);

Appending query fragments

Use the .append() method to conditionally add SurrealQL fragments. The method uses the same tagged template literal syntax as surql, so interpolated values are automatically bound.

const query = new BoundQuery('SELECT * FROM person');
const filterName = 'Alice';

if (filterName) {
    query.append(surql` WHERE name = ${filterName}`);
}

const [results] = await db.query(query);

Composing expressions

The expressions API provides functions for building dynamic conditions in a type-safe way. Expressions integrate with both surql and query builder methods like .where().

const checkActive = true;

await db.query(surql`SELECT * FROM users WHERE ${eq('active', checkActive)}`);

Learn more

• surql API reference for template tag details
• BoundQuery API reference for manual query building
• expr API reference for the full expressions API
• Executing queries for running queries against the database