githubEdit

Time

The time type handles timestamps using Go's time.Time with special CBOR encoding for nanosecond precision.

Overview

Property
Value

Go Type

time.Time / *time.Time

Database Schema

datetime / option<datetime>

CBOR Encoding

Tag 12 with [unix_seconds, nanoseconds]

Sortable

Yes

CBOR Encoding

Time values are encoded with CBOR Tag 12 as a two-element array:

Tag 12: [unix_seconds (int64), nanoseconds (int64)]

This provides:

  • Full nanosecond precision

  • Proper round-tripping with SurrealDB

  • Handling of empty arrays for optional fields

Definition

type Event struct {
    som.Node

    StartTime   time.Time   // Required
    EndTime     time.Time   // Required
    CancelledAt *time.Time  // Optional
}

Automatic Timestamps

Use som.Timestamps for automatic tracking:

  • CreatedAt - Set automatically on create, readonly

  • UpdatedAt - Updated automatically on every save

Schema

Generated SurrealDB schema:

Filter Operations

Equality Operations

Set Membership

Comparison Operations

Time provides intuitive comparison aliases:

Arithmetic Operations

Component Extraction

Extract individual time components as numeric filters:

Grouping

Group times by unit:

Rounding Operations

Formatting

Format time as string for comparison:

Validation

Nil Operations (Pointer Types Only)

Zero Value Check

Sorting

Method Chaining

Time filters support powerful chaining:

Common Patterns

Date Range Queries

Recent Records

Upcoming Events

Complete Example

Filter Reference Table

Operation
Description
Returns

Equal(val)

Exact match

Bool filter

NotEqual(val)

Not equal

Bool filter

In(vals...)

Value in set

Bool filter

NotIn(vals...)

Value not in set

Bool filter

Before(val)

Before time

Bool filter

BeforeOrEqual(val)

Before or equal

Bool filter

After(val)

After time

Bool filter

AfterOrEqual(val)

After or equal

Bool filter

LessThan(val)

Same as Before

Bool filter

LessThanEqual(val)

Same as BeforeOrEqual

Bool filter

GreaterThan(val)

Same as After

Bool filter

GreaterThanEqual(val)

Same as AfterOrEqual

Bool filter

Add(duration)

Add duration

Time filter

Sub(duration)

Subtract duration

Time filter

Year()

Extract year

Numeric filter

Month()

Extract month (1-12)

Numeric filter

Day()

Extract day (1-31)

Numeric filter

Hour()

Extract hour (0-23)

Numeric filter

Minute()

Extract minute (0-59)

Numeric filter

Second()

Extract second (0-59)

Numeric filter

Nano()

Extract nanoseconds

Numeric filter

Micros()

Microseconds since epoch

Numeric filter

Millis()

Milliseconds since epoch

Numeric filter

Unix()

Unix timestamp

Numeric filter

Weekday()

Day of week (0-6)

Numeric filter

Week()

Week of year (1-53)

Numeric filter

YearDay()

Day of year (1-366)

Numeric filter

Group(unit)

Group by time unit

Time filter

Floor(duration)

Floor to duration

Time filter

Round(duration)

Round to duration

Time filter

Format(fmt)

Format as string

String filter

IsLeapYear()

Check leap year

Bool filter

Zero(bool)

Check zero time

Bool filter

Truth()

To boolean

Bool filter

IsNil()

Is null (ptr)

Bool filter

IsNotNil()

Not null (ptr)

Bool filter

Last updated