Swift API

The Swift 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 package Relate, from the repository github.com/relatedb/relate, for iOS 16 or later and macOS 13 or later in the Swift 6 language mode. It is a Swift layer over the relate C library, linked in as the static XCFramework RelateFFI, 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 and throws RelateError. This page describes the package of relate 0.1.2.

Synopsis

import Relate

public final class Database: @unchecked Sendable {
    public init(path: String) throws
    public init(readOnlyPath path: String) throws
    public static func inMemory() throws -> Database
    public let path: String
    public let isReadOnly: Bool
    public func connect() throws -> Connection
    public func connect(namespace: String?) throws -> Connection
    public func checkpoint() throws
}

public final class Connection {
    public let database: Database
    @discardableResult
    public func query(_ cypher: String, _ parameters: [String: CypherValue] = [:]) throws -> QueryResult
    public func setNamespace(_ name: String) throws
    public func begin() throws
    @discardableResult public func commit() throws -> String?
    public func rollback() throws
    @discardableResult public func transaction<T>(_ body: (Connection) throws -> T) throws -> T
}

Public types

Database

A Database closes its storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary when its last reference is released; there is no close(). Every Connection keeps its database, so the store outlives its connections. A failed open throws .engine 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 throws semantic error: DatabaseNotFound: Graph not found: <name>.

Connection

A Connection disconnects when it is released. Its own refusals, each .engine with code Neo.ClientError.Statement.SemanticError and GQLSTATUS 42000:

QueryResult

A QueryResult is a plain value, copied out of the engine before query returns.

A QueryResult has no column types. QueryStats has 11 Int properties: nodesCreated, nodesDeleted, relationshipsCreated, relationshipsDeleted, propertiesSet, labelsAdded, labelsRemoved, indexesAdded, indexesRemoved, constraintsAdded, constraintsRemoved. A bookmark's <n> grows across every connection of the store and orders as a number: as strings, "relate:10" sorts before "relate:9".

Values

Every cell, and every element of a list or map, is a CypherValue that keeps its kind at any depth:

Vector.DType has the cases .integer8, .integer16, .integer32, .integer, .float16, .bfloat16, .float32 and .float, whose raw values are the engine's names (INTEGER8 … FLOAT). UUIDs arrive as .string, byte arrays as a .list of .int. 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; the Int64 ids are the deprecated numeric ids id() returns. A value kind the package does not know throws .decoding.

Parameters

query(_:_:) binds each dictionary entry as one value. CypherValue conforms to ExpressibleByNilLiteral, …BooleanLiteral, …IntegerLiteral, …FloatLiteral, …StringLiteral, …ArrayLiteral and …DictionaryLiteral, so ["n": 1, "tags": ["a"], "m": ["k": true]] needs no wrapping. A variable binds through CypherValue(_:) for Int, Double, String and Bool; the struct payloads of the point, temporal, duration and vector cases have public initializers. Non-finite floats and every Int64 value bind directly.

Errors

error.message is the message of any case and error.engineError the EngineError of the .engine case, else nil.

A statement failure throws from query; a conflict in an explicit transaction throws from commit(). After a .internal failure the handle may be poisoned: later calls throw .internal too, and only a new handle recovers. A write on a read-only database throws code Neo.ClientError.Statement.SemanticError with GQLSTATUS 42N18. The errors reference lists the engine's messages.

Notifications and plans

Notification has the properties 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.

Concurrency

Platforms and linking

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 CypherValue kind of each returned value:

import Relate

let conn = try Database.inMemory().connect()
let result = try 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
    """)
for (column, value) in zip(result.columns, result.rows[0]) {
    print("\(column): \(value.kind) \(value)")
}

ada: node (4:relate-neo4j:n0:Person {name: 'Ada'})
k: relationship (4:relate-neo4j:n0)-[5:relate-neo4j:r0:KNOWS {since: 2024}]->(4:relate-neo4j:n1)
big: int 9007199254740993
ratio: float 1.5
day: date 2024-05-06
meeting: dateTime 2024-05-06T09:30:00+02:00[Europe/Berlin]
term: duration duration(months: 14, days: 0, seconds: 0, nanoseconds: 0)
spot: point point({srid: 7203, x: 1.0, y: 2.0})
counts: vector vector<INTEGER8>[1, 2, 3]

See also

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