Protocols

Decodable protocol is used to specify how a FaunaDB value returned by the server is converted to other Swift data structures.

For example:

struct Point { let x, y: Int }

extension Point: Decodable {
    init?(value: Value) throws {
        try self.init(
            x: value.get("data", "position", "x") ?? 0
            y: value.get("data", "position", "y") ?? 0
    }
}

//...

let point: Point? = databaseValue.get()

Documentation describing data conversion can be found in the FaunaDB.Field struct.

See more

public protocol Decodable

Expr is the top level of the query language expression tree.

For convenience, some native types are considered valid expressions: String, Int, Double, Bool, Optional, and Date.

Reference

Motivation

The FaunaDB query language is a non-typed expression based language. You can think about it as an actual programming language.

In order to express an non-typed language in a typed language like Swift, we need to remove the types from the provided DSL so that we don’t restrict function composition with type constraints.

In practice, query language functions will always receive and return pure Expr types. That means you can compose your queries by combining functions together.

For example:

// Just return a reference to an user
client.query(
    Ref("classes/users/42")
)

// Combine Ref and Get to return the user entry
client.query(
    Get(
        Ref("classes/users/42")
    )
)

// Combine Ref, Get, and Select to return the user name
client.query(
    Select(
        path: "data", "name"
        from: Get(
            Ref("classes/users/42")
        )
    )
)

public protocol Expr

Encodable protocol is used to specify how a Swift data structure is converted to a valid FaunaDB value when sending data to the server.

For example:

struct Point { let x, y: Int }

extension Point: Encodable {
    func encode() -> Expr {
        return Obj(
            "x" => x,
            "y" => y
        )
    }
}

//...

client.query(
    Create(
        at: Class("points"),
        Obj("data" => Point(x: 10, y: 15))
    )
)

See more

public protocol Encodable: Expr

Represents a path segment to a field value. See FaunaDB.Field for more information.

public protocol Segment

Value is the top level of the value tree hierarchy. It represents a valid FaunaDB entry returned by the server.

Reference

Traversal API

You can use the traversal API to traverse and convert a database entry to an native type.

The traversal API uses type inference to convert the returned value to the desired type.

The traversal API methods are shortcuts for field extractors. See FaunaDB.Field for more information.

Examples of field extractions and type conversions:

// Attempts to convert the root value to a String
let name: String? = try! value.get()

// Transverses to the path "array" -> 1 -> "value" and
// attempts to convert its result to an Int
let count: Int? = try! value.get("array", 1, "count")

// Using a predefined field
let nameField = Field<String>("data", "name")
let name = try! value.get(field: nameField)

// Extracting an array
let tags1 = try! value
    .at("data")
    .get(asArrayOf: Field<String>())

let tags2: [String] = try! value.get("data")

// Extracting a dictionary
let nickNamesByName1 = try! value
    .at("data")
    .get(asDictionaryOf: Field<String>())

let nickNamesByName2: [String: String] =
    try! value.get("data")

// Extracting a struct that implements
// FaunaDB.Decodable
let blogPost: Post = try! value.get("data")!

See more

public protocol Value: Expr, CustomStringConvertible

Represents scalar values returned by the server. Reference.

See more

public protocol ScalarValue: Value, Equatable