Value types
The Go SDK communicates with SurrealDB using CBOR (Concise Binary Object Representation) rather than JSON. The SDK provides Go types that map to SurrealDB’s data model and handle CBOR serialization transparently when used in structs or maps.
This page covers the mapping between SurrealDB types and Go types, and how to work with the most common value types.
API References
Type mapping
The following table shows how SurrealDB types map to Go types when using the SDK.
| SurrealQL type | Go type | CBOR tag |
|---|
null | nil | - |
none | models.CustomNil / models.None | 6 |
bool | bool | - |
int | int, int64, etc. | - |
float | float64 | - |
decimal | models.DecimalString | 10 |
string | string | - |
bytes | []byte | - |
datetime | models.CustomDateTime | 12 |
duration | models.CustomDuration | 14 |
uuid | models.UUID | 37 |
record | models.RecordID | 8 |
array | []any or typed slice | - |
object | map[string]any or struct | - |
geometry<point> | models.GeometryPoint | 88 |
geometry<line> | models.GeometryLine | 89 |
geometry<polygon> | models.GeometryPolygon | 90 |
geometry<multipoint> | models.GeometryMultiPoint | 91 |
geometry<multiline> | models.GeometryMultiLine | 92 |
geometry<multipolygon> | models.GeometryMultiPolygon | 93 |
geometry<collection> | models.GeometryCollection | 94 |
Working with record IDs
Use models.NewRecordID to construct a RecordID, or receive them from query results. The ID can be any CBOR-serializable value (string, integer, array, etc.).
import "github.com/surrealdb/surrealdb.go/pkg/models"
id := models.NewRecordID("persons", "tobie")
numericID := models.NewRecordID("events", 42)
To parse a record ID from a string like "persons:tobie", use ParseRecordID:
id, err := models.ParseRecordID("persons:tobie")
When defining structs for database records, use *models.RecordID for the ID field:
type Person struct {
ID *models.RecordID `json:"id,omitempty"`
Name string `json:"name"`
Surname string `json:"surname"`
}
Working with datetimes
CustomDateTime wraps Go’s time.Time and handles CBOR encoding with nanosecond precision.
now := models.CustomDateTime{Time: time.Now()}
You can use all standard time.Time methods directly on a CustomDateTime value, since it embeds time.Time.
Working with durations
CustomDuration wraps Go’s time.Duration with SurrealDB-compatible formatting (e.g., 1d2h30m).
dur := models.CustomDuration{Duration: 2*time.Hour + 30*time.Minute}
fmt.Println(dur.String())
Use CustomDurationString when you need the string representation directly, and call .ToCustomDuration() to convert back.
Working with geometry types
The SDK provides types for all SurrealDB geometry values. GeometryPoint is the most common:
point := models.GeometryPoint{Longitude: -0.118, Latitude: 51.509}
Other geometry types compose GeometryPoint:
line := models.GeometryLine{
{Longitude: -0.118, Latitude: 51.509},
{Longitude: -0.076, Latitude: 51.508},
}
polygon := models.GeometryPolygon{line}
Using None
SurrealDB distinguishes between null (SQL NULL) and none (absence of a value). Use models.None to represent the absence of a value:
surrealdb.Create[any](ctx, db, models.Table("test"), map[string]any{
"field": models.None,
})
Learn more
