Representations and codecs

Many SurrealDB built-ins do the same broad job: take a value in representation A and produce a value in representation B. As these tend to be found over various parts of the documentation, this page is a map to introduce them in a single location and help you pick the right one.

Quick overview

Serialisation (encoding::*)

Reversible codecs for wire formats and storage:

• encoding::json::encode / decode — JSON text

• encoding::cbor::encode / decode — CBOR bytes

• encoding::base64::encode / decode — Base64 text for binary payloads

Typical uses: DEFINE API request bodies, file bucket payloads, and SDK interchange. Round-trip is the mental model.

LET $payload = { event: 'signup', user: 'tobie' };

-- Value → JSON text → value again
encoding::json::decode(encoding::json::encode($payload));
-- { event: 'signup', user: 'tobie' }

Related one-way or format-specific helpers elsewhere include string::html::encode, geo::hash::encode, and crypto::* hashes.

Text analysis (search::analyze)

search::analyze runs a named DEFINE ANALYZER pipeline on a string and returns an array of tokens. It is lossy (stemming, filtering) and mirrors what full-text indexing does — useful for debugging analyzers before you index.

The "format" here is not JSON or CBOR; it is whatever pipeline you defined on the analyzer.

DEFINE ANALYZER demo_blank TOKENIZERS blank;

search::analyze("demo_blank", "SurrealDB graph queries");
-- ['SurrealDB', 'graph', 'queries']

Compare the tokens above with what you get after adding FILTERS lowercase, snowball(english) — the same input string produces a different token list, which is why search::analyze is handy when tuning an analyzer before you create a FULLTEXT index.

Structured parsing (parse::*)

parse::url::* and parse::email::* extract one component from a structured string. There is no round-trip — you get a field value, not a reassembled URL.

{
	domain: parse::url::domain("https://surrealdb.com/docs"),
	user: parse::email::user("tobie@surrealdb.com"),
};
-- { domain: 'surrealdb.com', user: 'tobie' }

In-value transforms (value::*)

value::diff and value::patch move between a SurrealQL value and JSON Patch operations. They pair naturally with changefeeds and LIVE SELECT DIFF.

LET $before = { title: 'Weekly update', status: 'draft' };
LET $after = { title: 'Weekly update', status: 'published' };
LET $patch = value::diff($before, $after);

value::patch($before, $patch);
-- { title: 'Weekly update', status: 'published' }

value::diff produced the patch; value::patch applied it. The same pair works when you receive patch operations from a client or a live diff stream.

Dynamic evaluation (eval::*)

eval::surql and eval::gql parse and execute query text in the caller's transaction. That is fundamentally different from encoding:

• Input is executable SurrealQL or ISO GQL, not a static wire format.

• Denied by default — requires allow-eval-query and the arbitrary-query gate.

• Nested writes affect the caller's transaction; transaction-control statements are rejected.

Use eval::* when the query string is only known at runtime. Prefer DEFINE FUNCTION, DEFINE API, or normal client queries when the shape of the work is fixed at deploy time.

-- Query text from a table, config row, or user input (requires allow-eval-query)
LET $template = "$greeting + ', ' + $name";
eval::surql($template, { greeting: 'Hello', name: 'world' });
-- 'Hello, world'

For ISO GQL strings, use eval::gql instead — same bindings object, plus the gql experimental capability. See Eval functions for setup and examples.

See also

• Database functions catalogue

• Parameterised queries — $parameters at the SurrealQL layer (contrast with eval bindings)

• Capabilities