Sdbql Functions Misc — SoliDB Docs

Type Checking Functions

Functions to check the type of values at runtime.

IS_ARRAY(val)

Returns true if value is an array.

RETURN IS_ARRAY([1,2]) --true

IS_BOOLEAN(val)

Returns true if value is a boolean.

RETURN IS_BOOLEAN(true) --true

IS_NUMBER(val)

Returns true if value is a number.

RETURN IS_NUMBER(42) --true

IS_INTEGER(val)

Returns true if value is an integer (no decimals).

RETURN IS_INTEGER(3.14) --false

IS_STRING(val)

Returns true if value is a string.

RETURN IS_STRING("hi") --true

IS_OBJECT(val)

Returns true if value is an object.

RETURN IS_OBJECT({a:1}) --true

IS_NULL(val)

Returns true if value is null.

RETURN IS_NULL(null) --true

IS_DATETIME(val)

Returns true if value is an ISO 8601 date string.

RETURN IS_DATETIME("2024-01-15T10:30:00Z") --true

TYPENAME(val)

Returns the type name as a string.

RETURN TYPENAME([1,2]) --"array"
RETURN TYPENAME("hi") --"string"

IS_EMAIL(val)

Returns true if value is a valid email format.

RETURN IS_EMAIL("user@example.com") --true

IS_URL(val)

Returns true if value is a valid URL format.

RETURN IS_URL("https://example.com") --true

IS_UUID(val)

Returns true if value is a valid UUID format.

RETURN IS_UUID("550e8400-e29b-41d4-...") --true

IS_EMPTY(val)

Returns true if value is null, "", [], or {}.

RETURN IS_EMPTY([]) --true
RETURN IS_EMPTY("") --true

IS_BLANK(val)

Returns true if string is blank (whitespace only).

RETURN IS_BLANK("   ") --true

Type Casting Functions

Functions to convert values between different types.

TO_BOOL(value)

Casts value to boolean.

RETURN TO_BOOL(null) --false
RETURN TO_BOOL(1) --true
RETURN TO_BOOL(0) --false

TO_NUMBER(value)

Casts value to number.

RETURN TO_NUMBER("123") --123
RETURN TO_NUMBER(true) --1
RETURN TO_NUMBER("foo") --0

TO_STRING(value)

Casts value to string.

RETURN TO_STRING(123) --"123"
RETURN TO_STRING(true) --"true"
RETURN TO_STRING(null) --""

TO_ARRAY(value)

Casts value to array.

RETURN TO_ARRAY(null) --[]
RETURN TO_ARRAY("foo") --["foo"]
RETURN TO_ARRAY({a:1}) --[1]

Logical & Conditional

Functions for conditional logic and null handling.

IF(cond, true, false)

Condition evaluation. Returns true_val if cond is true, else false_val.

RETURN IF(1 > 0, "yes", "no") --"yes"
RETURN IF(null, 1, 0) --0

cond ? true : false

Ternary operator. Syntactic sugar for IF function.

RETURN doc.age >= 18 ? "Adult" : "Minor"
RETURN a ? b ? "both" : "a" : "none"

COALESCE(val1, val2, ...)

Returns the first non-null value. Alias: NOT_NULL.

RETURN COALESCE(null, 0, 5) --0

NULLIF(expr1, expr2)

Returns null if expr1 equals expr2, otherwise returns expr1. Useful for avoiding division by zero.

RETURN NULLIF(10, 10) --null
RETURN NULLIF(10, 5) --10

Object Functions

Functions for manipulating objects and documents.

MERGE(obj1, obj2)

Shallow merge of objects.

RETURN MERGE({a:1}, {b:2})

DEEP_MERGE(obj1, obj2, ...)

Deep merge objects recursively.

RETURN DEEP_MERGE({a:{b:1}}, {a:{c:2}})
--{a:{b:1,c:2}}

GET(obj, path, default?)

Get nested value by dot-notation path.

RETURN GET(doc, "user.name", "N/A")

HAS(doc, attr)

Checks if document contains attribute.

FILTER HAS(doc, "email")

KEEP(doc, attr...)

Keep only specified attributes.

RETURN KEEP(doc, "name", "email")

UNSET(doc, attr...)

Removes specified attributes.

RETURN UNSET(doc, "password")

REDACT(doc, keys)

Deep-remove keys from objects and nested objects/arrays.

RETURN REDACT(doc, ["ssn", "email"])

ATTRIBUTES(doc, removeInternal?, sort?)

Top-level attribute keys of the document.

RETURN ATTRIBUTES(doc, true)

VALUES(doc, removeInternal?)

Returns top-level attribute values.

RETURN VALUES(doc, true)

ENTRIES(obj)

Convert object to [key, value] pairs.

RETURN ENTRIES({a:1,b:2})
--[["a",1],["b",2]]

FROM_ENTRIES(arr)

Convert [key, value] pairs to object.

RETURN FROM_ENTRIES([["a",1],["b",2]])
--{a:1,b:2}

LENGTH(val)

Count elements in array/object.

RETURN LENGTH([1,2,3]) --3

Collection Functions

COLLECTION_COUNT(name)

Returns the number of documents in a collection. Efficient metadata lookup without iterating documents.

RETURN COLLECTION_COUNT("users") --42

Usage Example

Get document counts for multiple collections:

RETURN {
  users: COLLECTION_COUNT("users"),
  orders: COLLECTION_COUNT("orders"),
  products: COLLECTION_COUNT("products")
}

Auth, sketches, events, RAG

CURRENT_USER() / CURRENT_ROLES() / CAN(action [, doc])

Request principal. HTTP queries get the JWT user. Without a principal, CAN is false and CURRENT_USER is null. Actions: read, write, admin. Optional doc also checks owner/_owner and _acl.{action} (user, role, or *).

FILTER CAN("write")
RETURN CURRENT_USER()

ROW_POLICY(coll [, pred])

Store a filter expression on the collection. Non-admin FOR scans evaluate it with the doc bound as the collection name and as doc. Pass null to clear.

RETURN ROW_POLICY("orders", "orders.tenant == @tenant")

PARSE_IDENTIFIER / PARSE_COLLECTION / PARSE_KEY

Split a document id collection/key. Extra slashes stay in the key.

RETURN PARSE_IDENTIFIER("users/ada")
-- { collection: "users", key: "ada" }

UNSET_RECURSIVE / KEEP_RECURSIVE / ZIP_OBJECT

Deep drop or keep named keys. ZIP_OBJECT(keys, values) builds an object (pair-wise ZIP is unchanged for numeric arrays).

RETURN UNSET_RECURSIVE(doc, "ssn")
RETURN ZIP_OBJECT(["a","b"], [1,2])

APPLY(name, args) / CALL(name, …)

Call another builtin by name. Recursion is capped at 8.

RETURN CALL("UPPER", "hi")
RETURN APPLY("ABS", [-3])

MINHASH / MINHASH_COUNT / MINHASH_ERROR

MinHash signatures for Jaccard-style set comparison. MINHASH_COUNT(0.05) is 400 hashes.

RETURN MINHASH(["a","b","c"], 16)

APPROX_COUNT_DISTINCT / APPROX_PERCENTILE / APPROX_TOP_K / SKETCH_MERGE

HyperLogLog (p=14), percentile, Space-Saving top-k. HLL results are objects with _type: "hll" and estimate; merge two sketches with SKETCH_MERGE.

RETURN APPROX_PERCENTILE(amounts, 95)

MATCH_SEQ(events, key, steps)

Find ordered event sequences per key. Steps: {as, type, field, equals, within}. Times use ts / t / time.

RETURN MATCH_SEQ(events, "user", [
  {as: "a", type: "signup"},
  {as: "b", type: "pay", within: "7d"}
])

SNAPSHOT_DIFF(coll, t1, t2)

On a versioned collection, classify documents inserted, updated, or deleted between two timestamps.

RETURN SNAPSHOT_DIFF("orders", t1, t2)

EMBED / EXTRACT / CITE / GROUNDED / SEMANTIC

EMBED and EXTRACT call the configured LLM (same providers as auto-embed). CITE / GROUNDED fall back to lexical overlap. SEMANTIC(doc, q) is a trigram score.

RETURN CITE(@answer, results)
RETURN EMBED(doc.body, { provider: "openai" })

Hashing & Encoding

Functions for hashing strings and encoding/decoding data.

MD5(string)

Calculates MD5 hash of a string.

RETURN MD5("hello") --"5d41402abc4b2a76..."

SHA256(string)

Calculates SHA256 hash of a string.

RETURN SHA256("hello") --"2cf24dba5fb0a30e..."

BASE64_ENCODE(string)

Encodes string to Base64.

RETURN BASE64_ENCODE("hello") --"aGVsbG8="

BASE64_DECODE(string)

Decodes Base64 string.

RETURN BASE64_DECODE("aGVsbG8=") --"hello"

Unique ID Generation

Functions for generating unique identifiers for documents and keys.

UUID()

Generates a random UUID v4. Alias: UUID_V4().

RETURN UUID()
--"550e8400-e29b-41d4-..."

UUIDV7()

Generates a time-ordered UUID v7.

RETURN UUIDV7()
--"018f6e4a-5b7c-7d8e-..."

ULID()

Generates a Lexicographically Sortable Identifier.

RETURN ULID()
--"01ARZ3NDEKTSV4RR..."

NANOID(size?)

Generates a Nano ID (default 21 chars).

RETURN NANOID()
--"V1StGXR8_Z5jdHi6B-myT"

ID Type Comparison

Type	Length	Sortable	Best For
UUID v4	36 chars	No	General unique identifiers
UUID v7	36 chars	Yes	Time-ordered records, primary keys
ULID	26 chars	Yes	Compact time-sortable IDs
Nano ID	21 chars	No	URL-safe short IDs, user-facing

Debugging & Control

ASSERT(cond, msg)

Throws error if condition false.

RETURN ASSERT(x > 0, "Fail")

SLEEP(ms)

Pauses execution (for testing).

RETURN SLEEP(1000) --1s

Other Functions