Data types | SurrealDB

How version 2 of the PHP SDK maps SurrealQL data types to native PHP types and custom value classes.

SurrealDB has types that PHP does not, such as record IDs, nanosecond datetimes, durations, and arbitrary-precision decimals. Version 2 of the SDK represents these with value classes in the SurrealDB\SDK\Types namespace. Native PHP types pass through unchanged.

Type mapping

SurrealQL type	PHP type
`bool`	`bool`
`int`, `float`	`int`, `float`
`string`	`string`
`null`	`null`
`none`	`None`
`array`	`array` (list)
`object`	`array` (associative)
`set`	`Set`
`bytes`	`Bytes`
`datetime`	`DateTime`
`duration`	`Duration`
`decimal`	`Decimal`
`uuid`	`Uuid`
`record`	`RecordId`
`range`	`Range`
`geometry`	`Geometry` types
`file`	`File`

Record IDs and tables

A RecordId is a table name plus an ID. A Table is a table reference on its own. The query builders accept either, so the SDK can tell a record from a table.

use SurrealDB\SDK\Types\RecordId;
use SurrealDB\SDK\Types\Table;

$tobie = new RecordId('person', 'tobie');
$people = new Table('person');

$record = $db->select($tobie)->execute();
$all = $db->select($people)->execute();

The ID can be a string, integer, array, or object for composite keys.

$metric = new RecordId('metric', ['service' => 'api', 'host' => 'server-01']);

To send a record ID that is already a string, wrap it in StringRecordId so the server parses it.

use SurrealDB\SDK\Types\StringRecordId;

$db->select(new StringRecordId('person:tobie'))->execute();

Datetimes and durations

A DateTime keeps nanosecond precision, which PHP's native DateTime does not. A Duration follows SurrealQL duration syntax.

use SurrealDB\SDK\Types\DateTime;
use SurrealDB\SDK\Types\Duration;

$now = DateTime::now();
$parsed = DateTime::fromString('2024-01-15T12:00:00.123456789Z');

$ttl = Duration::fromString('1h30m');

Decimals

A Decimal holds a number without floating-point rounding. Construct it from a string when precision matters.

use SurrealDB\SDK\Types\Decimal;

$price = new Decimal('19.99');

UUIDs

A Uuid represents a universally unique identifier, with helpers for v4 (random) and v7 (time-ordered).

use SurrealDB\SDK\Types\Uuid;

$random = Uuid::v4();
$timeOrdered = Uuid::v7();

Geometries

The SDK provides classes for every GeoJSON geometry type: GeometryPoint, GeometryLine, GeometryPolygon, GeometryMultiPoint, GeometryMultiLine, GeometryMultiPolygon, and GeometryCollection.

use SurrealDB\SDK\Types\GeometryPoint;
use SurrealDB\SDK\Types\GeometryLine;

$point = new GeometryPoint(-0.118092, 51.509865);
$line = new GeometryLine(
    new GeometryPoint(0, 0),
    new GeometryPoint(1, 1),
);

Learn more

Data types API reference for every value class and its methods
SurrealQL data model for the database type system