Types Reference

This section provides comprehensive documentation for all field types supported by SOM. Each type includes its Go definition, SurrealDB schema, available filter operations, sorting capabilities, and practical examples.

Quick Reference

Type	Go Type	DB Schema	CBOR	Sortable	Filters
String	string	string	Direct	Yes	50+
Numeric	int, float64, etc.	int / float	Direct	Yes	20+
Bool	bool	bool	Direct	Yes	4
Byte	byte / []byte	int / bytes	Direct	Yes/No	8+
Time	time.Time	datetime	Tag 12	Yes	25+
Duration	time.Duration	duration	Tag 14	Yes	15+
UUID	uuid.UUID	uuid	Tag 37	Yes	8
URL	url.URL	string	Direct	Yes	15+
Email	som.Email	string	Direct	Yes	10+
Enum	Custom type	String union	Direct	Yes	8
Slice	[]T	array<T>	Direct	No	30+
Node	*OtherNode	record<table>	Direct	No	Via fields
Struct	Embedded struct	object	Direct	No	Via fields

Type Categories

Primitive Types

Basic Go types with direct database mapping:

• String - Text data with extensive string operations

• Numeric - Integers and floating-point numbers

• Bool - Boolean true/false values

• Byte - Single bytes and binary data

Time Types

Temporal data with special CBOR encoding:

• Time - Timestamps using time.Time

• Duration - Time intervals using time.Duration

Special Types

Types with validation or special handling:

• UUID - Universally unique identifiers

• URL - Web addresses with component parsing

• Email - Email addresses with validation

• Enum - Constrained string values

Complex Types

Composite and reference types:

• Slice - Arrays of any type

• Node - References to other records

• Struct - Nested object structures

Universal Operations

All types support these base filter operations:

// Equality
filter.User.Name.Equal("Alice")
filter.User.Name.NotEqual("Bob")

// Set membership
filter.User.Role.In("admin", "moderator")
filter.User.Status.NotIn("banned", "suspended")

// Zero value check
filter.User.Name.Zero(true)   // Is empty string
filter.User.Age.Zero(false)   // Is not zero

// Truthiness
filter.User.Name.Truth()      // Convert to bool filter

Pointer Types (Optional Fields)

All types support pointer variants for optional fields:

type User struct {
    som.Node

    Name     string   // Required
    Nickname *string  // Optional
}

Pointer types add nil-checking operations:

filter.User.Nickname.IsNil()     // Field is NULL/NONE
filter.User.Nickname.IsNotNil()  // Field has a value

CBOR Encoding

SOM uses CBOR (Concise Binary Object Representation) for efficient database communication. Most types use direct CBOR encoding, but some require special handling:

Type	CBOR Tag	Format
DateTime	12	[unix_seconds, nanoseconds]
Duration	14	[seconds, nanoseconds]
UUID	37	Binary (16 bytes)

Sorting

Most types support ascending and descending sort:

// Ascending
query.Order(by.User.Name.Asc())

// Descending
query.Order(by.User.CreatedAt.Desc())

// Multiple fields
query.Order(
    by.User.IsActive.Desc(),
    by.User.Name.Asc(),
)

Not sortable: Slice, Node, Struct (use nested field sorting instead)

Method Chaining

Many filter operations return new filters, enabling powerful chains:

// String transformations
filter.User.Email.Lowercase().Contains("@gmail")

// Numeric math
filter.Product.Price.Mul(1.1).LessThan(100)

// Time extraction
filter.Event.StartTime.Year().Equal(2024)

// Slice operations
filter.Post.Tags.Distinct().Len().GreaterThan(3)

Schema Generation

SOM generates SurrealDB schema definitions for each field:

DEFINE FIELD name ON user TYPE string;
DEFINE FIELD age ON user TYPE option<int>;
DEFINE FIELD email ON user TYPE string ASSERT string::is::email($value);
DEFINE FIELD role ON user TYPE "admin" | "user" | "guest";
DEFINE FIELD created_at ON user TYPE datetime VALUE $before OR time::now() READONLY;