Field

const Field: object

Defined in: define/field/index.ts:91

A factory object for creating field definitions for table schemas.

Type Declaration

any()

any(options): FieldDefinition<any>

Defines an any field, which can store any data type.

Parameters

options

FieldOptions = {}

Options for the any field.

Returns

FieldDefinition<any>

Example

flexibleData: Field.any()

array()

array<TElementDef>(element, options): FieldDefinition<InferFieldType<TElementDef>[]>

Defines an array field.

Type Parameters

TElementDef

TElementDef extends FieldDefinition<unknown>

Parameters

element

TElementDef

The field definition for the elements within the array.

options

ArrayFieldOptions<InferFieldType<TElementDef>> = {}

Options for the array field, such as max size.

Returns

FieldDefinition<InferFieldType<TElementDef>[]>

Example

// An array of strings
tags: Field.array(Field.string()),

// An array of objects
items: Field.array(Field.object({
  name: Field.string(),
  quantity: Field.number(),
}))

bool()

bool(options): FieldDefinition<boolean>

Defines a boolean field.

Parameters

options

FieldOptions = {}

Standard field options.

Returns

FieldDefinition<boolean>

Example

Field.bool({ default: false })

bytes()

bytes(options): FieldDefinition<ArrayBuffer>

Defines a bytes field for storing binary data.

Parameters

options

FieldOptions = {}

Options for the bytes field.

Returns

FieldDefinition<ArrayBuffer>

Example

avatar: Field.bytes()

custom()

custom<T>(typeString, options): FieldDefinition<T>

Defines a custom field type using a specific SurrealDB type string. This is useful for types not built-in to the ORM, like duration or geometry.

Type Parameters

T

T

Parameters

typeString

string

The SurrealQL type string (e.g., ‘duration’, ‘geometry’).

options

CustomFieldOptions = {}

Standard field options.

Returns

FieldDefinition<T>

Example

Field.custom<number>('duration')

datetime()

datetime(options): FieldDefinition<Date>

Defines a datetime field.

Parameters

options

FieldOptions = {}

Standard field options.

Returns

FieldDefinition<Date>

Example

Field.datetime({ default: surql`time::now()` })

decimal()

decimal(options): FieldDefinition<Decimal>

Defines a decimal field for high-precision numbers.

Parameters

options

FieldOptions = {}

Options for the decimal field.

Returns

FieldDefinition<Decimal>

Example

balance: Field.decimal()

duration()

duration(options): FieldDefinition<Duration>

Defines a duration field for storing time durations.

Parameters

options

FieldOptions = {}

Options for the duration field.

Returns

FieldDefinition<Duration>

Example

ttl: Field.duration()

float()

float(options): FieldDefinition<number>

Defines a float field for floating-point numbers.

Parameters

options

FieldOptions = {}

Options for the float field.

Returns

FieldDefinition<number>

Example

rating: Field.float()

geometry()

geometry<T>(type, options): FieldDefinition<GeometryTypeMap[T]>

Defines a geometry field for storing GeoJSON data.

Type Parameters

T

T extends GeometryType

Parameters

type

T

The specific geometry type.

options

FieldOptions = {}

Options for the geometry field.

Returns

FieldDefinition<GeometryTypeMap[T]>

Example

// A single point
location: Field.geometry('point'),

int()

int(options): FieldDefinition<number>

Defines an int field for integers.

Parameters

options

FieldOptions = {}

Options for the int field.

Returns

FieldDefinition<number>

Example

views: Field.int()

number()

number(options): FieldDefinition<number>

Defines a number field (integer or float).

Parameters

options

FieldOptions = {}

Standard field options.

Returns

FieldDefinition<number>

Example

Field.number({ default: 0 })

object()

object<TSchema>(schema, options): FieldDefinition<InferShapeFromFields<TSchema>>

Defines an object field with a nested schema.

Type Parameters

TSchema

TSchema extends Record<string, FieldDefinition<unknown>>

Parameters

schema

TSchema

An object defining the shape of the nested object.

options

ObjectFieldOptions = {}

Options for the object field, such as flexible.

Returns

FieldDefinition<InferShapeFromFields<TSchema>>

Example

meta: Field.object({
  views: Field.number(),
  lastVisited: Field.datetime(),
})

option()

option<FD>(fieldDefinition): FieldDefinition<InferFieldType<FD> | undefined>

Makes a field optional. In SurrealDB, fields are required by default. Wrapping a field definition with option() makes it optional.

Type Parameters

FD

FD extends FieldDefinition<unknown>

Parameters

fieldDefinition

FD

The field definition to make optional.

Returns

FieldDefinition<InferFieldType<FD> | undefined>

Example

bio: Field.option(Field.string())

record()

record<TModel>(tableClassThunk, options): FieldDefinition<InstanceType<TModel> | RecordId<TModel["_tableName"]>>

Defines a record field, which creates a standard Record Link to a record in another table. This stores a RecordId (a pointer). It does NOT use the experimental REFERENCE feature and does not provide automatic referential integrity. If the linked record is deleted, this field will hold a dangling reference.

Type Parameters

TModel

TModel extends AnyModelClass

Parameters

tableClassThunk

() => TModel

A thunk () => ModelClass returning the model being referenced. This is required to prevent circular dependencies.

options

RecordFieldOptions = {}

Options for the record field.

Returns

FieldDefinition<InstanceType<TModel> | RecordId<TModel["_tableName"]>>

Example

// Creates a link to a User record.
author: Field.record(() => User)

set()

set<TElementDef>(element, options): FieldDefinition<Set<InferFieldType<TElementDef>>>

Defines a set field, which is a collection of unique values.

Type Parameters

TElementDef

TElementDef extends FieldDefinition<unknown>

Parameters

element

TElementDef

The field definition for the elements within the set.

options

ArrayFieldOptions<InferFieldType<TElementDef>> = {}

Options for the set field.

Returns

FieldDefinition<Set<InferFieldType<TElementDef>>>

Example

// A set of unique tags
tags: Field.set(Field.string())

string()

string(options): FieldDefinition<string>

Defines a string field.

Parameters

options

FieldOptions = {}

Standard field options.

Returns

FieldDefinition<string>

Example

Field.string({ assert: surql`$value.length > 0` })

uuid()

uuid(options): FieldDefinition<Uuid>

Defines a uuid field.

Parameters

options

FieldOptions = {}

Options for the uuid field.

Returns

FieldDefinition<Uuid>

Example

uniqueId: Field.uuid()