Go API

The Go clientclient A language package that runs the relate engine inside a program's process: the Python, Node.js, Rust, Java, Go and Swift clients. Read more in the glossary is the module github.com/relatedb/relate/clients/go, package relate, for Go 1.22 or later. It is cgo code over the relate C library, librelate_ffi, whose C application binary interface (C ABI) is version 2: values cross through the library's typed value walker and parameter builder, with no JSON. Every call is synchronous. This page lists the package's exported identifiers as go doc reports them for relate 0.1.2.

Synopsis

import relate "github.com/relatedb/relate/clients/go"

func Open(uri string) (*Database, error)
func OpenReadOnly(uri string) (*Database, error)

func (d *Database) Connect() (*Connection, error)
func (d *Database) ConnectNamespace(name string) (*Connection, error)
func (d *Database) Checkpoint() error
func (d *Database) Close()

func (c *Connection) Query(cypher string) (*Result, error)
func (c *Connection) QueryParams(cypher string, params map[string]any) (*Result, error)
func (c *Connection) SetNamespace(name string) error
func (c *Connection) Begin() error
func (c *Connection) Commit() (string, error)
func (c *Connection) Rollback() error
func (c *Connection) Close()

Exported identifiers

Database

A failed Open or OpenReadOnly returns a *Error with message internal error, code Neo.DatabaseError.General.UnknownError, GQLSTATUS 42000 and stage internal, whether the store is locked by another writer or missing. An unknown namespace returns semantic error: DatabaseNotFound: Graph not found: <name>.

Close on a *Database or a *Connection frees the native handle and keeps no closed state: a second Close, or any later call on the value, uses freed memory. The package sets no finalizers, so a handle never closed keeps its store open, and a .rl store locked, until the process exits.

Connection

A statement failure returns a nil *Result and the *Error. A connection's own refusals, each with code Neo.ClientError.Statement.SemanticError and GQLSTATUS 42000:

The package holds no lock. A *Database may be shared between goroutines; calls that share a *Connection are serialized by the caller, one at a time, and distinct connections may run concurrently.

Result

A Result has no column types or timings. A bookmark's <n> grows across every connection of the store and orders as a number: as strings, "relate:10" sorts before "relate:9".

Stats has 11 int64 fields, always present: NodesCreated, NodesDeleted, RelationshipsCreated, RelationshipsDeleted, PropertiesSet, LabelsAdded, LabelsRemoved, IndexesAdded, IndexesRemoved, ConstraintsAdded, ConstraintsRemoved. The counting follows Neo4j: one label per node it is added to, one property per write, and schema statements in the index and constraint counters.

Values

Each result cell decodes to one Go type per Cypher kind:

A zoned value reports its local wall clock. An element idelement id The string elementId() returns for a node or relationship, such as 4:relate-neo4j:n0; it stays the same when the store is closed and opened again. Read more in the glossary is the string elementId() returns, such as 4:relate-neo4j:n0, and is "" in the system namespace. The ID fields are the deprecated numeric ids id() returns. A value kind the client does not know is an error, never nil.

Parameters

QueryParams binds each map entry as one Cypher value:

The package's own value types are structs, so they bind as maps of their fields; a temporal, point or vector parameter is built in the statement from its parts, as date($day) or vector($v, 3, FLOAT32). A value the builder refuses fails before the statement runs, as a plain error prefixed parameter "<name>": :

A nested value adds its position (item <n>, field "<name>", key "<name>"). A name holding a NUL byte fails with parameter "<name>" holds an interior NUL and cannot cross the C boundary, and a statement holding one with statement holds an interior NUL and cannot cross the C boundary.

Errors

Every failure the engine or the C boundary reports is a *Error, from a statement's result or from the call's own error channel; errors.As(err, &e) with var e *relate.Error matches it. The client's own refusals are plain error values: the parameter refusals, ABI contract violated: … for a result that breaks the C contract, and unsupported value kind <n>. A write on a read-only database returns code Neo.ClientError.Statement.SemanticError and GQLSTATUS 42N18. The errors reference lists the engine's messages.

Notifications and plans

Notification has the fields Code, GQLStatus, Severity (INFORMATION or WARNING), Category (PERFORMANCE, UNRECOGNIZED, DEPRECATION, SCHEMA or HINT), Title, Description, Remedy and OperatorID, an *int64 that is nil on a statement-scoped notification.

Linking

The package's cgo directives include relate.h and link -lrelate_ffi, searching the surfaces/relate-ffi/include, target/debug and target/release directories of the relate source repository. Outside that repository the build reads cgo's environment:

Each release attaches relate-ffi-<target>.tar.gz, holding the shared library, the static library, and the header. On Windows, cgo links with MinGW, which needs an import library generated from relate_ffi.dll with gendef and dlltool.

Limits

The limits come from the engine and are the same on every surface: a statement's text is at most 4194304 bytes (syntax error: query text of <n> bytes exceeds the maximum query size of 4194304 bytes), one value a statement builds is bounded by the expression memory cap, and a file-backed store has one writing open across every process. Limits and sizing lists each limit with its default and the setting that changes it.

Capabilities

Example

This program writes two Person nodes and a KNOWS relationship to an in-memory store and prints the Go type of each returned value:

package main

import (
	"fmt"
	"log"

	relate "github.com/relatedb/relate/clients/go"
)

func main() {
	db, err := relate.Open(":memory:")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()
	conn, err := db.Connect()
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	res, err := conn.Query(`
		CREATE (ada:Person {name: 'Ada'})-[k:KNOWS {since: 2024}]->(grace:Person {name: 'Grace'})
		RETURN ada, k, 9007199254740993 AS big, 1.5 AS ratio, date('2024-05-06') AS day,
		       datetime('2024-05-06T09:30:00[Europe/Berlin]') AS meeting, duration('P1Y2M') AS term,
		       point({x: 1, y: 2}) AS spot, vector([1, 2, 3], 3, INT8) AS counts`)
	if err != nil {
		log.Fatal(err)
	}
	for i, col := range res.Columns {
		fmt.Printf("%s: %T %+v\n", col, res.Rows[0][i], res.Rows[0][i])
	}
}

ada: relate.Node {ElementID:4:relate-neo4j:n0 ID:0 Labels:[Person] Properties:map[name:Ada]}
k: relate.Relationship {ElementID:5:relate-neo4j:r0 StartElementID:4:relate-neo4j:n0 EndElementID:4:relate-neo4j:n1 ID:0 StartID:0 EndID:1 Type:KNOWS Properties:map[since:2024]}
big: int64 9007199254740993
ratio: float64 1.5
day: relate.Date {Year:2024 Month:5 Day:6}
meeting: relate.DateTime {Year:2024 Month:5 Day:6 Hour:9 Minute:30 Second:0 Nanosecond:0 OffsetSeconds:7200 Zone:Europe/Berlin}
term: relate.Duration {Months:14 Days:0 Seconds:0 Nanos:0}
spot: relate.Point {SRID:7203 Dimension:2 X:1 Y:2 Z:0}
counts: relate.Vector {DType:INTEGER8 Ints:[1 2 3] Floats:[]}

See also

• Use the Go client: linking, open modes, parameters, transactions and errors, task by task.
• Embed relate in a Go app: the first program, step by step.
• API reference: every surface and the capability matrix.
• C ABI: the library and header this client links.
• Errors: every engine message with its codes.
• Embedded graph in an app: the problem the clients solve.