Instance Object, Class, and Database Reference

Instance objects are single, changeable records within a FaunaDB database. A database is an instance object that serves as a container for data. A class is an instance object that groups together data within a database.

Instance Objects

Each record in a FaunaDB database is stored as an object. All instances are objects, but you can have objects that are not instances. Every instance object belongs to a specific class. This includes configuration as well: databases, keys, user-defined classes, and indexes are all instances of their respective schema classes.

All instances have a set of common characteristics:

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.

All instances are manipulated with the same query language functions: get, create, update, replace, and delete. Instances returned by queries are represented as JSON objects. Within a query, an instance’s fields may be accessed using select.

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

Field Value Definition

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.

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.

Field Type Definition and Requirements

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.

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 in the class using the query API.

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 in the class remain associated with the class.

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

Field Type Definition and Requirements

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

Optional.

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.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve! documentation@fauna.com

Thank you for your feedback!