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
Duration(duration: str | int | list[int, int])

Create a 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

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 I 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
Geometry.to_json()

Example
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
Geometry.is(geometry: Geometry)

Example
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
Geometry.clone()

Properties

.coordinates

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

Signature
Geometry.coordinates

Derivatives

GeometryPoint

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

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

GeometryLine

A line, made up of two or more points

Signature
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
GeometryPolygon([GeometryLine, ...])

GeometryMultiPoint

A collection of one or more points

Signature
GeometryMultiPoint([GeometryPoint, ...])

GeometryMultiLine

A collection of one or more lines

Signature
GeometryMultiLine([GeometryLine, ...])

GeometryMultiPolygon

A collection of one or more polygons

Signature
GeometryMultiPolygon([GeometryPolygon, ...])

GeometryCollection

A collection of one or more Geometry derivatives

Signature
GeometryCollection([Geometry, ...])

Table

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

Signature
Table(table: str)

Converting to string

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

Converting to JSON

A Table will be represented as a string in 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
RecordID(tb: str, id: Any)

Working with a RecordID

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

Extracting data
# Simple
rid = RecordID("person", "john")
rid.tb # "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
str(RecordID('table', 123))
# 'table:123'
str(RecordID('table', 'abc'))
# 'table:abc'

Complex characters
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
str(RecordID('table', { city: "London" }))
# 'table:{ city: "London" }'
str(RecordID('table', ["London"]))
# 'table:["London"]'