TOPICS
LANGUAGE

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.

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 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.