Models | SurrealDB

Describe SurrealDB tables as PHP classes in Surqlize, using attributes for the table name, record id, casts, schema, and specialised fields.

A Surqlize model is a PHP class that maps to a SurrealDB table. It extends Surqlize\Model\Model, declares its table with the #[Table] attribute, and exposes the record's fields as typed properties.

use Surqlize\Attributes\Id;
use Surqlize\Attributes\Table;
use Surqlize\Model\Model;
use SurrealDB\SDK\Types\RecordId;

#[Table('user')]
final class User extends Model
{
    #[Id]
    public RecordId $id;

    public string $name;
    public int $age;
}

The property marked #[Id] holds the record's RecordId from the SDK. Property names map to SurrealDB field names directly, so a name property reads and writes the name field.

Attributes

Surqlize describes a model through attributes in the Surqlize\Attributes namespace.

Attribute	Target	Purpose
`#[Table('user')]`	class	Maps the model to a table
`#[Id]`	property	Marks the record id property (a `RecordId`)
`#[Cast(Address::class)]`	property	Hydrates a nested value as another model
`#[Schema(UserSchema::class)]`	class	Links the model to a schema definition
`#[Search(analyzer: 'english')]`	property	Marks a full-text search field
`#[Vector(dimension: 3)]`	property	Marks a vector field and its dimension
`#[Geometry]`	property	Marks a geometry field
`#[Edge('has_address', in: User::class, out: Address::class)]`	class	Defines a graph edge model

The #[Vector] attribute also accepts a distance (default cosine), #[Geometry] accepts a type (default geometry), and #[Search] accepts an optional analyzer.

Nested models

Use #[Cast] to hydrate an embedded object or a record link as another model. The nested class is itself a model.

use Surqlize\Attributes\Cast;
use Surqlize\Attributes\Table;
use Surqlize\Model\Model;

#[Table('address')]
final class Address extends Model
{
    public string $street;
    public int $number;
    public string $postcode;
}

#[Table('user')]
final class User extends Model
{
    #[Id]
    public RecordId $id;

    public string $name;

    #[Cast(Address::class)]
    public ?Address $address = null;
}

What a model gives you

Extending Model provides static query entry points and instance data operations.

Method	Purpose
`select()`	Start a `SELECT` with fields or a typed callback
`query()`	Start `SELECT *` for the table
`selectValue()`	Start a `SELECT VALUE` query
`fields()`	Resolve the model's typed field set
`relate()`	Start a model-first relation builder
`create()`, `createQuery()`, `upsert()`, `save()`, `delete()`	Persist a record
`all()`, `find()`, `findOrFail()`, `count()`, `exists()`, `refresh()`	Read or reload records
`toArray()`	Serialise the initialised properties to an array

These are covered in Querying and Mutations.

Learn more

Connections to register the executor models run through
Querying for the typed query builder
Schema to define tables and fields in the database