API Reference

This section provides comprehensive technical documentation for all classes, methods, types, and utilities in the SurrealDB JavaScript SDK. The API reference is organized by functionality to help you quickly find what you need.

Core Classes

The core classes provide the foundation for connecting to SurrealDB and managing database sessions.

• Surreal - Main entry point for connecting to SurrealDB instances
• SurrealSession - Scoped session context with authentication and configuration
• SurrealQueryable - Base class providing query execution methods
• SurrealTransaction - Transaction management for atomic operations
• SurrealApi - User-defined API endpoint methods

Query Builders

Query builder classes are returned by query methods and provide chainable configuration options before execution. View all query builders →

Core Queries

• Query - Raw SurrealQL query execution
• SelectPromise - SELECT queries with filtering and pagination
• CreatePromise - CREATE operations for new records
• InsertPromise - Bulk INSERT operations
• UpdatePromise - UPDATE operations with merge/replace
• UpsertPromise - UPSERT operations (insert or replace)
• DeletePromise - DELETE operations

Graph & Real-time

• RelatePromise - RELATE operations for graph relationships
• LivePromise - Live query subscriptions

Functions & APIs

• RunPromise - Execute SurrealDB functions and SurrealML models
• ApiPromise - User-defined API endpoint calls

Data Types

Custom data type classes for SurrealDB-specific types with type safety and utility methods. View type mapping →

Core Types

• RecordId - Type-safe record identifiers
• DateTime - Datetime values with nanosecond precision
• Duration - Time duration values
• Decimal - Arbitrary precision decimal numbers
• Uuid - UUID generation and parsing
• Table - Type-safe table references

Advanced Types

• Geometry - Geometric types (Point, Line, Polygon, etc.)
• Range - Generic range values
• Future - Deferred computation (deprecated)

Utilities

Utility functions and classes for building queries and working with SurrealDB data. View all utilities →

• expr - Type-safe expression builder with operators
• surql - Tagged template for parameterized queries
• BoundQuery - Parameterized query class
• equals - Deep equality comparison
• Escape Functions - Identifier and value escaping

Error Classes

Error classes for handling different types of failures in the SDK.

• Error Reference - Complete list of error classes with descriptions

TypeScript Types

TypeScript type definitions and interfaces used throughout the SDK.

• TypeScript Types - Connection types, options, events, and all type definitions

Quick Navigation

By Use Case

Getting Started:

1. Create a Surreal instance
2. Call connect() to establish connection
3. Use query methods like select(), create(), etc.

Authentication:

• signup() - Sign up new users
• signin() - Sign in with credentials
• authenticate() - Authenticate with tokens

Querying Data:

• query() - Raw SurrealQL
• select() - Select records (SelectPromise)
• create() - Create records (CreatePromise)
• insert() - Insert records
• update() - Update records
• delete() - Delete records

Real-time Features:

• live() - Subscribe to live queries
• Event subscriptions - Listen to connection events

Transactions:

• beginTransaction() - Start transactions
• commit() - Commit changes
• cancel() - Roll back changes

Related Documentation

• Installation - Getting started
• Connection Engines - Engine-specific documentation
• Framework Integration - Framework-specific guides
• Data Types - Working with SurrealDB data types

Version Information

This API reference is for the JavaScript SDK version 2.x. For version 1.x documentation, see the v1 documentation.

Contributing

Found an error or want to improve the documentation? Submit an issue or pull request in the docs.surrealdb.com repository.