01 Documentation

Languages:

Introduction

Modern applications no longer interact exclusively with tabular or relational data. Adaptability requires supporting multiple data structures within the same system. With this requirement in mind, FaunaDB implements an inheritance-free object-relational data model, a strict superset of the relational, document, object-oriented, and graph paradigms:

  • Records are inserted as structured documents called instances, which can include recursively nested objects and arrays as well as scalar types.
  • Instances are grouped into classes, which are similar to tables in a relational database. However, like a document database, full or partially shared schema within a class is optional, not mandatory.
  • Classes are grouped into databases. Like filesystem directories, databases can recursively contain other databases.
  • Database access is controlled by keys. Keys are credentials that identify the application requesting access and close over a specific database context. They can be assigned priorities and access control roles.
  • Queries can be supported by views built using indexes. An index is a transformation of a set of input instances into one or more result sets composed of terms and values. Indexes are can transform, cover, and order instance data, and enforce unique constraints. Indexes must be referenced explicitly in query expressions; to avoid performance discontinuities, the optimizer does not make index application decisions on behalf of the developer.
  • Queries can be parameterized as functions, similar to stored procedures in a SQL system, in order to share logic across applications, abstract logic from applications that are difficult to upgrade in place, or create custom security models.

Instances

Each record in a FaunaDB database is stored as an object. All objects are instances of a specific class. This includes configuration as well as user data: Databases, keys, user-defined classes, and indexes are all instances of their respective schema classes.

Every instance has an identifier called a ref. An instance’s ref encodes its class along with a unique id, and is therefore unique to that instance within the scope of the database in which it is stored.

Fields

Every instance has a set of common fields in addition to any other fields it contains. These common fields are:

Field Type
ref Ref The instance’s identifier. Unique within a database.
class Ref The ref of the instance’s class.
ts Integer The instance’s last updated time. Microsecond UNIX timestamp.

Security

Reading or writing instances of user-defined classes requires a server key, or an instance token with appropriate permissions. Read more about instance level access control here.

Databases

Databases are defined as instances of the databases class. Databases exist within the system-global root database context.

Aside from keys, all other instances exist within the context of a specific database. All queries are limited to a single database as well, and cannot span across databases.

It is possible to rename a database by updating its name field. Renaming a database changes its ref, but preserves inbound references to the database. The data within a database remains accessible via existing keys.

When a database is deleted, its associated data becomes inaccessible, and is deleted asynchronously.

Fields

Name Type
name String Cannot be events, sets, self, instances, or _.
api_version String The default API version for requests made to this database. Defaults to “2.0”.
priority Number A priority between 1 and 500, inclusive. Defaults to 1.
data Object A JSON object. Optional.

Security

Reading or writing databases requires an admin key.

Examples

Create a Database


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "create_database": { "object": { "name": "annuvin" } } }'

FaunaClient adminClient = FaunaClient.builder()
  .withSecret(adminKey)
  .build();

adminClient.query(CreateDatabase(Obj("name", Value("annuvin"))));

var adminClient = new faunadb.Client({
  secret: adminKey
});

adminClient.query(q.CreateDatabase({ name: "annuvin" }));

val adminClient = FaunaClient(secret = adminKey)

adminClient.query(CreateDatabase(Obj("name" -> "annuvin")))

$admin_client = Fauna::Client.new(secret: adminKey)

$admin_client.query do
  create_database name: 'annuvin'
end

var adminClient = new FaunaClient(secret: adminKey);

adminClient.Query(CreateDatabase(Obj("name", "annuvin")));

adminClient = FaunaClient(secret=adminKey)

adminClient.query(q.create_database({"name": "annuvin"}))

adminClient = f.NewFaunaClient(adminKey)

adminClient.Query(f.CreateDatabase(f.Obj{"name": "annuvin"}))

let adminClient = FaunaDB.Client(secret: adminKey)

adminClient.query(CreateDatabase(Obj("name" => "annuvin")))

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "databases/annuvin" },
    "class": { "@ref": "databases" },
    "ts": 1436375112141542,
    "name": "annuvin"
  }
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

Get a Database


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "get": { "database": "annuvin" } }'

adminClient.query(Get(Database(Value("annuvin"))));

adminClient.query(q.Get(q.Database("annuvin")));

adminClient.query(Get(Database("annuvin")))

$admin_client.query do
  get database('annuvin')
end

adminClient.Query(Get(Database("annuvin")));

adminClient.query(q.get(q.database("annuvin")))

adminClient.Query(f.Get(f.Database("annuvin")))

adminClient.query(Get(Database("annuvin")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "databases/annuvin" },
    "class": { "@ref": "databases" },
    "ts": 1436375112141542,
    "name": "annuvin"
  }
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

=> {
  "ref": { "@ref": "databases/annuvin" },
  "class": { "@ref": "databases" },
  "ts": 1436375112141542,
  "name": "annuvin"
}

Paginate All Databases


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "paginate": { "@ref": "databases" } }'

adminClient.query(Paginate(Ref("databases")));

adminClient.query(q.Paginate(Ref("databases")));

adminClient.query(Paginate(Ref("databases")))

$admin_client.query do
  paginate ref('databases')
end

adminClient.Query(Paginate(Ref("databases")));

adminClient.query(q.paginate(Ref("databases")))

adminClient.Query(f.Paginate(f.Ref("databases")))

adminClient.query(Paginate(Ref("databases")))

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "databases/prydain" },
      { "@ref": "databases/caledonia" },
      { "@ref": "databases/annuvin" }
    ]
  }
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

=> {
  "data": [
    { "@ref": "databases/prydain" },
    { "@ref": "databases/caledonia" },
    { "@ref": "databases/annuvin" }
  ]
}

Rename a Database


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{
          "update": { "database": "annuvin" },
          "params": { "object": { "name": "llyr" } }
        }'

adminClient.query(
  Update(Database(Value("annuvin")), Obj("name", Value("llyr"))));

adminClient.query(
  q.Update(q.Database("annuvin"), { name: "llyr" }));

adminClient.query(
  Update(Database("annuvin"), Obj("name" -> "llyr")))

$admin_client.query do
  update database('annuvin'), name: 'llyr'
end

adminClient.Query(
  Update(Database("annuvin"), Obj("name", "llyr")));

adminClient.query(
  q.update(q.database("annuvin"), {"name": "llyr"}))

adminClient.Query(
    f.Update(f.Database("annuvin"), f.Obj{"name": "llyr"}),
)

adminClient.query(
    Update(
        ref: Database("annuvin"),
        to: Obj("name" => "llyr")
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "databases/llyr" },
    "class": { "@ref": "databases" },
    "ts": 1436375112199704,
    "name": "llyr"
  }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112199704,
  "name": "llyr"
}

Annotate a Database


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{
          "update": { "database": "llyr" },
          "params": { "object": { "data": { "object": { "env": "test" } } } }
        }'

adminClient.query(
  Update(
    Database(Value("llyr")),
    Obj("data", Obj("env", Value("test")))));

adminClient.query(
  q.Update(q.Database("llyr"), { data: { env: "test" } }));

adminClient.query(
  Update(Database("llyr"), Obj("data" -> Obj("env" -> "test"))))

$admin_client.query do
  update database('llyr'), data: { env: 'test' }
end

adminClient.Query(
  Update(Database("llyr"), Obj("data", Obj("env", "test"))));

adminClient.query(
  q.update(q.database("llyr"), {"data": {"env": "test"}}))

adminClient.Query(
    f.Update(
        f.Database("llyr"),
        f.Obj{"data": f.Obj{"env": "test"}},
    ),
)

adminClient.query(
    Update(
        ref: Database("llyr"),
        to: Obj("data" => Obj("env" => "test"))
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "databases/llyr" },
    "class": { "@ref": "databases" },
    "ts": 1436375112257866,
    "name": "llyr",
    "data": { "env": "test" }
  }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

Delete a Database


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "delete": { "database": "llyr" } }'

adminClient.query(Delete(Database(Value("llyr"))));

adminClient.query(q.Delete(q.Database("llyr")));

adminClient.query(Delete(Database("llyr")))

$admin_client.query do
  delete database('llyr')
end

adminClient.Query(Delete(Database("llyr")));

adminClient.query(q.delete(q.database("llyr")))

adminClient.Query(f.Delete(f.Database("llyr")))

adminClient.query(Delete(ref: Database("llyr")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "databases/llyr" },
    "class": { "@ref": "databases" },
    "ts": 1436375112257866,
    "name": "llyr",
    "data": { "env": "test" }
  }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

=> {
  "ref": { "@ref": "databases/llyr" },
  "class": { "@ref": "databases" },
  "ts": 1436375112257866,
  "name": "llyr",
  "data": { "env": "test" }
}

Keys

Keys are defined as instances of the keys class. Like databases, keys exist within the system-global root database context.

Keys are tied to a specific database, and allow access to its contents. The level of access a key provides depends on its role.

For an overview of FaunaDB’s authentication and permissions systems, start with Authenticating Requests.

You must copy the key’s secret out of the key when it is first created, and store it securely. Only a BCrypt hash of the key is stored on disk. It is impossible to recover the key’s secret if it is discarded.

Fields

Name Type
database Database ref The database associated with this key.
role String The key’s role. Either admin, server, server-readonly or client.
secret String The key’s authentication secret. Only present on creation.
hashed_secret String The key’s hashed authentication secret.
priority Number A priority between 1 and 500, inclusive. Defaults to 1.
data Object A JSON object. Optional.

Security

Reading or writing keys requires an admin key.

Examples

Create a Key


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{
          "create_key": {
            "object": {
              "database": { "database": "caledonia" },
              "role": "server"
            }
          }
        }'

FaunaClient adminClient = FaunaClient.builder()
  .withSecret(adminKey)
  .build();

adminClient.query(
  CreateKey(
    Obj(
      "database", Database(Value("caledonia")),
      "role", Value("server")
    )));

var adminClient = new faunadb.Client({
  secret: adminKey
});

adminClient.query(
  q.CreateKey(
    { database: q.Database("caledonia"), role: "server" }));

val adminClient = FaunaClient(secret = adminKey)

adminClient.query(
  CreateKey(
    Obj("database" -> Database("caledonia"), "role" -> "server")))

$admin_client = Fauna::Client.new(secret: adminKey)

$admin_client.query do
  create_key database: database('caledonia'), role: 'server'
end

var adminClient = new FaunaClient(secret: adminKey);

adminClient.Query(
  CreateKey(
    Obj("database", Database("caledonia"), "role", "server")));

adminClient = FaunaClient(secret=adminKey)

adminClient.query(
  q.create_key(
    {"database": q.database("caledonia"), "role": "server"}
  ))

adminClient = f.NewFaunaClient(adminKey)

adminClient.Query(
    f.CreateKey(
        f.Obj{"database": f.Database("caledonia"), "role": "server"},
    ),
)

let adminClient = FaunaDB.Client(secret: adminKey)

adminClient.query(
    CreateKey(
        Obj(
            "database" => Database("caledonia"),
            "role" => "server"
        )
    )
)

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "keys/104979509692858368" },
    "class": { "@ref": "keys" },
    "ts": 1436375112374190,
    "database": { "@ref": "databases/caledonia" },
    "role": "server",
    "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
    "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
  }
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "secret": "kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

Get a Key


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "get": { "@ref": "keys/104979509692858368" } }'

adminClient.query(Get(Ref("keys/104979509692858368")));

adminClient.query(q.Get(Ref("keys/104979509692858368")));

adminClient.query(Get(Ref("keys/104979509692858368")))

$admin_client.query do
  get ref('keys/104979509692858368')
end

adminClient.Query(Get(Ref("keys/104979509692858368")));

adminClient.query(q.get(Ref("keys/104979509692858368")))

adminClient.Query(f.Get(f.Ref("keys/104979509692858368")))

adminClient.query(Get(Ref("keys/104979509692858368")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "keys/104979509692858368" },
    "class": { "@ref": "keys" },
    "ts": 1436375112374190,
    "database": { "@ref": "databases/caledonia" },
    "role": "server",
    "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
  }
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

=> {
  "ref": { "@ref": "keys/104979509692858368" },
  "class": { "@ref": "keys" },
  "ts": 1436375112374190,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$.saZ/E/JSuEEkbIfTU/GN.7iKEBBpBGePtWe/mZyL/rmf4uXeZ5oi"
}

Paginate All Keys


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "paginate": { "@ref": "keys" } }'

adminClient.query(Paginate(Ref("keys")));

adminClient.query(q.Paginate(Ref("keys")));

adminClient.query(Paginate(Ref("keys")))

$admin_client.query do
  paginate ref('keys')
end

adminClient.Query(Paginate(Ref("keys")));

adminClient.query(q.paginate(Ref("keys")))

adminClient.Query(f.Paginate(f.Ref("keys")))

adminClient.query(Paginate(Ref("keys")))

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "keys/104979509693618791" },
      { "@ref": "keys/104979509692858368" }
    ]
  }
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

=> {
  "data": [
    { "@ref": "keys/104979509693618791" },
    { "@ref": "keys/104979509692858368" }
  ]
}

Delete a Key


curl https://db.fauna.com/ \
    -u kqnPAi3Kj3ZgAAC0Hu51Ng2dtn0JcgP7Fb-Q_uzLGZE: \
    -d '{ "delete": { "@ref": "keys/104979509693618791" } }'

adminClient.query(Delete(Ref("keys/104979509693618791")));

adminClient.query(q.Delete(Ref("keys/104979509693618791")));

adminClient.query(Delete(Ref("keys/104979509693618791")))

$admin_client.query do
  delete ref('keys/104979509693618791')
end

adminClient.Query(Delete(Ref("keys/104979509693618791")));

adminClient.query(q.delete(Ref("keys/104979509693618791")))

adminClient.Query(f.Delete(f.Ref("keys/104979509693618791")))

adminClient.query(
    Delete(ref: Ref("keys/104979509693618791"))
)

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "keys/104979509693618791" },
    "class": { "@ref": "keys" },
    "ts": 1436375112316028,
    "database": { "@ref": "databases/caledonia" },
    "role": "server",
    "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
  }
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

=> {
  "ref": { "@ref": "keys/104979509693618791" },
  "class": { "@ref": "keys" },
  "ts": 1436375112316028,
  "database": { "@ref": "databases/caledonia" },
  "role": "server",
  "hashed_secret": "$2a$05$/FgxoctNLXMBjYAcea/dwOeyYLJtQLGiEdf2S/Lu6ZN7e6Gps6WF6"
}

Classes

A database’s schema is defined by its classes. To create a class, create an instance of the classes class.

Once the class is defined, it is possible to create instances of the class using the query or REST APIs.

Note: A class cannot be created and used in the same transaction.

It is possible to rename a class by updating its name field. Renaming a class changes its ref, but preserves inbound references to the class. Instances of the class remain associated with the class.

When a class is deleted, associated instances become inaccessible, and are deleted asynchronously.

Fields

Name Type
name String Cannot be events, sets, self, instances, or _.
data Object A JSON object. Optional.
history_days Number Instance history is retained for at least this many days. Defaults to 30 days.
ttl_days Number Instances are deleted this many days after their last write. Optional.
permissions Object See below for specific fields. Optional.

History Retention & TTL

Each class has two configuration fields that control the retention of instance data. By default, instance history is stored for 30 days. Set history_days to another value to keep more or less history. Setting history_days to null will retain history forever. Increasing retention will increase storage utilization.

By setting a class’s ttl_days, instances of the class will be removed if they have not been updated within the configured TTL.

Security

Reading or writing classes requires a server key.

Creating, reading, and modifying an instance of a class is controlled by its permissions. Applicable fields on a class are:

Permission Allows
create Creating an instance of the class.
read Reading instances of the class.
write Writing to instances of the class.

Instances also have permissions, which are applied in addition to permissions defined on their class. The permissions object on an instance may contain these fields:

Permission Allows
read Reading this instance.
write Writing to this instance.

Examples

Create a Class


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "create_class": { "object": { "name": "spells" } } }'

client.query(CreateClass(Obj("name", Value("spells"))));

client.query(q.CreateClass({ name: "spells" }));

client.query(CreateClass(Obj("name" -> "spells")))

$client.query do
  create_class name: 'spells'
end

client.Query(CreateClass(Obj("name", "spells")));

client.query(q.create_class({"name": "spells"}))

client.Query(f.CreateClass(f.Obj{"name": "spells"}))

client.query(CreateClass(Obj("name" => "spells")))

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "classes/spells" },
    "class": { "@ref": "classes" },
    "ts": 1436375112432352,
    "history_days": 30,
    "name": "spells"
  }
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

Get a Class


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "get": { "class": "spells" } }'

client.query(Get(Class(Value("spells"))));

client.query(q.Get(q.Class("spells")));

client.query(Get(Class("spells")))

$client.query do
  get class_('spells')
end

client.Query(Get(Class("spells")));

client.query(q.get(q.class_expr("spells")))

client.Query(f.Get(f.Class("spells")))

client.query(Get(Class("spells")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "classes/spells" },
    "class": { "@ref": "classes" },
    "ts": 1436375112432352,
    "history_days": 30,
    "name": "spells"
  }
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

=> {
  "ref": { "@ref": "classes/spells" },
  "class": { "@ref": "classes" },
  "ts": 1436375112432352,
  "history_days": 30,
  "name": "spells"
}

Paginate All Classes


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "paginate": { "@ref": "classes" } }'

client.query(Paginate(Ref("classes")));

client.query(q.Paginate(Ref("classes")));

client.query(Paginate(Ref("classes")))

$client.query do
  paginate ref('classes')
end

client.Query(Paginate(Ref("classes")));

client.query(q.paginate(Ref("classes")))

client.Query(f.Paginate(f.Ref("classes")))

client.query(Paginate(Ref("classes")))

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "classes/decrepit_huts" },
      { "@ref": "classes/spellbooks" },
      { "@ref": "classes/characters" },
      { "@ref": "classes/spells" }
    ]
  }
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

=> {
  "data": [
    { "@ref": "classes/decrepit_huts" },
    { "@ref": "classes/spellbooks" },
    { "@ref": "classes/characters" },
    { "@ref": "classes/spells" }
  ]
}

Rename a Class


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "update": { "class": "decrepit_huts" },
          "params": { "object": { "name": "dilapidated_huts" } }
        }'

client.query(
  Update(
    Class(Value("decrepit_huts")),
    Obj("name", Value("dilapidated_huts"))));

client.query(
  q.Update(
    q.Class("decrepit_huts"),
    { name: "dilapidated_huts" }));

client.query(
  Update(
    Class("decrepit_huts"),
    Obj("name" -> "dilapidated_huts")))

$client.query do
  update class_('decrepit_huts'), name: 'dilapidated_huts'
end

client.Query(
  Update(
    Class("decrepit_huts"),
    Obj("name", "dilapidated_huts")));

client.query(
  q.update(
    q.class_expr("decrepit_huts"),
    {"name": "dilapidated_huts"}
  ))

client.Query(
    f.Update(
        f.Class("decrepit_huts"),
        f.Obj{"name": "dilapidated_huts"},
    ),
)

client.query(
    Update(
        ref: Class("decrepit_huts"),
        to: Obj("name" => "dilapidated_huts")
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "classes/dilapidated_huts" },
    "class": { "@ref": "classes" },
    "ts": 1436375112490514,
    "history_days": 30,
    "name": "dilapidated_huts"
  }
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

Delete a Class


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "delete": { "class": "dilapidated_huts" } }'

client.query(Delete(Class(Value("dilapidated_huts"))));

client.query(q.Delete(q.Class("dilapidated_huts")));

client.query(Delete(Class("dilapidated_huts")))

$client.query do
  delete class_('dilapidated_huts')
end

client.Query(Delete(Class("dilapidated_huts")));

client.query(q.delete(q.class_expr("dilapidated_huts")))

client.Query(f.Delete(f.Class("dilapidated_huts")))

client.query(Delete(ref: Class("dilapidated_huts")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "classes/dilapidated_huts" },
    "class": { "@ref": "classes" },
    "ts": 1436375112490514,
    "history_days": 30,
    "name": "dilapidated_huts"
  }
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

=> {
  "ref": { "@ref": "classes/dilapidated_huts" },
  "class": { "@ref": "classes" },
  "ts": 1436375112490514,
  "history_days": 30,
  "name": "dilapidated_huts"
}

Create an Instance of a Class


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create": { "class": "spells" },
          "params": {
            "object": {
              "data": {
                "object": { "name": "Fire Beak", "element": [ "air", "fire" ] }
              }
            }
          }
        }'

client.query(
  Create(
    Class(Value("spells")),
    Obj(
      "data", Obj(
        "name", Value("Fire Beak"),
        "element", Arr(Value("air"), Value("fire"))
      )
    )));

client.query(
  q.Create(
    q.Class("spells"),
    { data: { name: "Fire Beak", element: ["air", "fire"] } }));

client.query(
  Create(
    Class("spells"),
    Obj(
      "data" -> Obj("name" -> "Fire Beak", "element" -> Arr("air", "fire"))
    )))

$client.query do
  create class_('spells'),
         data: { name: 'Fire Beak', element: ['air', 'fire'] }
end

client.Query(
  Create(
    Class("spells"),
    Obj(
      "data", Obj("name", "Fire Beak", "element", Arr("air", "fire"))
    )));

client.query(
  q.create(
    q.class_expr("spells"),
    {"data": {"name": "Fire Beak", "element": ["air", "fire"]}}
  ))

client.Query(
    f.Create(
        f.Class("spells"),
        f.Obj{
            "data": f.Obj{"name": "Fire Beak", "element": f.Arr{"air", "fire"}},
        },
    ),
)

client.query(
    Create(
        at: Class("spells"),
        Obj(
            "data" => Obj(
                "name" => "Fire Beak",
                "element" => Arr("air", "fire")
            )
        )
    )
)

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "classes/spells/104979509694379214" },
    "class": { "@ref": "classes/spells" },
    "ts": 1436375112548676,
    "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
  }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

=> {
  "ref": { "@ref": "classes/spells/104979509694379214" },
  "class": { "@ref": "classes/spells" },
  "ts": 1436375112548676,
  "data": { "name": "Fire Beak", "element": [ "air", "fire" ] }
}

Indexes

Indexes allow for the organization and retrieval of instances by attributes other than their refs. They are defined as instances of the indexes class.

Note: An index cannot be created and read in the same transaction.

When an index is added, it is immediately available for reads, but will return incomplete results until it is built. FaunaDB will asynchronously build the index by scanning over relevant instances. Upon completion, the index’s active field will be set to true.

It is possible to rename an index by updating its name field. Renaming an index changes its ref, but preserves inbound references to the index. Index data is not rebuilt.

An index’s terms, values, or partitions fields may not be changed. If you update the unique field, it will not remove existing duplicated items from the index.

When an index is deleted, it becomes inaccessible, and its data is deleted asynchronously.

Reading Indexes

Entries in an index have zero or more terms, zero or more covered values.

Entries are partitioned into sets by their terms. Within each set, entries are sorted by their covered values.

The match function is used to refer to a set of entries within an index:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "match": { "index": "spells_by_element" }, "terms": "fire" }'

client.query(
  Match(Index(Value("spells_by_element")), Value("fire")));

client.query(q.Match(q.Index("spells_by_element"), "fire"));

client.query(Match(Index("spells_by_element"), "fire"))

$client.query do
  match index('spells_by_element'), 'fire'
end

client.Query(Match(Index("spells_by_element"), "fire"));

client.query(q.match(q.index("spells_by_element"), "fire"))

client.Query(f.MatchTerm(f.Index("spells_by_element"), "fire"))

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "fire"
    }
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

If the index is configured to index multiple terms (i.e. a compound index), match should be passed an Array with the required number of term values:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "match": { "index": "spells_by_element_and_name" },
          "terms": [ "fire", "Fire Beak" ]
        }'

client.query(
  Match(
    Index(Value("spells_by_element_and_name")),
    Arr(Value("fire"), Value("Fire Beak"))));

client.query(
  q.Match(
    q.Index("spells_by_element_and_name"),
    ["fire", "Fire Beak"]));

client.query(
  Match(
    Index("spells_by_element_and_name"),
    Arr("fire", "Fire Beak")))

$client.query do
  match index('spells_by_element_and_name'),
        ['fire', 'Fire Beak']
end

client.Query(
  Match(
    Index("spells_by_element_and_name"),
    Arr("fire", "Fire Beak")));

client.query(
  q.match(
    q.index("spells_by_element_and_name"),
    ["fire", "Fire Beak"]
  ))

client.Query(
    f.MatchTerm(
        f.Index("spells_by_element_and_name"),
        f.Arr{"fire", "Fire Beak"},
    ),
)

client.query(
    Match(
        index: Index("spells_by_element_and_name"),
        terms: "fire", "Fire Beak"
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element_and_name" },
      "terms": [ "fire", "Fire Beak" ]
    }
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element_and_name" },
    "terms": [ "fire", "Fire Beak" ]
  }
}

Or conversely, if the index is configured with no terms, then only the index ref need be provided:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "match": { "index": "all_spells" } }'

client.query(Match(Index(Value("all_spells"))));

client.query(q.Match(q.Index("all_spells")));

client.query(Match(Index("all_spells")))

$client.query do
  match index('all_spells')
end

client.Query(Match(Index("all_spells")));

client.query(q.match(q.index("all_spells")))

client.Query(f.Match(f.Index("all_spells")))

client.query(Match(index: Index("all_spells")))

HTTP/1.1 200 OK
{
  "resource": { "@set": { "match": { "@ref": "indexes/all_spells" } } }
}

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

=> { "@set": { "match": { "@ref": "indexes/all_spells" } } }

Index terms are always scalar values, and match interprets Arrays as tuples. For single-term indexes, the following expresssions are equivalent:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "match": { "index": "spells_by_element" }, "terms": "fire" }'

client.query(
  Match(Index(Value("spells_by_element")), Value("fire")));

client.query(q.Match(q.Index("spells_by_element"), "fire"));

client.query(Match(Index("spells_by_element"), "fire"))

$client.query do
  match index('spells_by_element'), 'fire'
end

client.Query(Match(Index("spells_by_element"), "fire"));

client.query(q.match(q.index("spells_by_element"), "fire"))

client.Query(f.MatchTerm(f.Index("spells_by_element"), "fire"))

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "fire"
    }
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "match": { "index": "spells_by_element" },
          "terms": [ "fire" ]
        }'

client.query(
  Match(Index(Value("spells_by_element")), Arr(Value("fire"))));

client.query(q.Match(q.Index("spells_by_element"), ["fire"]));

client.query(Match(Index("spells_by_element"), Arr("fire")))

$client.query do
  match index('spells_by_element'), ['fire']
end

client.Query(Match(Index("spells_by_element"), Arr("fire")));

client.query(q.match(q.index("spells_by_element"), ["fire"]))

client.Query(
    f.MatchTerm(f.Index("spells_by_element"), f.Arr{"fire"}),
)

client.query(
    Match(index: Index("spells_by_element"), terms: "fire")
)

HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "fire"
    }
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

=> {
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "fire"
  }
}

Fields

Name Type
name String Cannot be events, sets, self, instances, or _.
source VarArgs One or more source objects describing source classes and (optional) field bindings.
terms Array An array of term objects describing the fields to be indexed. Optional
values Array An array of value objects describing the fields to be covered. Optional
unique Boolean If true, maintains a uniqueness constraint on combined terms and values. Optional
partitions Integer The number of sub-partitions within each term. Optional
permissions Object See below for specific fields. Optional

Source Objects

Source objects describe the source class of index entries and, optionally, bindings. A binding must be a pure lambda function that emits values to be used as a term and/or value.

The class field can be a single class ref or set of refs. Instances of classes matching the class field will apply the associated bindings to be used in the index’s terms or values. A class ref can only exist in one source object. If the class is a wildcard (_), the index will run over all classes. Bindings associated with a wildcard will only be used if the class is not matched by any other source object.

Name Type
class Ref The class or classes to be indexed, or a wildcard.
bindings Object A binding object describing bindings and their transforms. Optional

Binding Objects

A binding object contains field names bound to pure, single-argument lambda functions. The function must take the instance to be indexed and emit either a single scalar value or an array of scalar values. Binding functions are not permitted to perform reads or writes.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "object": {
            "binding1": {
              "query": {
                "lambda": "instance",
                "expr": {
                  "select": [ "data", "field" ],
                  "from": { "var": "instance" }
                }
              }
            }
          }
        }'

// Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

HTTP/1.1 200 OK
{
  "resource": {
    "binding1": {
      "@query": {
        "lambda": "instance",
        "expr": {
          "select": [ "data", "field" ],
          "from": { "var": "instance" }
        }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

=> {
  "binding1": {
    "@query": {
      "lambda": "instance",
      "expr": {
        "select": [ "data", "field" ],
        "from": { "var": "instance" }
      }
    }
  }
}

Term Objects

Term objects describe the fields used to locate entries in the index. If multiple terms are provided, instances missing a value will emit a Null term in the index for that field.

If no term objects are defined, passing term values to to match is not required. The resulting set will contain all instances of the source class.

A value can be from a field in the instance or a binding defined by the source object.

Fields
field Array The path of the field within an instance to be indexed.
binding String The name of a binding from a source object.

Value Objects

Value objects describe the data covered by the index, which are included in query results on the index and control ordering of entries having the same terms. By default, indexes cover only the refs of included instances.

A value can be from a field in the instance or a binding defined in a source object.

Fields
field Array The path of the field within an instance to be indexed.
binding String The name of a binding from a source object.
reverse Boolean Whether this field’s value should sort reversed. Defaults to false.

Note: The instance’s ref may also appear in before and after cursors when paging through an index with paginate, even if the ref does not appear as a covered value in the index configuration. These “extra” refs are used to stabilize pagination.

Field Values

Any of an instance’s fields may be indexed. The value of field in a Term or Value object indicates the position within an instance for a field. For example, the field "ref" refers to the top-level ref field. The field ["data", "address", "street"] refers to the street field contained in an address object within the instance’s data object.

Ordering

Covered values sort lexically according to their type. Strings and Numbers sort using their natural order, while Arrays and Objects sort according to their contents. For example, { "name": "Hen Wen" } will appear after { }, and { "age": 110 }.

Instances may have different types of values in the same field, or an instance may be missing a field entirely. An index covering that path will sort values in this order: Integers, Strings, Arrays, Objects, Refs, Times, Dates, Booleans, Decimals, Nulls.

The default sort order may be reversed on a per-field basis using the reverse flag in the index configuration.

Partitioning

FaunaDB partitions indexes on the set of terms for each index entry. Therefore, there is no performance difference between an index on the terms [{ "field": ["data", "name"] }, { "field": ["data", "age"] }] and [{ "field": ["data", "age"] }, { "field": ["data", "name"] }].

Term partitions may be sub-divided by the number of partitions in the index configuration. Sub-dividing indexes beyond their term may increase write performance for terms with many entries, but may also increase read latency.

Class indexes default to 8 sub-partitions; all other indexes default to a single term partition. No index may have more than 8 sub-partitions.

Security

Creating and updating an index requires a server key.

Query access to an index is controlled by its permissions. Applicable fields are:

Permission Allows
read Querying the index.

Examples

Create an Index

Let’s create an index to list all spells’ names:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create_index": {
            "object": {
              "name": "all_spell_names",
              "source": { "class": "spells" },
              "values": [ { "object": { "field": [ "data", "name" ] } } ]
            }
          }
        }'

client.query(
  CreateIndex(
    Obj(
      "name", Value("all_spell_names"),
      "source", Class(Value("spells")),
      "values", Arr(Obj("field", Arr(Value("data"), Value("name"))))
    )));

client.query(
  q.CreateIndex(
    {
      name: "all_spell_names",
      source: q.Class("spells"),
      values: [{ field: ["data", "name"] }]
    }));

client.query(
  CreateIndex(
    Obj(
      "name" -> "all_spell_names",
      "source" -> Class("spells"),
      "values" -> Arr(Obj("field" -> Arr("data", "name")))
    )))

$client.query do
  create_index name: 'all_spell_names',
               source: class_('spells'),
               values: [{ field: ['data', 'name'] }]
end

client.Query(
  CreateIndex(
    Obj(
      "name", "all_spell_names",
      "source", Class("spells"),
      "values", Arr(Obj("field", Arr("data", "name")))
    )));

client.query(
  q.create_index(
    {
      "name": "all_spell_names",
      "source": q.class_expr("spells"),
      "values": [{"field": ["data", "name"]}]
    }
  ))

client.Query(
    f.CreateIndex(
        f.Obj{
            "name": "all_spell_names",
            "source": f.Class("spells"),
            "values": f.Arr{f.Obj{"field": f.Arr{"data", "name"}}},
        },
    ),
)

client.query(
    CreateIndex(
        Obj(
            "name" => "all_spell_names",
            "source" => Class("spells"),
            "values" => Arr(Obj("field" => Arr("data", "name")))
        )
    )
)

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "indexes/all_spell_names" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112665000,
    "unique": false,
    "active": false,
    "partitions": 8,
    "name": "all_spell_names",
    "source": { "@ref": "classes/spells" },
    "values": [ { "field": [ "data", "name" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/all_spell_names" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112665000,
  "unique": false,
  "active": false,
  "partitions": 8,
  "name": "all_spell_names",
  "source": { "@ref": "classes/spells" },
  "values": [ { "field": [ "data", "name" ] } ]
}

It’s also possible to specify the terms that are going to be used to locate entries on the index. In this case, we’ll create an index that allow us to find spells by their elements’ name:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create_index": {
            "object": {
              "name": "spells_by_element_with_name",
              "source": { "class": "spells" },
              "terms": [ { "object": { "field": [ "data", "element" ] } } ],
              "values": [ { "object": { "field": [ "data", "name" ] } } ]
            }
          }
        }'

client.query(
  CreateIndex(
    Obj(
      "name", Value("spells_by_element_with_name"),
      "source", Class(Value("spells")),
      "terms", Arr(Obj("field", Arr(Value("data"), Value("element")))),
      "values", Arr(Obj("field", Arr(Value("data"), Value("name"))))
    )));

client.query(
  q.CreateIndex(
    {
      name: "spells_by_element_with_name",
      source: q.Class("spells"),
      terms: [{ field: ["data", "element"] }],
      values: [{ field: ["data", "name"] }]
    }));

client.query(
  CreateIndex(
    Obj(
      "name" -> "spells_by_element_with_name",
      "source" -> Class("spells"),
      "terms" -> Arr(Obj("field" -> Arr("data", "element"))),
      "values" -> Arr(Obj("field" -> Arr("data", "name")))
    )))

$client.query do
  create_index name: 'spells_by_element_with_name',
               source: class_('spells'),
               terms: [{ field: ['data', 'element'] }],
               values: [{ field: ['data', 'name'] }]
end

client.Query(
  CreateIndex(
    Obj(
      "name", "spells_by_element_with_name",
      "source", Class("spells"),
      "terms", Arr(Obj("field", Arr("data", "element"))),
      "values", Arr(Obj("field", Arr("data", "name")))
    )));

client.query(
  q.create_index(
    {
      "name": "spells_by_element_with_name",
      "source": q.class_expr("spells"),
      "terms": [{"field": ["data", "element"]}],
      "values": [{"field": ["data", "name"]}]
    }
  ))

client.Query(
    f.CreateIndex(
        f.Obj{
            "name": "spells_by_element_with_name",
            "source": f.Class("spells"),
            "terms": f.Arr{f.Obj{"field": f.Arr{"data", "element"}}},
            "values": f.Arr{f.Obj{"field": f.Arr{"data", "name"}}},
        },
    ),
)

client.query(
    CreateIndex(
        Obj(
            "name" => "spells_by_element_with_name",
            "source" => Class("spells"),
            "terms" => Arr(Obj("field" => Arr("data", "element"))),
            "values" => Arr(Obj("field" => Arr("data", "name")))
        )
    )
)

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "indexes/spells_by_element_with_name" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112723162,
    "unique": false,
    "active": false,
    "partitions": 1,
    "name": "spells_by_element_with_name",
    "source": { "@ref": "classes/spells" },
    "terms": [ { "field": [ "data", "element" ] } ],
    "values": [ { "field": [ "data", "name" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112723162,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

Indexes can also cover multiple values, which affect the order of their results. Check ordering for more information.

Here is an example of an index that allows you to search for a spell by its element and get back both the spell name and ref:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create_index": {
            "object": {
              "name": "spells_with_ref_by_element_name",
              "source": { "class": "spells" },
              "terms": [ { "object": { "field": [ "data", "element" ] } } ],
              "values": [
                { "object": { "field": [ "data", "name" ] } },
                { "object": { "field": [ "ref" ] } }
              ]
            }
          }
        }'

client.query(
  CreateIndex(
    Obj(
      "name", Value("spells_with_ref_by_element_name"),
      "source", Class(Value("spells")),
      "terms", Arr(Obj("field", Arr(Value("data"), Value("element")))),
      "values", Arr(
        Obj("field", Arr(Value("data"), Value("name"))),
        Obj("field", Arr(Value("ref")))
      )
    )));

client.query(
  q.CreateIndex(
    {
      name: "spells_with_ref_by_element_name",
      source: q.Class("spells"),
      terms: [{ field: ["data", "element"] }],
      values: [{ field: ["data", "name"] }, { field: ["ref"] }]
    }));

client.query(
  CreateIndex(
    Obj(
      "name" -> "spells_with_ref_by_element_name",
      "source" -> Class("spells"),
      "terms" -> Arr(Obj("field" -> Arr("data", "element"))),
      "values" -> Arr(
        Obj("field" -> Arr("data", "name")),
        Obj("field" -> Arr("ref"))
      )
    )))

$client.query do
  create_index name: 'spells_with_ref_by_element_name',
               source: class_('spells'),
               terms: [{ field: ['data', 'element'] }],
               values: [{ field: ['data', 'name'] }, { field: ['ref'] }]
end

client.Query(
  CreateIndex(
    Obj(
      "name", "spells_with_ref_by_element_name",
      "source", Class("spells"),
      "terms", Arr(Obj("field", Arr("data", "element"))),
      "values", Arr(
        Obj("field", Arr("data", "name")),
        Obj("field", Arr("ref"))
      )
    )));

client.query(
  q.create_index(
    {
      "name": "spells_with_ref_by_element_name",
      "source": q.class_expr("spells"),
      "terms": [{"field": ["data", "element"]}],
      "values": [{"field": ["data", "name"]}, {"field": ["ref"]}]
    }
  ))

client.Query(
    f.CreateIndex(
        f.Obj{
            "name": "spells_with_ref_by_element_name",
            "source": f.Class("spells"),
            "terms": f.Arr{f.Obj{"field": f.Arr{"data", "element"}}},
            "values": f.Arr{
                f.Obj{"field": f.Arr{"data", "name"}},
                f.Obj{"field": f.Arr{"ref"}},
            },
        },
    ),
)

client.query(
    CreateIndex(
        Obj(
            "name" => "spells_with_ref_by_element_name",
            "source" => Class("spells"),
            "terms" => Arr(Obj("field" => Arr("data", "element"))),
            "values" => Arr(
                Obj("field" => Arr("data", "name")),
                Obj("field" => Arr("ref"))
            )
        )
    )
)

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112839486,
    "unique": false,
    "active": false,
    "partitions": 1,
    "name": "spells_with_ref_by_element_name",
    "source": { "@ref": "classes/spells" },
    "terms": [ { "field": [ "data", "element" ] } ],
    "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_with_ref_by_element_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112839486,
  "unique": false,
  "active": false,
  "partitions": 1,
  "name": "spells_with_ref_by_element_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] }, { "field": [ "ref" ] } ]
}

Get an Index


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "get": { "index": "spells_by_element_with_name" } }'

client.query(Get(Index(Value("spells_by_element_with_name"))));

client.query(q.Get(q.Index("spells_by_element_with_name")));

client.query(Get(Index("spells_by_element_with_name")))

$client.query do
  get index('spells_by_element_with_name')
end

client.Query(Get(Index("spells_by_element_with_name")));

client.query(q.get(q.index("spells_by_element_with_name")))

client.Query(f.Get(f.Index("spells_by_element_with_name")))

client.query(Get(Index("spells_by_element_with_name")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "indexes/spells_by_element_with_name" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112781324,
    "unique": false,
    "active": true,
    "partitions": 1,
    "name": "spells_by_element_with_name",
    "source": { "@ref": "classes/spells" },
    "terms": [ { "field": [ "data", "element" ] } ],
    "values": [ { "field": [ "data", "name" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_element_with_name" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112781324,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_element_with_name",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

Query an Index

Indexes created without specifying the terms field return all elements on the indexed class.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "paginate": { "match": { "index": "all_spell_names" } } }'

client.query(Paginate(Match(Index(Value("all_spell_names")))));

client.query(q.Paginate(q.Match(q.Index("all_spell_names"))));

client.query(Paginate(Match(Index("all_spell_names"))))

$client.query do
  paginate match(index('all_spell_names'))
end

client.Query(Paginate(Match(Index("all_spell_names"))));

client.query(q.paginate(q.match(q.index("all_spell_names"))))

client.Query(f.Paginate(f.Match(f.Index("all_spell_names"))))

client.query(
    Paginate(Match(index: Index("all_spell_names")))
)

HTTP/1.1 200 OK
{
  "resource": {
    "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
  }
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

=> {
  "data": [ "Fire Beak", "Hippo's Wallow", "Water Dragon's Claw" ]
}

For indexes where the terms field was defined, it’s possible to locate entries using the indexed terms.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "paginate": {
            "match": { "index": "spells_by_element_with_name" },
            "terms": "fire"
          }
        }'

client.query(
  Paginate(
      Match(
        Index(Value("spells_by_element_with_name")),
        Value("fire"))));

client.query(
  q.Paginate(
    q.Match(q.Index("spells_by_element_with_name"), "fire")));

client.query(
  Paginate(Match(Index("spells_by_element_with_name"), "fire")))

$client.query do
  paginate match(index('spells_by_element_with_name'), 'fire')
end

client.Query(
  Paginate(Match(Index("spells_by_element_with_name"), "fire")));

client.query(
  q.paginate(
    q.match(q.index("spells_by_element_with_name"), "fire")
  ))

client.Query(
    f.Paginate(
        f.MatchTerm(
            f.Index("spells_by_element_with_name"),
            "fire",
        ),
    ),
)

client.query(
    Paginate(
        Match(
            index: Index("spells_by_element_with_name"),
            terms: "fire"
        )
    )
)

HTTP/1.1 200 OK
{
  "resource": { "data": [ "Fire Beak", "Water Dragon's Claw" ] }
}

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

=> { "data": [ "Fire Beak", "Water Dragon's Claw" ] }

Indexes return all their covered values. Here we’re searching for all the spells with element “fire” and displaying the spell name along with its ref:


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "paginate": {
            "match": { "index": "spells_with_ref_by_element_name" },
            "terms": "fire"
          }
        }'

client.query(
  Paginate(
      Match(
        Index(Value("spells_with_ref_by_element_name")),
        Value("fire"))));

client.query(
  q.Paginate(
    q.Match(q.Index("spells_with_ref_by_element_name"), "fire")));

client.query(
  Paginate(
    Match(Index("spells_with_ref_by_element_name"), "fire")))

$client.query do
  paginate match(index('spells_with_ref_by_element_name'), 'fire')
end

client.Query(
  Paginate(
    Match(Index("spells_with_ref_by_element_name"), "fire")));

client.query(
  q.paginate(
    q.match(q.index("spells_with_ref_by_element_name"), "fire")
  ))

client.Query(
    f.Paginate(
        f.MatchTerm(
            f.Index("spells_with_ref_by_element_name"),
            "fire",
        ),
    ),
)

client.query(
    Paginate(
        Match(
            index: Index("spells_with_ref_by_element_name"),
            terms: "fire"
        )
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      [
        "Fire Beak",
        { "@ref": "classes/spells/104979509694379214" }
      ],
      [
        "Water Dragon's Claw",
        { "@ref": "classes/spells/104979509695139637" }
      ]
    ]
  }
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

=> {
  "data": [
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ],
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ]
  ]
}

Indexes with Ordering and Transformations

Let’s create an index to return the latest spells updated given their elements’ name. We can create an index which is sorted reversely by the spell’s last updated timestamp.

We’ll also use the casefold function as a transformation to the index’s terms so we can query spells despite the case of their elements’ name.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create_index": {
            "object": {
              "name": "latest_spells_by_element",
              "source": { "class": "spells" },
              "terms": [
                {
                  "object": {
                    "field": [ "data", "element" ],
                    "transform": "casefold"
                  }
                }
              ],
              "values": [
                { "object": { "field": [ "ts" ], "reverse": true } },
                { "object": { "field": [ "data", "name" ] } },
                { "object": { "field": [ "ref" ] } }
              ]
            }
          }
        }'

client.query(
  CreateIndex(
    Obj(
      "name", Value("latest_spells_by_element"),
      "source", Class(Value("spells")),
      "terms", Arr(
        Obj(
          "field", Arr(Value("data"), Value("element")),
          "transform", Value("casefold")
        )
      ),
      "values", Arr(
        Obj("field", Arr(Value("ts")), "reverse", Value(true)),
        Obj("field", Arr(Value("data"), Value("name"))),
        Obj("field", Arr(Value("ref")))
      )
    )));

client.query(
  q.CreateIndex(
    {
      name: "latest_spells_by_element",
      source: q.Class("spells"),
      terms: [{ field: ["data", "element"], transform: "casefold" }],
      values: [
        { field: ["ts"], reverse: true },
        { field: ["data", "name"] },
        { field: ["ref"] }
      ]
    }));

client.query(
  CreateIndex(
    Obj(
      "name" -> "latest_spells_by_element",
      "source" -> Class("spells"),
      "terms" -> Arr(
        Obj(
          "field" -> Arr("data", "element"),
          "transform" -> "casefold"
        )
      ),
      "values" -> Arr(
        Obj("field" -> Arr("ts"), "reverse" -> true),
        Obj("field" -> Arr("data", "name")),
        Obj("field" -> Arr("ref"))
      )
    )))

$client.query do
  create_index name: 'latest_spells_by_element',
               source: class_('spells'),
               terms: [{ field: ['data', 'element'], transform: 'casefold' }],
               values: [
                 { field: ['ts'], reverse: true },
                 { field: ['data', 'name'] },
                 { field: ['ref'] }
               ]
end

client.Query(
  CreateIndex(
    Obj(
      "name", "latest_spells_by_element",
      "source", Class("spells"),
      "terms", Arr(
        Obj("field", Arr("data", "element"), "transform", "casefold")
      ),
      "values", Arr(
        Obj("field", Arr("ts"), "reverse", true),
        Obj("field", Arr("data", "name")),
        Obj("field", Arr("ref"))
      )
    )));

client.query(
  q.create_index(
    {
      "name": "latest_spells_by_element",
      "source": q.class_expr("spells"),
      "terms": [{"field": ["data", "element"], "transform": "casefold"}],
      "values": [
        {"field": ["ts"], "reverse": True},
        {"field": ["data", "name"]},
        {"field": ["ref"]}
      ]
    }
  ))

client.Query(
    f.CreateIndex(
        f.Obj{
            "name": "latest_spells_by_element",
            "source": f.Class("spells"),
            "terms": f.Arr{
                f.Obj{
                    "field": f.Arr{"data", "element"},
                    "transform": "casefold",
                },
            },
            "values": f.Arr{
                f.Obj{"field": f.Arr{"ts"}, "reverse": true},
                f.Obj{"field": f.Arr{"data", "name"}},
                f.Obj{"field": f.Arr{"ref"}},
            },
        },
    ),
)

client.query(
    CreateIndex(
        Obj(
            "name" => "latest_spells_by_element",
            "source" => Class("spells"),
            "terms" => Arr(
                Obj(
                    "field" => Arr("data", "element"),
                    "transform" => "casefold"
                )
            ),
            "values" => Arr(
                Obj("field" => Arr("ts"), "reverse" => true),
                Obj("field" => Arr("data", "name")),
                Obj("field" => Arr("ref"))
            )
        )
    )
)

When querying the index, you can use the casefold function to make sure that the element you’re looking for has the same case as the index’s term.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "paginate": {
            "match": { "index": "latest_spells_by_element" },
            "terms": { "casefold": "FIRE" }
          }
        }'

client.query(
  Paginate(
      Match(
        Index(Value("latest_spells_by_element")),
        Casefold(Value("FIRE")))));

client.query(
  q.Paginate(
    q.Match(
      q.Index("latest_spells_by_element"),
      q.Casefold("FIRE"))));

client.query(
  Paginate(
    Match(Index("latest_spells_by_element"), Casefold("FIRE"))))

$client.query do
  paginate match(index('latest_spells_by_element'), casefold('FIRE'))
end

client.Query(
  Paginate(
    Match(Index("latest_spells_by_element"), Casefold("FIRE"))));

client.query(
  q.paginate(
    q.match(
      q.index("latest_spells_by_element"),
      q.casefold("FIRE")
    )
  ))

client.Query(
    f.Paginate(
        f.MatchTerm(
            f.Index("latest_spells_by_element"),
            f.Casefold("FIRE"),
        ),
    ),
)

client.query(
    Paginate(
        Match(
            index: Index("latest_spells_by_element"),
            terms: Casefold("FIRE")
        )
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      [
        1436375112606838,
        "Water Dragon's Claw",
        { "@ref": "classes/spells/104979509695139637" }
      ],
      [
        1436375112548676,
        "Fire Beak",
        { "@ref": "classes/spells/104979509694379214" }
      ]
    ]
  }
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      1436375112606838,
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      1436375112548676,
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

Since the timestamp was used only to sort the index, it might not be required for the application layer. It that case, it’s possible to use the map function to extract only the useful fields.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "map": {
            "lambda": [ "_", "name", "ref" ],
            "expr": [ { "var": "name" }, { "var": "ref" } ]
          },
          "collection": {
            "paginate": {
              "match": { "index": "latest_spells_by_element" },
              "terms": { "casefold": "FIRE" }
            }
          }
        }'

client.query(
  Map(
    Paginate(
        Match(
          Index(Value("latest_spells_by_element")),
          Casefold(Value("FIRE")))),
    Lambda(
      Arr(Value("_"), Value("name"), Value("ref")),
      Arr(Var("name"), Var("ref")))));

client.query(
  q.Map(
    q.Paginate(
      q.Match(
        q.Index("latest_spells_by_element"),
        q.Casefold("FIRE"))),
    function(_, name, ref) {
      return [name, ref];
    }));

client.query(
  Map(
    Paginate(
      Match(Index("latest_spells_by_element"), Casefold("FIRE"))),
    Lambda { (_, name, ref) => Arr(name, ref) }))

$client.query do
  map paginate(match(index('latest_spells_by_element'), casefold('FIRE'))),
      lambda_expr(['_', 'name', 'ref'], [var('name'), var('ref')])
end

client.Query(
  Map(
    Paginate(
      Match(Index("latest_spells_by_element"), Casefold("FIRE"))),
    Lambda(
      Arr("_", "name", "ref"),
      Arr(Var("name"), Var("ref")))));

client.query(
  q.map_expr(
    q.lambda_expr(
      ["_", "name", "ref"],
      [q.var("name"), q.var("ref")]
    ),
    q.paginate(
      q.match(
        q.index("latest_spells_by_element"),
        q.casefold("FIRE")
      )
    )
  ))

client.Query(
    f.Map(
        f.Paginate(
            f.MatchTerm(
                f.Index("latest_spells_by_element"),
                f.Casefold("FIRE"),
            ),
        ),
        f.Lambda(
            f.Arr{"_", "name", "ref"},
            f.Arr{f.Var("name"), f.Var("ref")},
        ),
    ),
)

client.query(
    Map(
        collection: Paginate(
            Match(
                index: Index("latest_spells_by_element"),
                terms: Casefold("FIRE")
            )
        ),
        to: Lambda(
            vars: "_", "name", "ref"
            in: Arr(Var("name"), Var("ref"))
        )
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      [
        "Water Dragon's Claw",
        { "@ref": "classes/spells/104979509695139637" }
      ],
      [
        "Fire Beak",
        { "@ref": "classes/spells/104979509694379214" }
      ]
    ]
  }
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

=> {
  "data": [
    [
      "Water Dragon's Claw",
      { "@ref": "classes/spells/104979509695139637" }
    ],
    [
      "Fire Beak",
      { "@ref": "classes/spells/104979509694379214" }
    ]
  ]
}

Paginate All Indexes


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "paginate": { "@ref": "indexes" } }'

client.query(Paginate(Ref("indexes")));

client.query(q.Paginate(Ref("indexes")));

client.query(Paginate(Ref("indexes")))

$client.query do
  paginate ref('indexes')
end

client.Query(Paginate(Ref("indexes")));

client.query(q.paginate(Ref("indexes")))

client.Query(f.Paginate(f.Ref("indexes")))

client.query(Paginate(Ref("indexes")))

HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "indexes/all_spells" },
      { "@ref": "indexes/spells_by_name" },
      { "@ref": "indexes/spells_by_element" },
      { "@ref": "indexes/spells_by_element_and_name" },
      { "@ref": "indexes/spellbooks_by_owner" },
      { "@ref": "indexes/spells_by_spellbook" },
      { "@ref": "indexes/all_spell_names" },
      { "@ref": "indexes/spells_by_element_with_name" },
      { "@ref": "indexes/spells_with_ref_by_element_name" },
      { "@ref": "indexes/latest_spells_by_element" }
    ]
  }
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

=> {
  "data": [
    { "@ref": "indexes/all_spells" },
    { "@ref": "indexes/spells_by_name" },
    { "@ref": "indexes/spells_by_element" },
    { "@ref": "indexes/spells_by_element_and_name" },
    { "@ref": "indexes/spellbooks_by_owner" },
    { "@ref": "indexes/spells_by_spellbook" },
    { "@ref": "indexes/all_spell_names" },
    { "@ref": "indexes/spells_by_element_with_name" },
    { "@ref": "indexes/spells_with_ref_by_element_name" },
    { "@ref": "indexes/latest_spells_by_element" }
  ]
}

Update an Index

It is disallowed to update an index in a way that changes its shape. So this means no changing the source or the terms. You can, however, change the name or its uniqueness. If you update the unique field, it will not remove existing duplicated items from the index.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "update": { "index": "spells_by_element_with_name" },
          "params": { "object": { "name": "spells_by_kind" } }
        }'

client.query(
  Update(
    Index(Value("spells_by_element_with_name")),
    Obj("name", Value("spells_by_kind"))));

client.query(
  q.Update(
    q.Index("spells_by_element_with_name"),
    { name: "spells_by_kind" }));

client.query(
  Update(
    Index("spells_by_element_with_name"),
    Obj("name" -> "spells_by_kind")))

$client.query do
  update index('spells_by_element_with_name'),
         name: 'spells_by_kind'
end

client.Query(
  Update(
    Index("spells_by_element_with_name"),
    Obj("name", "spells_by_kind")));

client.query(
  q.update(
    q.index("spells_by_element_with_name"),
    {"name": "spells_by_kind"}
  ))

client.Query(
    f.Update(
        f.Index("spells_by_element_with_name"),
        f.Obj{"name": "spells_by_kind"},
    ),
)

client.query(
    Update(
        ref: Index("spells_by_element_with_name"),
        to: Obj("name" => "spells_by_kind")
    )
)

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "indexes/spells_by_kind" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112897648,
    "unique": false,
    "active": true,
    "partitions": 1,
    "name": "spells_by_kind",
    "source": { "@ref": "classes/spells" },
    "terms": [ { "field": [ "data", "element" ] } ],
    "values": [ { "field": [ "data", "name" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

Delete an Index


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{ "delete": { "index": "spells_by_kind" } }'

client.query(Delete(Index(Value("spells_by_kind"))));

client.query(q.Delete(q.Index("spells_by_kind")));

client.query(Delete(Index("spells_by_kind")))

$client.query do
  delete index('spells_by_kind')
end

client.Query(Delete(Index("spells_by_kind")));

client.query(q.delete(q.index("spells_by_kind")))

client.Query(f.Delete(f.Index("spells_by_kind")))

client.query(Delete(ref: Index("spells_by_kind")))

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "indexes/spells_by_kind" },
    "class": { "@ref": "indexes" },
    "ts": 1436375112897648,
    "unique": false,
    "active": true,
    "partitions": 1,
    "name": "spells_by_kind",
    "source": { "@ref": "classes/spells" },
    "terms": [ { "field": [ "data", "element" ] } ],
    "values": [ { "field": [ "data", "name" ] } ]
  }
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

=> {
  "ref": { "@ref": "indexes/spells_by_kind" },
  "class": { "@ref": "indexes" },
  "ts": 1436375112897648,
  "unique": false,
  "active": true,
  "partitions": 1,
  "name": "spells_by_kind",
  "source": { "@ref": "classes/spells" },
  "terms": [ { "field": [ "data", "element" ] } ],
  "values": [ { "field": [ "data", "name" ] } ]
}

User Defined Functions

User defined functions provide a mechanims for storing and running Fauna queries within FaunaDB. Untrusted clients can perform privileged actions without an intermediate system ensuring the client is sending safe queries.

Fields

Name Type
name String Cannot be events, sets, self, instances, or _.
body Lambda The query to be run when the function is called.
role String The privileges the function should be run at. Either admin, server, server-readonly or client. Optional

Security

Creating and updating a function requires a server key.

Calling a function is controlled by its permissions. Applicable fields are:

Permission Allows
call Calling the function.

Examples

Create a User Defined Function

Let’s create a function to allow our authors to create new blog posts. We’ll set it up to allow the author to provide a title and body. This way authors are constrained by what data they can store on the post instance.


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create_function": {
            "object": {
              "name": "create_entry",
              "body": {
                "query": {
                  "lambda": [ "title", "body" ],
                  "expr": {
                    "create": { "class": "posts" },
                    "params": {
                      "object": {
                        "title": { "var": "title" },
                        "body": { "var": "body" }
                      }
                    }
                  }
                }
              },
              "permissions": { "object": { "call": "public" } },
              "role": "server"
            }
          }
        }'

// Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "functions/create_entry" },
    "class": { "@ref": "functions" },
    "ts": 1436375112955810,
    "name": "create_entry",
    "body": {
      "@query": {
        "lambda": [ "title", "body" ],
        "expr": {
          "create": { "class": "posts" },
          "params": {
            "object": {
              "title": { "var": "title" },
              "body": { "var": "body" }
            }
          }
        }
      }
    },
    "permissions": { "call": "public" },
    "role": "server"
  }
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

=> {
  "ref": { "@ref": "functions/create_entry" },
  "class": { "@ref": "functions" },
  "ts": 1436375112955810,
  "name": "create_entry",
  "body": {
    "@query": {
      "lambda": [ "title", "body" ],
      "expr": {
        "create": { "class": "posts" },
        "params": {
          "object": {
            "title": { "var": "title" },
            "body": { "var": "body" }
          }
        }
      }
    }
  },
  "permissions": { "call": "public" },
  "role": "server"
}

Now we can create a new author and use their credentials


curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "create": { "class": "authors" },
          "params": {
            "object": {
              "data": { "object": { "name": "Patty Smith" } },
              "credentials": { "object": { "password": "123456" } }
            }
          }
        }'

// Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "classes/authors/104979509695900060" },
    "class": { "@ref": "classes/authors" },
    "ts": 1436375113013972,
    "data": { "name": "Patty Smith" }
  }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

=> {
  "ref": { "@ref": "classes/authors/104979509695900060" },
  "class": { "@ref": "classes/authors" },
  "ts": 1436375113013972,
  "data": { "name": "Patty Smith" }
}

curl https://db.fauna.com/ \
    -u kqnPAi4gDivAAAC0i5t-a9YCcRnljtU2SfMJ-kWSRYI: \
    -d '{
          "login": { "@ref": "classes/authors/104979509695900060" },
          "params": { "object": { "password": "123456" } }
        }'

// Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "tokens/104979509696660483" },
    "class": { "@ref": "tokens" },
    "ts": 1436375113072134,
    "instance": { "@ref": "classes/authors/104979509695900060" },
    "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
  }
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

=> {
  "ref": { "@ref": "tokens/104979509696660483" },
  "class": { "@ref": "tokens" },
  "ts": 1436375113072134,
  "instance": { "@ref": "classes/authors/104979509695900060" },
  "secret": "k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA"
}

After the author has logged in, they can use their secret to call the create_entry function that we created.


curl https://db.fauna.com/ \
    -u k6oCLcqe9TAAAAADqc8CLcqVdZAAALQaz43VUOEOvexWVMNr3vjvZfLVCA: \
    -d '{
          "call": { "function": "create_entry" },
          "arguments": [ "First Post Title", "This is my first blog post!" ]
        }'

// Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

# Not available in this language yet.

// Not available in this language yet.

// Not available in this language yet.

HTTP/1.1 201 Created
{
  "resource": {
    "ref": { "@ref": "classes/posts/104979509697420906" },
    "class": { "@ref": "classes/posts" },
    "ts": 1436375113130296
  }
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}

=> {
  "ref": { "@ref": "classes/posts/104979509697420906" },
  "class": { "@ref": "classes/posts" },
  "ts": 1436375113130296
}