Types
The Go SDK defines several types used by the client methods and data manipulation functions. These types are defined in the main surrealdb package and the pkg/connection package.
Package: github.com/surrealdb/surrealdb.go
Source: types.go
Authentication
Auth
Holds authentication credentials for signing in. The fields you populate determine the authentication level.
type Auth struct {
Namespace string `json:"NS,omitempty"`
Database string `json:"DB,omitempty"`
Scope string `json:"SC,omitempty"`
Access string `json:"AC,omitempty"`
Username string `json:"user,omitempty"`
Password string `json:"pass,omitempty"`
}
| Field | JSON key | When to use |
|---|
Namespace | NS | Namespace-level, database-level, or record-level signin |
Database | DB | Database-level or record-level signin |
Scope | SC | Legacy scope-based signin (SurrealDB v1.x) |
Access | AC | Record-level signin via a defined access method |
Username | user | All signin levels |
Password | pass | All signin levels |
You can also use map[string]any with the JSON keys directly, which allows passing additional fields required by access methods.
Tokens
Contains access and refresh tokens returned by .SignInWithRefresh() and .SignUpWithRefresh(). Only available with TYPE RECORD access methods that have WITH REFRESH enabled (SurrealDB v3+).
type Tokens struct {
Access string `cbor:"access"`
Refresh string `cbor:"refresh"`
}
| Field | Description |
|---|
Access | JWT token for authentication. Use with .Authenticate(). |
Refresh | Refresh token (format: surreal-refresh-...). Use with .SignInWithRefresh() to obtain new tokens. |
Query Results
QueryResult
Represents one statement’s result from a Query call. The type parameter T corresponds to the expected result type.
type QueryResult[T any] struct {
Status string `json:"status"`
Time string `json:"time"`
Result T `json:"result"`
Error *QueryError `json:"-"`
}
| Field | Description |
|---|
Status | "OK" for success, "ERR" for failure |
Time | Execution time for this statement |
Result | The typed result data |
Error | Non-nil when the statement failed. See QueryError. |
QueryStmt
Represents a single query statement for use with QueryRaw. After execution, the Result field is populated and .GetResult() can unmarshal it into a destination type.
type QueryStmt struct {
SQL string
Vars map[string]any
Result QueryResult[cbor.RawMessage]
}
Methods
.GetResult(dest any) error — unmarshals the raw result into dest
Data Types
PatchData
Represents a single JSON Patch operation for use with the Patch function.
type PatchData struct {
Op string `json:"op"`
Path string `json:"path"`
Value any `json:"value"`
}
Supported Op values: add, remove, replace, move, copy, test.
Relationship
Represents a graph edge between two records. Used with Relate and InsertRelation.
type Relationship struct {
ID *models.RecordID `json:"id"`
In models.RecordID `json:"in"`
Out models.RecordID `json:"out"`
Relation models.Table `json:"relation"`
Data map[string]any `json:"data"`
}
VersionData
Contains version information returned by .Version().
type VersionData struct {
Version string `json:"version"`
Build string `json:"build"`
Timestamp string `json:"timestamp"`
}
Notification
Represents a live query notification received through a notification channel.
Package: github.com/surrealdb/surrealdb.go/pkg/connection
type Notification struct {
ID *models.UUID `json:"id,omitempty"`
Action Action `json:"action"`
Result interface{} `json:"result"`
}
| Field | Type | Description |
|---|
ID | *models.UUID | The live query UUID |
Action | Action | One of CREATE, UPDATE, or DELETE |
Result | any | The record data or JSON Patch diff |
Type Constraints
TableOrRecord
A type constraint used by data manipulation functions. Accepts any of the following types:
type TableOrRecord interface {
string | models.Table | models.RecordID | []models.Table | []models.RecordID
}
See Table and RecordID for these value types.
sendable
A type constraint for types that can execute RPC requests. Satisfied by *DB, *Session, and *Transaction.
type sendable interface {
*DB | *Session | *Transaction
}
liveQueryable
A type constraint for types that support live queries. Satisfied by *DB and *Session (not *Transaction).
type liveQueryable interface {
*DB | *Session
}
See Also
