Data Types

The Python SDK translates all datatypes native to SurrealQL into either datatypes native to Python, or a custom implementation. This document describes all datatypes, and links to their respective documentation.

Data Types overview

Duration

When you receive a duration from SurrealDB, it will always be represented as a Duration class.

Signature
from surrealdb import Duration

Duration(duration: str | int | list[int, int])

Create a Duration

from surrealdb import Duration

# Parsed from a duration string
Duration("1w2d")
# Input milliseconds
Duration(1000)
# From a compact format ([ms, ns])
Duration([10000, 300])

# By a unit amount
Duration.nanoseconds(1000)
Duration.microseconds(1000)
Duration.milliseconds(1000)
Duration.seconds(1000)
Duration.minutes(1000)
Duration.hours(1000)
Duration.days(1000)
Duration.weeks(1000)

Transform a Duration

from surrealdb import Duration

dur = Duration("7d")

# Format as string, always as small as possible
dur.to_string()     # 1w
# Get inner milliseconds
dur._milliseconds  # 604800000
# Get compact format
dur.to_compact()    # [604800]

# How many of a full unit fit into the duration
dur.nanoseconds    # 604800000000000
dur.microseconds   # 604800000000
dur.milliseconds   # 604800000
dur.seconds        # 604800
dur.minutes        # 10080
dur.hours          # 168
dur.days           # 7
dur.weeks          # 1

Geometry

When a Geometry is sent back from SurrealDB, be it a Point, LineString, Polygon, MultiPoint, MultiLineString, MultiPolygon or Collection, it will be represented as a derivative of the Geometry class.

Methods

Below, are all the methods implemented across all geometry derivatives.

.to_json()

Used to convert a geometry to a GeoJSON representation

Signature
from surrealdb import Geometry

Geometry.to_json()

Example
from surrealdb import GeometryLine, GeometryPoint
import json

line = GeometryLine([
    GeometryPoint([1, 2]),
    GeometryPoint([3, 4]),
])

line.to_json()     # { type: "LineString", coordinates: [ [1, 2], [3, 4] ] }
json.dumps(line)   # '{ type: "LineString", coordinates: [ [1, 2], [3, 4] ] }'

.is()

Used to convert a check if geometry X is exactly equal to geometry Y

Signature
from surrealdb import Geometry

Geometry.is(geometry: Geometry)

Example
from surrealdb import GeometryLine, GeometryPoint

point1 = GeometryPoint([1, 2])
point2 = GeometryPoint([3, 4])
line = GeometryLine([point1, point2])

point1.is(point1)      # true
point1.is(point2)      # false
point1.is(line)        # false

# Checks the inner values, does not need to be the same instance
duplicate = GeometryPoint([1, 2])
point1.is(duplicate)   # true

.clone()

Used to deeply clone a geometry. Creates a replica of the original instance, but changing the instance won’t affect the other.

Signature
from surrealdb import Geometry

Geometry.clone()

Properties

.coordinates

A getter property, representing the coordinates as shown in GeoJSON format for X Geometry

Signature
from surrealdb import Geometry

Geometry.coordinates

Derivatives

GeometryPoint

A point in space, made up of a long and lat coordinate, automatically converted to a float.

Signature
from surrealdb import GeometryPoint

GeometryPoint([long: int | Decimal, lat: int | Decimal])

GeometryLine

A line, made up of two or more points

Signature
from surrealdb import GeometryLine, GeometryPoint

GeometryLine([GeometryPoint, GeometryPoint, ...])

GeometryPolygon

A polygon, made up of self-closing lines

Note: The lines inside the polygon will automatically be closed if not already, meaning that the last point will be the same as the first.

Signature
from surrealdb import GeometryPolygon, GeometryLine

GeometryPolygon([GeometryLine, ...])

GeometryMultiPoint

A collection of one or more points

Signature
from surrealdb import GeometryMultiPoint, GeometryPoint

GeometryMultiPoint([GeometryPoint, ...])

GeometryMultiLine

A collection of one or more lines

Signature
from surrealdb import GeometryMultiLine, GeometryLine

GeometryMultiLine([GeometryLine, ...])

GeometryMultiPolygon

A collection of one or more polygons

Signature
from surrealdb import GeometryMultiPolygon, GeometryPolygon

GeometryMultiPolygon([GeometryPolygon, ...])

GeometryCollection

A collection of one or more Geometry derivatives

Signature
from surrealdb import GeometryCollection, Geometry

GeometryCollection([Geometry, ...])

Table

When you get a table name sent back from SurrealDB, it will be represented as a Table class.

Signature
from surrealdb import Table

Table(table: str)

Converting to string

from surrealdb import Table

table = Table("table")
str(table)    # "table"

Converting to JSON

A Table will be represented as a string in JSON

from surrealdb import Table
import json

table = Table("table")
json.dumps(table) # "table"

RecordID

When you receive a RecordID back from SurrealDB, it will always be represented as a RecordID. The class holds tb and id fields, representing the table name, and a unique identifier for the record on that table. A RecordID can be converted into a string, and will be represented as such when it’s converted to JSON.

Signature
from surrealdb import RecordID

RecordID(tb: str, id: Any)

Working with a RecordID

Constructing
from surrealdb import RecordID

# table is "person"
# unique identifier on the table is "john"
rid = RecordID("person", "john")

Extracting data
from surrealdb import RecordID

# Simple
rid = RecordID("person", "john")
rid.table_name # "person"
rid.id # "john"

# Complex
rid = RecordID("recording", {"city": "London", "data": 123})
rid.id      # {"city": "London", "data": 123}
rid.id["city"] # "London"
rid.id["data"] # 123

Convert to String

Simple
from surrealdb import RecordID

str(RecordID('table', 123))
# 'table:123'
str(RecordID('table', 'abc'))
# 'table:abc'

Complex characters
from surrealdb import RecordID

str(RecordID('table', '123'))
# 'table:⟨123⟩'
str(RecordID('table', '123withletters'))
# 'table:123withletters'
str(RecordID('table', 'complex-string'))
# 'table:⟨complex-string⟩'
str(RecordID('table-name', 123))
# '⟨table-name⟩:123'

Objects and Arrays
from surrealdb import RecordID

str(RecordID('table', {"city": "London"}))
# 'table:{ city: "London" }'
str(RecordID('table', ["London"]))
# 'table:["London"]'

Parse a string to RecordID

The RecordID.parse method allows you to convert a string representation of a RecordID back into a RecordID object.

Basic parsing
from surrealdb import RecordID

# Parse a simple RecordID string
record_id = RecordID.parse("user:john")
print(record_id.table_name)  # "user"
print(record_id.id)  # "john"

Parsing special formats
from surrealdb import RecordID

# Parse RecordID with special characters in the ID
record_id = RecordID.parse("item:⟨complex-id⟩")
print(record_id.table_name)  # "item"
print(record_id.id)  # "complex-id"

Advanced parsing examples
from surrealdb import RecordID

# Parse a RecordID from a query result
result_id = "weather:['London', '2025-05-07']"
record_id = RecordID.parse(result_id)
print(record_id.table_name)  # "weather"
# The ID will be parsed as a string representation
print(record_id.id)  # "['London', '2025-05-07']"

# Using parse with error handling
try:
    record_id = RecordID.parse("invalid-format")
    # Handle the parsed record ID
except ValueError:
    print("Invalid RecordID format")