Types

RecordID(table, id)
RecordID(s::AbstractString)

SurrealDB record identifier: table:id. id is any serializable value (string, integer, vector, dict, ...). Equality + hashing follow the struct fields, so RecordID is usable as a Dict key.

Examples

RecordID("user", "abc123")     # table + string id
RecordID("user", 42)           # table + integer id
RecordID("user:abc123")        # parse `table:id` form

StringRecordID(s::AbstractString)

Opaque "raw string record id" wrapper. Holds s verbatim and ships it to the server as a plain CBOR text string for server-side parsing. Use when the id form is too complex for RecordID(table, id) (e.g. nested objects, ranges, escaped characters) and you want the server's parser to handle it. Mirrors StringRecordId in surrealdb.js / surrealdb.net.

For the common case prefer RecordID(t, i) or rid"t:i" — those go through the typed CBOR path and round-trip on decode.

StringRecordID("users:42")
StringRecordID("posts:⟨2024-01-15, 'ulid'⟩")

rid"table:id"

String macro for RecordID literals. Parses at compile time. Requires exactly one : separator with both parts non-empty; complex ids (nested objects, ranges, escaped colons) should use StringRecordID(...) or the explicit RecordID(table, id) constructor.

rid"users:42"          # ≡ RecordID("users", "42")
rid"posts:abc-123"     # ≡ RecordID("posts", "abc-123")

SurrealThing

Mirrors SurrealDB's sr_thing_t — a record ID (table + id). Equivalent to RecordID but named to match the C API convention.

Table(name)

SurrealDB table-name wrapper. Distinguishes "the table named X" from a plain string in the API.

Table("stream")

SurrealValue(kind::SurrealValueKind, value)

A tagged union representing any SurrealDB value type. Used internally for precision type handling when mapping to/from C FFI types in embedded mode.

Most users never construct one directly — query / select / etc. handle the conversions automatically.

Relationship(in, relation, out; data=Dict())

Represents a graph relationship between two records.

Examples

rel = Relationship("person:john", Table("knows"), "person:jane",
                    data=Dict("met" => "2024-01-01"))

SurrealDecimal(s::AbstractString)

Wire-format wrapper for SurrealDB's Decimal. Stores the canonical string form as emitted by the server. Construct from a literal string; convert to BigFloat if arithmetic is needed (note: binary-radix conversion is approximate).

SurrealDecimal("3.14159")
SurrealDecimal("-0.5")
BigFloat(SurrealDecimal("1.5"))   # 1.5 — exact in this case

SurrealDateTime(seconds::Int64, nanos::UInt32)

Wire-format datetime: seconds since the Unix epoch (1970-01-01 UTC) + sub-second nanoseconds (0..999_999_999). UTC; no timezone offset is stored (wire form always normalizes to UTC).

SurrealDateTime(1_716_423_296, UInt32(123_456_789))  # 2024-05-22T...

Convert to / from Dates.DateTime:

Dates.DateTime(SurrealDateTime(1_716_423_296, UInt32(123_000_000)))
# 2024-05-22T22:54:56.123 — sub-ms portion rounded
SurrealDateTime(Dates.DateTime(2024, 5, 22))
# SurrealDateTime(1716336000, 0x00000000)

SurrealDuration(seconds::Integer, nanos::Integer)

Wire-format duration: non-negative seconds + sub-second nanoseconds (0..999_999_999). Server-canonical encode emits the shortest form:

• (0, 0) → empty array
• (s, 0) → [s]
• (s, ns) → [s, ns]

SurrealDuration(0, 0)              # zero
SurrealDuration(3600, 0)           # 1h
SurrealDuration(0, 500_000_000)    # 0.5s
SurrealDuration(3600, 500_000_000) # 1h 0.5s

SurrealFile(bucket::AbstractString, key::AbstractString)

Reference to a file in a SurrealDB-managed bucket. Both bucket and key are opaque strings; SDK doesn't validate path syntax.

SurrealFile("avatars", "user_42/profile.png")

SurrealRange(start, stop)

Half-open or fully-bounded range. Each of start / stop is one of:

• BoundIncluded — inclusive bound
• BoundExcluded — exclusive bound
• nothing — unbounded side

SurrealRange(BoundIncluded(1), BoundExcluded(10))   # [1, 10)
SurrealRange(BoundIncluded(1), nothing)             # [1, ∞)
SurrealRange(nothing, BoundExcluded(0))             # (-∞, 0)

BoundIncluded(value)

Inclusive range bound ([value, ...). The wrapped value is any serializable Julia value.

BoundExcluded(value)

Exclusive range bound ((value, ...). The wrapped value is any serializable Julia value.

GeometryPoint(x::Real, y::Real)

2D point in lon/lat (or x/y) order. Both coordinates stored as Float64 — matches server's f64 payload.

GeometryLine(points::Vector{GeometryPoint})

Open or closed line — array of points. SurrealDB doesn't enforce minimum length here; an empty Line is technically representable though semantically rare.

GeometryPolygon(exterior::GeometryLine, interiors::Vector{GeometryLine}=GeometryLine[])

Polygon with one outer ring and zero or more inner holes. Server requires non-empty (at least one exterior).

GeometryMultiPoint(points::Vector{GeometryPoint})

Collection of independent points.

GeometryMultiLine(lines::Vector{GeometryLine})

Collection of independent lines.

GeometryMultiPolygon(polygons::Vector{GeometryPolygon})

Collection of independent polygons.

GeometryCollection(geometries::Vector{Any})

Heterogeneous collection — any mix of the Geometry types above. Stored as Vector{Any} since the elements may differ per index.

to_table(results) -> QueryResultTable

Convert query results to a Tables.jl-compatible source. Can be passed directly to DataFrame() from DataFrames.jl, Tables.columntable, etc.

results can be:

• A Vector{Dict{String, Any}} (single-statement result rows)
• A Vector{Any} containing nested vectors of dicts (multi-statement; rows are flattened across all statements)
• A single Dict (treated as a one-row table)

to_metagraph(vertices, edges; ...)
to_metagraph(client::SurrealClient, vertices_query::String, edges_query::String; ...)

Materialize query results into a MetaGraphsNext.MetaGraph (with vertex labels = record-id strings, vertex/edge data = field Dicts). Method bodies live in the SurrealDBMetaGraphsNextExt Pkg extension, loaded automatically by Julia 1.9+ when the user has MetaGraphsNext and Graphs in their environment.

If the extension isn't loaded, calls throw a clear error pointing the user at the right install command.

QueryResultTable

A Tables.jl-compatible wrapper around query results. Stores rows as a Vector{Dict{String, Any}} and delegates Tables.jl operations to Tables.dictrowtable / Tables.dictcolumntable so columns are derived lazily on access (no eager materialization). Use to_table to construct from raw query results.

Examples

result = SurrealDB.query(db, "SELECT * FROM stream")
table = SurrealDB.to_table(result)
using DataFrames
df = DataFrame(table)        # column-major access
for row in Tables.rows(table)  # row-major iteration
    println(row)
end