Escape functions

Escape functions provide safe handling of identifiers and values in SurrealQL queries when you need to construct queries manually.

Tip

Prefer using surql or BoundQuery for automatic parameterization. Use escape functions only when absolutely necessary.

Import:

import { 
    escapeIdent,
    escapeNumber,
    escapeIdPart,
    escapeRangeBound
} from 'surrealdb';

Source: utils/escape.ts

Functions

`escapeIdent(name)`

Escape table names, field names, and other identifiers.

Signature

function escapeIdent(name: string): string

Parameters

Parameter	Type	Description
`name`	`string`	The identifier to escape.

Returns

string - Escaped identifier

Examples

import { escapeIdent } from 'surrealdb';

// Simple identifiers (no escaping needed)
console.log(escapeIdent('users')); // 'users'
console.log(escapeIdent('first_name')); // 'first_name'

// Special characters (wrapped in backticks)
console.log(escapeIdent('user-table')); // '`user-table`'
console.log(escapeIdent('my table')); // '`my table`'
console.log(escapeIdent('user.name')); // '`user.name`'

// Reserved keywords
console.log(escapeIdent('select')); // '`select`'
console.log(escapeIdent('from')); // '`from`'

`escapeNumber(num)`

Escape a number to be used as a valid SurrealQL ident.

Signature

function escapeNumber(num: number | bigint): string

Parameters

Parameter	Type	Description
`num`	`number \| bigint`	The number to escape.

Returns

string - Escaped number representation

Examples

import { escapeNumber } from 'surrealdb';

console.log(escapeNumber(123));    // '123'
console.log(escapeNumber(42n));    // '42'

`escapeIdPart(id)`

Escape a record ID value part. Handles Uuid, string, number, bigint, and object values.

Signature

function escapeIdPart(id: RecordIdValue): string

Parameters

Parameter	Type	Description
`id`	`RecordIdValue`	The record ID value part to escape.

Returns

string - Escaped record ID part

Examples

import { escapeIdPart } from 'surrealdb';

// String IDs
console.log(escapeIdPart('john'));        // 'john' or escaped equivalent

// Numeric IDs
console.log(escapeIdPart(123));           // '123'
console.log(escapeIdPart(42n));           // '42'

// UUID values
console.log(escapeIdPart(new Uuid('...')));

`escapeRangeBound(bound)`

Escape a range bound value for use in SurrealQL range expressions.

Signature

function escapeRangeBound<T>(bound: Bound<T>): string

Parameters

Parameter	Type	Description
`bound`	`Bound<T>`	The range bound to escape.

Returns

string - Escaped range bound representation

Complete Examples

Dynamic Table Names

import { escapeIdent } from 'surrealdb';

async function selectFromTable(tableName: string) {
    // Validate and escape table name
    const safeTable = escapeIdent(tableName);
    
    // Use in query (still prefer Table class)
    const query = `SELECT * FROM ${safeTable}`;
    const [results] = await db.query(query).collect();
    
    return results;
}

await selectFromTable('user-sessions'); // Safe

Dynamic Field Selection

import { escapeIdent } from 'surrealdb';

async function selectFields(table: string, fields: string[]) {
    const escapedFields = fields.map(escapeIdent).join(', ');
    const escapedTable = escapeIdent(table);
    
    const query = `SELECT ${escapedFields} FROM ${escapedTable}`;
    const [results] = await db.query(query).collect();
    
    return results;
}

await selectFields('users', ['first-name', 'last-name', 'email']);

Using surql Instead (Recommended)

// Prefer surql for safe parameterization
const filters = { status: 'active', age: 18 };
const query = surql`
    SELECT * FROM users 
    WHERE status = ${filters.status} 
    AND age = ${filters.age}
`;

When to Use

✅ Use Escape Functions When:

Constructing queries with user-provided table/field names
Working with identifiers that have special characters
Building dynamic schema definitions
Interfacing with external query builders

❌ Prefer Other Solutions:

For values: Use surql or BoundQuery
For tables: Use Table class
For record IDs: Use RecordId class
For conditions: Use expr

Best Practices

1. Prefer Type-Safe Alternatives

// Good: Type-safe
const table = new Table('users');
const users = await db.select(table);

// Avoid: Manual escaping
const escaped = escapeIdent('users');
const users = await db.query(`SELECT * FROM ${escaped}`).collect();

2. Validate Before Escaping

// Good: Validate first
function safeQuery(tableName: string) {
    if (!isValidTable(tableName)) {
        throw new Error('Invalid table name');
    }
    
    const escaped = escapeIdent(tableName);
    return `SELECT * FROM ${escaped}`;
}

// Avoid: Blind escaping
function unsafeQuery(tableName: string) {
    return `SELECT * FROM ${escapeIdent(tableName)}`;
}

3. Use surql for Complex Queries

// Good: Automatic parameterization
const query = surql`SELECT * FROM users WHERE name = ${name}`;

// Avoid: Manual string construction
const query = `SELECT * FROM users WHERE name = '${name}'`;

Security Considerations

Warning

Escaping functions are NOT a complete defense against SQL injection. Always prefer parameterized queries using surql or BoundQuery.

// Secure: Parameterized
const query = surql`SELECT * FROM users WHERE name = ${userInput}`;

// Insecure: No escaping
const query = `SELECT * FROM users WHERE name = '${userInput}'`;

Tip

Functions

escapeIdent(name)

Parameters

Returns

Examples

escapeNumber(num)

Parameters

Returns

Examples

escapeIdPart(id)

Parameters

Returns

Examples

escapeRangeBound(bound)

Parameters

Returns

Complete Examples

Dynamic Table Names

Dynamic Field Selection

Using surql Instead (Recommended)

When to Use

✅ Use Escape Functions When:

❌ Prefer Other Solutions:

Best Practices

1. Prefer Type-Safe Alternatives

2. Validate Before Escaping

3. Use surql for Complex Queries

Security Considerations

Warning

See Also

`escapeIdent(name)`

`escapeNumber(num)`

`escapeIdPart(id)`

`escapeRangeBound(bound)`