SurrealDB

https://surrealdb.com/docs
Admin
SurrealDB is a multi-model database built in Rust that unifies document, graph, time-series,...
Tokens:1,214,989
Snippets:14,169
Trust Score:10
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies and Start Web App

Source: https://surrealdb.com/docs/explore/tutorials/tutorials/build-a-real-time-presence-app

Installs project dependencies using Bun and starts the development server.

```bash
bun install
bun start
```

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

### Start database with CLI flags

Source: https://surrealdb.com/docs/reference/cli/surrealdb-cli/environment-variables

Example of starting the database using standard command-line arguments.

```bash
surreal start --user root --pass secret --allow-net --deny-funcs "crypto::md5, http::post, http::delete"
```

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

### Setup Search Environment

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/search

Initial setup for search examples, including creating a record, defining an analyzer, and creating a fulltext index.

```surql
CREATE book:1 SET title = "Rust Web Programming";
DEFINE ANALYZER book_analyzer TOKENIZERS blank, class, camel, punct FILTERS snowball(english);
DEFINE INDEX book_title ON book FIELDS title FULLTEXT ANALYZER book_analyzer BM25;
```

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

### Recursive query examples and setup

Source: https://surrealdb.com/docs/reference/query-language/language-primitives/idioms

Provides setup data and various recursive query patterns including depth constraints and complex tree structures.

```surql
/**[test]

[[test.results]]
value = "[{ friends: [person:jaime, person:micha], id: person:tobie, name: 'Tobie' }, { friends: [person:mary], id: person:jaime, name: 'Jaime' }, { friends: [person:john], id: person:micha, name: 'Micha' }, { id: person:john, name: 'John' }, { id: person:mary, name: 'Mary' }, { id: person:tim, name: 'Tim' }]"

[[test.results]]
value = "[{ id: knows:1, in: person:tobie, out: person:jaime }, { id: knows:2, in: person:tobie, out: person:micha }, { id: knows:3, in: person:micha, out: person:john }, { id: knows:4, in: person:jaime, out: person:mary }, { id: knows:5, in: person:mary, out: person:tim }]"

[[test.results]]
value = "['Tim']"

[[test.results]]
value = "['Tim']"

[[test.results]]
value = "['Tim']"

[[test.results]]
value = "['Tim']"

[[test.results]]
value = "{ connections: [{ connections: [{ connections: [{ connections: [], id: person:tim, name: 'Tim' }], id: person:mary, name: 'Mary' }], id: person:jaime, name: 'Jaime' }, { connections: [{ connections: [], id: person:john, name: 'John' }], id: person:micha, name: 'Micha' }], id: person:tobie, name: 'Tobie' }"

[[test.results]]
value = "[{ names_2nds: ['Tim'] }, { names_2nds: [] }, { names_2nds: ['Tim'] }, { names_2nds: ['John'] }, { names_2nds: [] }, { names_2nds: ['Tim'] }]]"

[[test.results]]
value = ""

*/

INSERT INTO person [
	{ id: person:tobie, name: 'Tobie', friends: [person:jaime, person:micha] },
	{ id: person:jaime, name: 'Jaime', friends: [person:mary] },
	{ id: person:micha, name: 'Micha', friends: [person:john] },
	{ id: person:john, name: 'John' },
	{ id: person:mary, name: 'Mary' },
	{ id: person:tim, name: 'Tim' },
];

INSERT RELATION INTO knows [
	{ id: knows:1, in: person:tobie, out: person:jaime },
	{ id: knows:2, in: person:tobie, out: person:micha },
	{ id: knows:3, in: person:micha, out: person:john },
	{ id: knows:4, in: person:jaime, out: person:mary },
	{ id: knows:5, in: person:mary, out: person:tim },
];

-- Any depth
person:tobie.{..}(->knows->person).name;

-- Minimum 2, maximum 5 iterations of recursion (or either)
person:tobie.{2..6}(->knows->person).name;
person:tobie.{2..}(->knows->person).name;
person:tobie.{..6}(->knows->person).name;

-- Generate complex recursive tree structures:
-- Fetches connections up to 3 levels deep, 
-- collecting their name, id, and connections along the way
-- 3 levels, because the first iteration is used to collect
-- the details for person:tobie
person:tobie.{..4}.{ id, name, connections: ->knows->person.@ };

-- @ is a shortcut to the current document, and acts as a shorthand to start an idiom path.
-- The "." can optionally be omitted
SELECT @{1..4}(->knows->person).name AS names_2nds FROM person;

-- Recursive idioms work with any idiom parts, not limited to graphs
-- Here, we recursively fetch friends and then collect their names
person:tobie.{1..5}(.friend).name;
```

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

### Start SurrealDB with 3.x Datastore Configurations

Source: https://surrealdb.com/docs/reference/cli/surrealdb-cli/commands/start

Examples of starting a SurrealDB instance using various datastore protocols and parameters.

```bash
surreal start --user root --pass secret "surrealkv://path/to/db?versioned=true&sync=every&retention=30d"
surreal start --user root --pass secret "mem://tmp/data?versioned=true&aol=sync&snapshot=60s&sync=5s"
surreal start --user root --pass secret "mem://?versioned=true"
```

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

### Install OpenClaw Spectron Plugin

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/openclaw

Commands to install the plugin, initialize setup, and restart the gateway.

```bash
openclaw plugins install @surrealdb/spectron-openclaw
openclaw spectron setup
openclaw gateway restart
```

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

### SignIn Examples

Source: https://surrealdb.com/docs/reference/golang/api/core/db

Examples for root and record-level authentication.

```go
token, err := db.SignIn(ctx, surrealdb.Auth{
    Username: "root",
    Password: "root",
})
```

```go
token, err := db.SignIn(ctx, map[string]any{
    "NS": "my_ns", "DB": "my_db", "AC": "user_access",
    "user": "tobie", "pass": "s3cret",
})
```

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

### Install and Start TiKV Playground

Source: https://surrealdb.com/docs/running/multi-node

Installs TiUP and starts a local TiKV playground instance for testing distributed storage connectivity.

```bash
curl -sSf https://tiup-mirrors.pingcap.com/install.sh | sh
tiup playground --tag surrealdb --mode tikv-slim --pd 1 --kv 1
```

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

### Example startup output

Source: https://surrealdb.com/docs/build/deployment/self-hosted/docker

Shows the expected terminal output when starting the SurrealDB container.

```bash
docker run --rm --pull always -p 80:8000 -v /local-dir:/container-dir surrealdb/surrealdb:latest start --user root --pass secret rocksdb:/container-dir/mydatabase.db

2025-08-30T15:06:34.788739Z  INFO surreal::dbs: ✅🔒 Authentication is enabled 🔒✅
2025-08-30T15:06:34.788821Z  INFO surrealdb::kvs::ds: Starting kvs store in rocksdb:/container-dir/mydatabase.db
2025-08-30T15:06:34.788859Z  INFO surrealdb::kvs::ds: Started kvs store in rocksdb:/container-dir/mydatabase.db
2025-08-30T15:06:34.789222Z  INFO surrealdb::kvs::ds: Initial credentials were provided and no existing root-level users were found: create the initial user 'root'.
2025-08-30T15:06:35.205123Z  INFO surrealdb::node: Started node agent
2025-08-30T15:06:35.205827Z  INFO surrealdb::net: Started web server on 0.0.0.0:8080
```

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

### Start SurrealDB with 2.x Storage Engines

Source: https://surrealdb.com/docs/reference/cli/surrealdb-cli/commands/start

Examples of starting a SurrealDB instance using RocksDB and SurrealKV storage engines.

```bash
surreal start -u root -p secret rocksdb://mydb
```

```bash
surreal start -u root -p secret surrealkv://mydb
```

```bash
surreal start -u root -p secret surrealkv+versioned://mydb
```

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

### SignInWithRefresh Examples

Source: https://surrealdb.com/docs/reference/golang/api/core/db

Examples for initial sign-in and subsequent token refresh.

```go
tokens, err := db.SignInWithRefresh(ctx, map[string]any{
    "NS": "my_ns", "DB": "my_db", "AC": "user_access",
    "user": "tobie", "pass": "s3cret",
})
```

```go
newTokens, err := db.SignInWithRefresh(ctx, map[string]any{
    "NS": "my_ns", "DB": "my_db", "AC": "user_access",
    "refresh": tokens.Refresh,
})
```

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

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/voice/livekit

Install the required LiveKit plugins and the Spectron client.

```bash
pip install "livekit-agents[openai,silero]" surrealdb
```

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

### Begin Transaction Examples

Source: https://surrealdb.com/docs/reference/python/api/core/surreal

Examples showing synchronous, asynchronous, and session-specific transaction initiation.

```python
txn_id = db.begin()
```

```python
txn_id = await db.begin()
```

```python
session_id = db.attach()
txn_id = db.begin(session_id)
```

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

### Install Dependencies and Run SurrealDB

Source: https://surrealdb.com/docs/build/integrations/ai-frameworks/crewai

Install the necessary Python packages and start a local SurrealDB instance using Docker.

```bash
# CrewAI, SurrealDB Python SDK, and an embedder (OpenAI here; swap if you like)
pip install "crewai[tools]" surrealdb openai

# (optional) run SurrealDB locally – single binary, no deps
docker run --pull always -p 8000:8000 surrealdb/surrealdb:latest \
       start --user root --pass secret file:/data/db
```

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

### BeginTransaction Usage Example

Source: https://surrealdb.com/docs/reference/dotnet/core/transactions

Demonstrates starting a transaction, performing multiple create operations, and committing the changes.

```csharp
// Begin a new transaction on the current session
await using var txn = await db.BeginTransaction();

// Execute queries within the transaction
await txn.Create("person", new { Name = "John" });
await txn.Create("person", new { Name = "Jane" });

// Commit all changes atomically
await txn.Commit();
```

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

### Install SurrealKit from source

Source: https://surrealdb.com/docs/manage/schema-migration

Standard installation method using Cargo.

```bash
cargo install surrealkit
```

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

### USE Statement Examples

Source: https://surrealdb.com/docs/reference/query-language/statements/use

Examples of switching namespaces, databases, or both.

```surql
/**[test]

[[test.results]]
value = "{ database: 'test', namespace: 'test' }"

*/

USE NS test; -- Switch to the 'main' Namespace
```

```surql
/**[test]

[[test.results]]
value = "{ database: 'test', namespace: 'test' }"

*/

USE DB test; -- Switch to the 'main' Database
```

```surql
/**[test]

[[test.results]]
value = "{ database: 'test', namespace: 'test' }"

*/

USE NS test DB test; -- Switch to the 'main' Namespace and 'main' Database
```

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

### Install and Initialize SurrealKit

Source: https://surrealdb.com/docs/manage/schema-migration/getting-started/existing-databases

Install the SurrealKit CLI tool and initialize the project directory.

```bash
cargo binstall surrealkit
surrealkit init
```

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

### Install SQON package

Source: https://surrealdb.com/docs/reference/javascript/concepts/codecs

Install the standalone serialization library using bun.

```sh
bun add @surrealdb/sqon
```

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

### Install Surqlize via Composer

Source: https://surrealdb.com/docs/reference/php/libraries/surqlize/installation

Install the package using the Composer command-line tool.

```bash
composer require surrealdb/surqlize
```

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

### math::product Usage Example

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/math

Example usage of math::product in a RETURN statement.

```surql
/**[test]

[[test.results]]
value = "5619119.004884841f"

*/

RETURN math::product([ 26.164, 13.746189, 23, 16.4, 41.42 ]);
-- 5619119.004884841f
```

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

### Install and Import Spectron SDK

Source: https://surrealdb.com/docs/spectron/integrations/sdks/go

Commands to install the package and import it into your Go project.

```bash
go get github.com/surrealdb/surrealdb.go/spectron
```

```go
import "github.com/surrealdb/surrealdb.go/spectron"
```

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

### Get the start bound of a range

Source: https://surrealdb.com/docs/reference/java/api/values/range

Retrieves the start bound of the range as an Optional Value.

```java
value.getRangeStart()
```

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

### Clone and install the SDK

Source: https://surrealdb.com/docs/reference/mojo/installation

Use git and pixi to set up the SurrealDB Mojo environment.

```bash
git clone https://github.com/surrealdb/surrealdb.mojo
cd surrealdb.mojo
pixi install
```

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

### Start a transaction with db.Begin

Source: https://surrealdb.com/docs/reference/golang/api/core/transaction

Syntax for initiating a transaction on the default session.

```go
tx, err := db.Begin(ctx)
```

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

### Install dependencies

Source: https://surrealdb.com/docs/build/integrations/ai-frameworks/langchain

Install the necessary Python packages using pip, poetry, or uv.

```bash
# -- Using pip
pip install -U langchain-surrealdb langchain_ollama surrealdb
# -- Using poetry
poetry add langchain-surrealdb langchain_ollama surrealdb
# -- Using uv
uv add --upgrade langchain-surrealdb langchain_ollama surrealdb
```

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

### http::get Usage Examples

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/http

Examples of using http::get to perform GET requests with and without custom headers.

```surql
RETURN http::get('https://surrealdb.com');

-- The HTML code is returned
```

```surql
RETURN http::get('https://surrealdb.com', {
	'x-my-header': 'some unique string'
});

-- The HTML code is returned
```

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

### Create Record Example

Source: https://surrealdb.com/docs/reference/php/v2/api/query-builders

Example of creating a new record with specific content.

```php
$person = $db->create(new RecordId('person', 'tobie'))
    ->content(['name' => 'Tobie'])
    ->execute();
```

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

### Install Dagster and SurrealDB dependencies

Source: https://surrealdb.com/docs/build/integrations/ai-frameworks/dagster

Install the required Python packages and optionally start a local SurrealDB instance using Docker.

```bash
pip install dagster surrealdb openai  # or swap out OpenAI for any embedder
# optional – launch a local SurrealDB daemon
docker run -p 8000:8000 surrealdb/surrealdb:latest \
       start --user root --pass secret file:/data/db
```

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

### Server Startup Output

Source: https://surrealdb.com/docs/running/file-backed

Example command and the resulting terminal output upon successful server initialization.

```text
surreal start --user root --pass secret --bind 0.0.0.0:8080 rocksdb://mydatabase.db
```

```text
2025-08-30T15:06:34.788739Z  INFO surreal::dbs: ✅🔒 Authentication is enabled 🔒✅
2025-08-30T15:06:34.788821Z  INFO surrealdb::kvs::ds: Starting kvs store in file:mydatabase.db
2025-08-30T15:06:34.788859Z  INFO surrealdb::kvs::ds: Started kvs store in file:mydatabase.db
2025-08-30T15:06:34.789222Z  INFO surrealdb::kvs::ds: Initial credentials were provided and no existing root-level users were found: create the initial user 'root'.
2025-08-30T15:06:35.205123Z  INFO surrealdb::node: Started node agent
2025-08-30T15:06:35.205827Z  INFO surrealdb::net: Started web server on 0.0.0.0:8080
```

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

### Signup Example Usage

Source: https://surrealdb.com/docs/reference/swift/methods/signup

Demonstrates signing up a user with specific namespace, database, access, and variable credentials.

```swift
let tokens = try await client.signup(.accessRecord(
    namespace: "myapp",
    database: "mydb",
    access: "account",
        variables: ["email": .string("new@example.com"),
        "pass": .string("secret")]
))
```

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

### signin Example Usage

Source: https://surrealdb.com/docs/reference/swift/methods/signin

Examples demonstrating authentication for root users, database users, and record access using variables.

```swift
// Root user
let tokens = try await client.signin(.root(username: "root",
    password: "root"))

// Database user
let tokens = try await client.signin(.database(
    namespace: "myapp",
    database: "mydb",
    username: "db_user",
    password: "secret"
))

// Record access with variables
let tokens = try await client.signin(.accessVariables(
    namespace: "myapp",
    database: "mydb",
    access: "account",
        variables: ["email": .string("user@example.com"),
        "pass": .string("secret")]
))
```

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

### Generate sequential arrays

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/array

Examples of generating arrays with specific lengths and starting points.

```surql
array::sequence(5);
-- [0, 1, 2, 3, 4]
```

```surql
array::sequence(-5, 6);
-- [-5, -4, -3, -2, -1, 0]
```

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

### Run Method Usage Examples

Source: https://surrealdb.com/docs/reference/dotnet/methods/run

Examples demonstrating how to execute built-in SurrealQL functions with and without arguments.

```csharp
DateTime now = await db.Run<DateTime>("time::now");

string result = await db.Run<string>("string::repeat", ["test", 3]);
```

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

### Get Array of Values

Source: https://surrealdb.com/docs/reference/javascript/api/queries/select-promise

Example of unwrapping a specific field value from the record structure.

```ts
const names = await db.select(new Table('users'))
    .value('name');
// Returns: ['John', 'Jane', 'Bob']

// Instead of: [{ name: 'John' }, { name: 'Jane' }, ...]
```

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

### Select Namespace and Authenticate

Source: https://surrealdb.com/docs/languages/golang

Configure the database context and provide credentials to authenticate the client session.

```go
if err := db.Use(ctx, "company_name", "project_name"); err != nil {
	log.Fatal(err)
}

_, err = db.SignIn(ctx, surrealdb.Auth{
	Username: "root",
	Password: "root",
})
if err != nil {
	log.Fatal(err)
}
```

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

### Half-open range 1 to 10

Source: https://surrealdb.com/docs/reference/python/api/values/range

Example of creating a range where the start is inclusive and the end is exclusive.

```python
from surrealdb.data.types.range import BoundIncluded, BoundExcluded

r = Range(
    begin=BoundIncluded(1),
    end=BoundExcluded(10),
)
```

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

### Quickstart with SpectronToolset

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/google-adk

Initialize a SpectronToolset and use it within an ADK agent runner.

```python
import asyncio
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from spectron_google_adk import SpectronToolset

async def main():
    toolset = SpectronToolset(
        context="acme-prod",
        endpoint="https://api.spectron.example",
        api_key="sk-spec-...",
    )

    agent = Agent(
        model="gemini-2.5-flash",
        name="assistant",
        description="An assistant with persistent memory.",
        instruction="Store durable facts with remember and look things up with recall.",
        tools=[toolset],
    )

    runner = InMemoryRunner(agent=agent)
    try:
        await runner.run_debug("Remember: Acme Corp, healthcare, 1.2M dollar contract.")
        events = await runner.run_debug("What healthcare contracts do we have?")
        for event in events:
            if event.is_final_response() and event.content:
                for part in event.content.parts:
                    if part.text:
                        print(part.text)
    finally:
        await runner.close()
        await toolset.close()

asyncio.run(main())
```

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

### Define API Endpoint

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/api

Example setup for a custom API endpoint using the DEFINE API statement.

```surql
/**[test]

[[test.results]]
value = "NONE"

*/

DEFINE API "/test"
    FOR get 
        MIDDLEWARE
            api::timeout(1s)
        THEN {
            {
                status: 404,
                body: $request.body,
                headers: { the_time_is_now: <string>time::now() }
            };
        };
```

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

### Slice arrays with various parameters

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/array

Examples of slicing arrays using start positions, lengths, and negative indices.

```surql
/**[test]

[[test.results]]
value = "[2, 3]"

*/

RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, 3);

-- [2, 3]
```

```surql
/**[test]

[[test.results]]
value = "[2, 3, 4]"

*/

RETURN array::slice([ 1, 2, 3, 4, 5 ], 1, -1);

[ 2, 3, 4 ]
```

```surql
/**[test]

[[test.results]]
value = "[3, 4, 5]"

*/

RETURN array::slice([ 1, 2, 3, 4, 5 ], 2);

-- [ 3, 4, 5 ]
```

```surql
/**[test]

[[test.results]]
value = "[4, 5]"

*/

RETURN array::slice([ 1, 2, 3, 4, 5 ], -2);

-- [ 4, 5 ]
```

```surql
RETURN array::slice([ 1, 2, 3, 4, 5 ], -3, 2);

[ 3, 4 ]
```

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

### Start a transaction with session.Begin

Source: https://surrealdb.com/docs/reference/golang/api/core/transaction

Syntax for initiating a transaction within a specific session.

```go
tx, err := session.Begin(ctx)
```

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

### Start SurrealMX with versioning and snapshots

Source: https://surrealdb.com/docs/running/in-memory

Configures an in-memory server with versioning enabled and snapshots taken every 60 seconds.

```bash
surreal start --user root --pass secret "mem://tmp/data?versioned=true&snapshot=60s"
```

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

### Perform operations on a file pointer

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/type

Example of using put and get operations on a file pointer after defining a bucket.

```surql
/**[test]

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "b"536F6D65206461746120696E73696465""

*/

DEFINE BUCKET my_bucket BACKEND "memory";

type::file("my_bucket", "file_name").put("Some data inside");
type::file("my_bucket", "file_name").get();
```

```surql
b"536F6D65206461746120696E73696465"
```

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

### Example GET Request via cURL

Source: https://surrealdb.com/docs/reference/rest-api/http-protocol

A sample cURL command demonstrating how to authenticate and query the /key/:table endpoint.

```bash
curl -X GET -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person
```

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

### Start the rollout

Source: https://surrealdb.com/docs/manage/schema-migration/rollouts

Applies the non-destructive start-phase steps of the migration.

```bash
surrealkit rollout start 20260302153045__add_customer_indexes --user root \
  --pass secret
```

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

### Configure local development metrics

Source: https://surrealdb.com/docs/manage/observability/configuration

Commands to start SurrealDB and scrape metrics locally, including authenticated and anonymous access examples.

```bash
surreal start --user root --pass secret
# Anonymous: only the public allowlist
curl http://127.0.0.1:8000/metrics
# Authenticated: the full surface
curl -u root:secret http://127.0.0.1:8000/metrics
```

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

### GET Record via cURL

Source: https://surrealdb.com/docs/reference/rest-api/http-protocol

Example request to retrieve a record from the 'person' table with ID '1' using basic authentication and required headers.

```bash
curl -X GET -u "root:secret" -H "Surreal-NS: main" -H "Surreal-DB: main" -H "Accept: application/json" http://localhost:8000/key/person/1
```

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

### Monitor SurrealDB Connection Pool Statistics

Source: https://surrealdb.com/docs/build/integrations/data-management/n8n

Example output from the System > Get Pool Statistics operation used to monitor performance and health of the connection pool.

```json
{
  "poolStatistics": {
    "totalConnections": 5,
    "activeConnections": 2,
    "idleConnections": 3,
    "waitingRequests": 0,
    "totalRequests": 150,
    "failedRequests": 2,
    "averageResponseTime": 45,
    "successRate": 99
  },
  "performance": {
    "averageResponseTimeMs": 45,
    "requestsPerSecond": 2,
    "errorRate": 1
  },
  "poolHealth": {
    "utilizationRate": 40,
    "availableConnections": 3,
    "waitingRequests": 0
  }
}
```

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

### CLI Record Creation Examples

Source: https://surrealdb.com/docs/reference/rust/frameworks/actix

Examples of creating records as a root user versus a restricted record user.

```bash
main/main> CREATE person SET name = 'Aeon';
-- Query 1
[
	{
		id: person:hdl0unwts4atic65nh7l,
		name: 'Aeon'
	}
]
```

```bash
main/main> CREATE person SET name = 'Aeon';
-- Query 1
[
	{
		created_by: user:qx2apv5oc8mh03wtah0q,
		id: person:8syfiq2ovztn2tbr8mhb,
		name: 'Aeon'
	}
]
```

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

### Performing Linear Fusion with search::linear

Source: https://surrealdb.com/docs/reference/query-language/functions/database-functions/search

Example demonstrating data setup, index creation, and the fusion of vector and full-text search results using both minmax and zscore normalization.

```surql
/**[test]

[[test.results]]
value = "[{ embedding: [0.1f, 0.2f, 0.3f], id: test:1, text: 'Graph databases are great.' }]"

[[test.results]]
value = "[{ embedding: [0.05f, 0.1f, 0f], id: test:2, text: 'Relational databases store tables.' }]"

[[test.results]]
value = "[{ embedding: [0.2f, 0.1f, 0.25f], id: test:3, text: 'This document mentions graphs and networks.' }]"

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "NONE"

[[test.results]]
value = "[{ id: test:1, linear_score: 2f, score: 0.5366538763046265f }, { id: test:3, linear_score: 0f }]"

[[test.results]]
value = "[{ id: test:1, linear_score: 2f, score: 0.5366538763046265f }, { id: test:3, linear_score: -2f }]"

*/

-- Sample data --
CREATE test:1 SET text = "Graph databases are great.", embedding = [0.10, 0.20, 0.30];
CREATE test:2 SET text = "Relational databases store tables.", embedding = [0.05, 0.10, 0.00];
CREATE test:3 SET text = "This document mentions graphs and networks.", embedding = [0.20, 0.10, 0.25];

-- Analyzer used by the full‑text index
DEFINE ANALYZER simple TOKENIZERS class, punct FILTERS lowercase, ascii;

-- Full‑text index
DEFINE INDEX idx_text ON TABLE test FIELDS text FULLTEXT ANALYZER simple BM25;

-- Vector index (HNSW) on a 3‑dimensional embedding, using cosine distance
DEFINE INDEX idx_embedding ON TABLE test FIELDS embedding HNSW DIMENSION 3 DIST COSINE;

-- Query vector (whatever your embedding model produced for "graph databases")
LET $qvec = [0.12, 0.18, 0.27];

-- Vector search: top 2 nearest neighbours
LET $vs = SELECT id FROM test  WHERE embedding <|2,100|> $qvec;

-- Full‑text search: top 2 lexical matches
LET $ft = SELECT id, search::score(1) as score FROM test
          WHERE text @1@ 'graph' ORDER BY score DESC LIMIT 2;

-- Fuse with Linear / minmax
search::linear([$vs, $ft], [2, 1], 2, 'minmax');

-- Fuse with Linear / zscore
search::linear([$vs, $ft], [2, 1], 2, 'zscore');
```

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

### Example usage

Source: https://surrealdb.com/docs/reference/mojo/methods/signup

Demonstrates how to encode signup credentials using CborCodec and execute the signup method.

```python
from surrealdb import CborCodec
from std.collections import List

var codec = CborCodec()
var pairs = List[Tuple[String, List[UInt8]]]()
pairs.append(Tuple(String("namespace"), codec.encode_text("test")))
pairs.append(Tuple(String("database"), codec.encode_text("test")))
pairs.append(Tuple(String("access"), codec.encode_text("user")))
pairs.append(Tuple(String("email"), codec.encode_text("chiru@example.com")))
pairs.append(Tuple(String("pass"), codec.encode_text("changeme")))

var resp = client.signup(codec.encode_map(pairs))
```

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

### Actix Web and SurrealDB Application Setup

Source: https://surrealdb.com/docs/reference/rust/frameworks/actix

This example shows the full implementation of an Actix Web application, including a static database connection, custom error handling, and various CRUD routes for managing person records.

```rust
use actix_web::{App, HttpServer};
use std::sync::LazyLock;
use surrealdb::Surreal;
use surrealdb::engine::remote::ws::Client;
use surrealdb::engine::remote::ws::Ws;
use surrealdb::opt::auth::Root;

static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);

mod error {
    use actix_web::{HttpResponse, ResponseError};
    use thiserror::Error;

    #[derive(Error, Debug)]
    pub enum Error {
        #[error("database error")]
        Db(String),
    }

    impl ResponseError for Error {
        fn error_response(&self) -> HttpResponse {
            match self {
                Error::Db(e) => HttpResponse::InternalServerError().body(e.to_string()),
            }
        }
    }

    impl From<surrealdb::Error> for Error {
        fn from(error: surrealdb::Error) -> Self {
            eprintln!("{error}");
            Self::Db(error.to_string())
        }
    }
}

mod routes {

    use fake::Fake;
    use fake::faker::name::en::FirstName;
    use surrealdb::opt::auth::Record;

    use crate::DB;
    use crate::error::Error;
    use actix_web::web::{Json, Path};
    use actix_web::{delete, get, post, put};
    use serde::{Deserialize, Serialize};
    use surrealdb::types::{RecordId, SurrealValue};
    const PERSON: &str = "person";

    #[derive(SurrealValue, Deserialize)]
    pub struct PersonData {
        name: String,
    }

    #[derive(SurrealValue, Deserialize, Serialize)]
    pub struct Person {
        name: String,
        id: RecordId,
    }

    #[get("/")]
    pub async fn paths() -> &'static str {
        r#"

-----------------------------------------------------------------------------------------------------------------------------------------
        PATH                |           SAMPLE COMMAND                                                                                  
-----------------------------------------------------------------------------------------------------------------------------------------
/session: See session data  |  curl -X GET    -H "Content-Type: application/json"                          http://localhost:8080/session
                            |
/person/{id}:               |
  Create a person           |  curl -X POST   -H "Content-Type: application/json" -d '{"name":"John Doe"}' http://localhost:8080/person/one
  Get a person              |  curl -X GET    -H "Content-Type: application/json"                          http://localhost:8080/person/one
  Update a person           |  curl -X PUT    -H "Content-Type: application/json" -d '{"name":"Jane Doe"}' http://localhost:8080/person/one
  Delete a person           |  curl -X DELETE -H "Content-Type: application/json"                          http://localhost:8080/person/one
                            |
/people: List all people    |  curl -X GET    -H "Content-Type: application/json"                          http://localhost:8080/people

/new_user:  Create a new record user
/new_token: Get instructions for a new token if yours has expired"#
    }

    #[get("/session")]
    pub async fn session() -> Result<Json<String>, Error> {
        let res: Option<String> = DB.query("<string>$session").await?.take(0)?;

        Ok(Json(res.unwrap_or("No session data found!".into())))
    }

    #[post("/person/{id}")]
    pub async fn create_person(
        id: Path<String>,
        person: Json<PersonData>,
    ) -> Result<Json<Option<Person>>, Error> {
        let person = DB
            .create((PERSON, id.into_inner()))
            .content(person.into_inner())
            .await?;
        Ok(Json(person))
    }

    #[get("/person/{id}")]
    pub async fn read_person(id: Path<String>) -> Result<Json<Option<Person>>, Error> {
        let person = DB.select((PERSON, id.into_inner())).await?;
        Ok(Json(person))
    }

    #[put("/person/{id}")]
    pub async fn update_person(
        id: Path<String>,
        person: Json<PersonData>,
    ) -> Result<Json<Option<Person>>, Error> {
        let person = DB
            .update((PERSON, id.into_inner()))
            .content(person.into_inner())
            .await?;
        Ok(Json(person))
    }

    #[delete("/person/{id}")]
    pub async fn delete_person(id: Path<String>) -> Result<Json<Option<Person>>, Error> {
        let person = DB.delete((PERSON, id.into_inner())).await?;
        Ok(Json(person))
    }

    #[get("/people")]
    pub async fn list_people() -> Result<Json<Vec<Person>>, Error> {
        let people = DB.select(PERSON).await?;
        Ok(Json(people))
    }

    #[derive(SurrealValue)]
    struct Params {
        name: String,
        pass: String,
    }

```

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

### Signup Example Usage

Source: https://surrealdb.com/docs/reference/rust/embedding

Demonstrates signing up with a scope and custom credentials struct. Ensure the resulting JWT is handled securely.

```rust
use serde::Serialize;
use surrealdb::opt::auth::Scope;

#[derive(Serialize)]
struct Credentials<'a> {
    email: &'a str,
    pass: &'a str,
}

let jwt = db.signup(Scope {
    namespace: "main",
    database: "main",
    access: "user",
    params: Credentials {
        email: "info@surrealdb.com",
        pass: "123456",
    },
}).await?;

// ⚠️: It is important to note that the token should be handled securely and protected from unauthorized access.
let token = jwt.as_insecure_token();
```

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

### Install SurrealDB Nightly on Windows

Source: https://surrealdb.com/docs/running/installation/nightly

Use the PowerShell install script to download and install the nightly version on Windows.

```powershell
iex "& { $(irm https://windows.surrealdb.com) } -Nightly"
```

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

### Example usage

Source: https://surrealdb.com/docs/reference/rust/methods/connect

Demonstrates connecting to local and remote endpoints using different protocols and optional configuration settings.

```rust
use std::sync::LazyLock;
use std::time::Duration;
use surrealdb::engine::remote::ws::{Client, Ws, Wss};
use surrealdb::opt::Config;
use surrealdb::Surreal;

static DB: LazyLock<Surreal<Client>> = LazyLock::new(Surreal::init);

#[tokio::main]
async fn main() -> surrealdb::Result<()> {
    // Connect to a local endpoint
    DB.connect::<Ws>("127.0.0.1:8000").await?;
    // Connect to a remote endpoint
    DB.connect::<Wss>("cloud.surrealdb.com").await?;
    // A tuple with a Config struct can also be passed in for fine tuning of the connection
    let config = Config::default().query_timeout(Duration::from_millis(1500));
    DB.connect::<Ws>(("127.0.0.1:8000", config)).await?;
    Ok(())
}
```

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

### Install SurrealDB Nightly on Unix

Source: https://surrealdb.com/docs/running/installation/nightly

Use the install script to download and install the nightly version on macOS or Linux systems.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://install.surrealdb.com | sh -s -- --nightly
```

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

### Install Spectron CLI via script

Source: https://surrealdb.com/docs/spectron/reference/cli

Automated installation script for macOS and Linux that resolves the latest version and installs to the system path.

```bash
curl -fsSL https://download.surrealdb.com/spectron/install.sh | sh
```

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

### Main Application Entry Point

Source: https://surrealdb.com/docs/build/integrations/ai-frameworks/cocoindex

Initializes the database connection, environment, and executes graph building tasks.

```rust
#[tokio::main]
async fn main() -> Result<()> {
    let session = load_session()?;
    println!(
        "Loaded transcript: {} ({} utterances)\n",
        session.title,
        session.utterances.len()
    );

    let graph = Graph::connect(
        &env_or("SURREALDB_URL", "127.0.0.1:8000"),
        &env_or("SURREALDB_NS", "cocoindex"),
        &env_or("SURREALDB_DB", "beato_cantrell"),
        &env_or("SURREALDB_USER", "root"),
        &env_or("SURREALDB_PASS", "secret"),
    )
    .await?;

    let dir = tempfile::tempdir()?;
    let app = Environment::builder()
        .db_path(dir.path().join("cocoindex_lmdb"))
        .provide_key(&GRAPH, graph.clone())
        .build()
        .await?
        .app("beato_cantrell_demo")
        .await?;

    println!("Run 1 — full graph (includes Tony Iommi / Black Sabbath branch)");
    build_graph(&app, &session, true).await?;
    print_counts(&graph).await?;

    println!("\nRun 2 — narrower extraction (Sabbath influence branch reconciled away)");
    build_graph(&app, &session, false).await?;
    print_counts(&graph).await?;

    print_query_hints();
    Ok(())
}
```

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

### Initialize Database Connection

Source: https://surrealdb.com/docs/manage/schema-migration/library/example

Basic connection setup using environment variables.

```rust
use surrealkit::{DbCfg, DbOverrides, connect};

let cfg = DbCfg::from_env(None, &DbOverrides::default())?;
let db = connect(&cfg).await?;
```

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

### Install Dependencies

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/autogen

Install the required AutoGen and SurrealDB packages.

```bash
pip install autogen-agentchat autogen-ext[openai] surrealdb
```

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

### Initialize Spectron SDK

Source: https://surrealdb.com/docs/spectron/reference/agents

Examples for initializing the Spectron client in Python and JavaScript environments.

```python
from surrealdb import Spectron

memory = Spectron(context="acme-prod",
    api_key=os.environ["SPECTRON_API_KEY"])
await memory.sessions.create(scope=["org/acme/user/alice"])
```

```javascript
import { Spectron } from "@surrealdb/spectron";

const memory = new Spectron({ context: "acme-prod",
    apiKey: process.env.SPECTRON_API_KEY });
```

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

### Delete Record Example

Source: https://surrealdb.com/docs/reference/php/v2/api/query-builders

Example of deleting a record by its ID.

```php
$db->delete(new RecordId('person', 'tobie'))->execute();
```

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

### SignUp Example Usage

Source: https://surrealdb.com/docs/reference/dotnet/core/authentication

Demonstrates signing up a user with record access by providing AuthParams and receiving a JWT.

```csharp
// With Record Access
var authParams = new AuthParams
{
    Namespace = "main",
    Database = "main",
    Access = "user",
	// Also pass any properties required by the access definition
    Email = "info@surrealdb.com",
    Password = "123456"
};

Jwt jwt = await db.SignUp(authParams);

public class AuthParams : ScopeAuth
{
	public string? Username { get; set; }
	public string? Email { get; set; }
	public string? Password { get; set; }
}
```

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

### GET /ready

Source: https://surrealdb.com/docs/reference/rest-api/http-protocol

Checks whether the instance has finished startup and is ready to serve traffic.

```APIDOC
## GET /ready

### Description
Checks whether the instance has finished startup and is ready to serve traffic.

### Method
GET

### Endpoint
/ready
```

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

### UpdatePromise Content Example

Source: https://surrealdb.com/docs/reference/javascript/api/queries/update-promise

Example of replacing all fields of a record.

```ts
const user = await db.update(new RecordId('users', 'john'))
    .content({
        name: 'John Smith',
        email: 'john.smith@example.com',
        age: 31
    });
// Replaces all fields
```

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

### Create Sample Data

Source: https://surrealdb.com/docs/learn/schema-management/schema-design/sample-industry-schemas

Initializes payment terms, project structures, vendors, purchase orders, and invoices.

```SurrealQL
CREATE payment_terms:net30 SET
    code = "NT30",
    net_due = 30d,
    description = "Net 30 days";
CREATE payment_terms:net27 SET
    code = "Z027",
    net_due = 27d,
    description = "Net 27 days";
CREATE payment_terms:payrcpt SET
    code = "Z000",
    net_due = 0d,
    description = "Due on receipt";

CREATE project:pad3 SET name = "Pad 3 expansion";
CREATE wbs_element:pad3 SET
    sap_id = "EP-24-PAD3",
    project = project:pad3,
    name = "Pad 3 package";
CREATE wbs_element:pad3_civil SET
    sap_id = "EP-24-PAD3-CIVIL",
    project = project:pad3,
    parent = wbs_element:pad3,
    name = "Civil & earthworks";

RELATE wbs_element:pad3 -> wbs_of -> project:pad3;
RELATE wbs_element:pad3_civil -> wbs_of -> project:pad3;
RELATE wbs_element:pad3_civil -> wbs_child_of -> wbs_element:pad3;

CREATE vendor:welding SET
    name = "Northern Weld Services Ltd",
    sap_vendor_number = "0000100042",
    default_payment_terms = payment_terms:net30;
CREATE vendor:small SET
    name = "Camp Catering Co-op",
    sap_vendor_number = "0000100891",
    default_payment_terms = payment_terms:payrcpt;

CREATE purchase_order:450001 SET
    sap_po_number = "4500000123",
    vendor = vendor:welding,
    currency = "CAD",
    issued_at = d'2026-05-15';
RELATE purchase_order:450001 -> ordered_from -> vendor:welding;

CREATE po_line:line10 SET
    purchase_order = purchase_order:450001,
    line_number = 10,
    description = "Structural welding — pipe rack",
    amount_cents = 18500000,
    wbs = wbs_element:pad3_civil;
RELATE po_line:line10 -> charges -> wbs_element:pad3_civil;

CREATE vendor_invoice:510001 SET
    sap_doc_number = "5100000456",
    purchase_order = purchase_order:450001,
    vendor = vendor:welding,
    amount_cents = 9250000,
    payment_terms = payment_terms:net30,
    baseline_date = d'2026-06-01',
    due_date = d'2026-07-01',
    status = "approved";
RELATE vendor_invoice:510001 -> invoices -> purchase_order:450001;
```

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

### Install dependencies

Source: https://surrealdb.com/docs/spectron/integrations/observability/agentops

Install the necessary packages for AgentOps, SurrealDB, and OpenAI.

```bash
pip install agentops surrealdb openai
```

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

### Install Spectron Hermes

Source: https://surrealdb.com/docs/spectron/integrations/frameworks/hermes

Install the required package via pip.

```bash
pip install spectron-hermes
```

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

### Install OpenSwoole extension

Source: https://surrealdb.com/docs/reference/php/v2/concepts/runtimes

Install the OpenSwoole extension via PECL.

```bash
pecl install openswoole
```

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

### Selecting a Runtime Preset

Source: https://surrealdb.com/docs/reference/php/v2/concepts/runtimes

Use the Runtime helper to configure the driver for synchronous, OpenSwoole, or Amp environments.

```php
use SurrealDB\SDK\Surreal;
use SurrealDB\SDK\Runtime\Runtime;

$db = new Surreal(Runtime::sync());   // default, synchronous
$db = new Surreal(Runtime::swoole()); // OpenSwoole coroutines
$db = new Surreal(Runtime::amp());    // Amp / Revolt event loop
```

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

### Install dependencies

Source: https://surrealdb.com/docs/build/integrations/embeddings-providers/mistral

Install the required Python packages for Mistral and SurrealDB.

```bash
pip install mistralai surrealdb
```

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

### Install HTTP Client for Surqlize

Source: https://surrealdb.com/docs/reference/php/libraries/surqlize/installation

Install Guzzle and discovery packages to enable HTTP transport for the SDK.

```bash
composer require guzzlehttp/guzzle php-http/discovery
```

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

### Install SurrealML with PyTorch

Source: https://surrealdb.com/docs/explore/ml-models

Installs the SurrealML package with only PyTorch support.

```bash
pip install "git+https://github.com/surrealdb/surrealml#egg=surrealml[torch]"
```

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

### Install SurrealML with sklearn

Source: https://surrealdb.com/docs/explore/ml-models

Installs the SurrealML package with only sklearn support.

```bash
pip install "git+https://github.com/surrealdb/surrealml#egg=surrealml[sklearn]"
```

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

### Use Method Parameter Combinations

Source: https://surrealdb.com/docs/reference/rest-api/rpc-protocol

Demonstrates various combinations of namespace and database settings using strings, null, and none.

```surql
[none, none]     -- Won't change ns or db
["test", none]   -- Change ns to test
[none, "test"]   -- Change db to test
["test", "test"] -- Change ns and db to test

[none, null]     -- Will only unset the database
[null, none]     -- Will throw an error, you cannot unset only the database
[null, null]     -- Will unset both ns and db
["test", null]   -- Change ns to test and unset db
```
Tokens:
Raw