This SDK facilitates communication between client and the backend service using the Concise Binary Object Representation (CBOR) format. It streamlines data serialization and deserialization while ensuring efficient and lightweight communication. The library also provides custom models tailored to specific Data models recognised by SurrealDb, which cannot be covered by idiomatic Go, enabling seamless interaction between the client and the backend.
CBOR Type | Go Representation | Example |
---|---|---|
Null | nil | var x interface{} = nil |
None | surrealdb.None | map[string]interface{}{"customer": surrealdb.None} |
Boolean | bool | true , false |
Array | []interface{} | []MyStruct{item1, item2} |
Date/Time | time.Time | time.Now() |
Duration | time.Duration | time.Duration(8821356) |
UUID (string representation) | surrealdb.UUID(string) | surrealdb.UUID("123e4567-e89b-12d3-a456-426614174000") |
UUID (binary representation) | surrealdb.UUIDBin([]bytes) | surrealdb.UUIDBin([]byte{0x01, 0x02, ...} )` |
Integer | uint , uint64 , int , int64 | 42 , uint64(100000) , -42 , int64(-100000) |
Floating Point | float32 , float64 | 3.14 , float64(2.71828) |
Byte String, Binary Encoded Data | []byte | []byte{0x01, 0x02} |
Text String | string | "Hello, World!" |
Map | map[interface{}]interface{} | map[string]float64{"one": 1.0} |
Table name | surrealdb.Table(name) | surrealdb.Table("users") |
Record ID | surrealdb.RecordID{Table: string, ID: interface{}} | surrealdb.RecordID{Table: "customers", ID: 1}, surrealdb.NewRecordID("customers", 1) |
Geometry Point | surrealdb.GeometryPoint{Latitude: float64, Longitude: float64} | surrealdb.GeometryPoint{Latitude: 11.11, Longitude: 22.22 |
Geometry Line | surrealdb.GeometryLine{GeometricPoint1, GeometricPoint2,... } | |
Geometry Polygon | surrealdb.GeometryPolygon{GeometryLine1, GeometryLine2,... } | |
Geometry Multipoint | surrealdb.GeometryMultiPoint{GeometryPoint1, GeometryPoint2,... } | |
Geometry MultiLine | surrealdb.GeometryMultiLine{GeometryLine1, GeometryLine2,... } | |
Geometry MultiPolygon | surrealdb.GeometryMultiPolygon{GeometryPolygon1, GeometryPolygon2,... } | |
Geometry Collection | surrealdb.GeometryMultiPolygon{GeometryPolygon1, GeometryLine2, GeometryPoint3, GeometryMultiPoint4,... } |
The SDK uses CBOR for all client-server serialization. It does not use encoding/json
, and MarshalJSON
is not part of the serialization path.
pkg/models/cbor.go
surrealcbor/
Both implementations are supported; choose the one that fits your needs/performance characteristics.
For some methods like create, insert, update, you can pass a map instead of an struct value. An example:
person, err := surrealdb.Create[Person](db, models.Table("persons"), map[interface{}]interface{}{ "Name": "John", "Surname": "Doe", "Location": models.NewGeometryPoint(-0.11, 22.00), })
This can be simplified to:
person, err := surrealdb.Create[Person](db, models.Table("persons"), surrealdb.O{ "Name": "John", "Surname": "Doe", "Location": models.NewGeometryPoint(-0.11, 22.00), })
Where surrealdb.O is defined below. There is no special advantage in using this other than simplicity/legibility.
type surrealdb.O map[interface{}]interface{}
Note
models.GeometryPoint
takes the latitude and the longtitude in an order that conflicts with SurrealDB. Based on GeoJSON, SurrealDB assumes the longtitude appear earlier, whilemodels.GeometryPoint
takes the latitude earlier. TThe function should be changed to take the longtitude earlier. Related issue: #223
This is useful for the Send
function where T
is the expected response type for a request. An example:
var res surrealdb.Result[[]Users] err := db.Send(&res, "select", model.Table("users")) if err != nil { panic(err) } fmt.Printf("users: %+v\n", users.R)