Types

This pages information about FQL data types, including a list of available types. FQL supports static typing with optional typechecking.

Encode FQL types as JSON

When transmitting FQL data, the Fauna Core HTTP API encodes FQL data types as JSON using one of two data formats:

Tagged format: Tags JSON values with FQL type annotations, ensuring lossless typing.
Simple format: Lossy format that converts FQL values to their closest JSON type, without annotations or transformations.

The Core API’s Query endpoint uses the simple format by default.

For more information about data formats, see Wire protocol: Encode FQL as JSON.

Check a value’s type

Use the isa operator to check if a value is of a specific FQL type. For example:

"foo" isa String  // true

123 isa String    // false

123 isa Int       // true

0.123 isa Double  // true

123 isa Number    // true

0.123 isa Number  // true

{ a: "foo", b: "bar" } isa Object // true

[ 1, 2, 3 ] isa Array   // true

Product.all() isa Set   // true

// For documents, the type is the name
// of the collection. For example, `Product`
//collection documents have a type of `Product.`
Product.byName('limes').first() isa Product // true

// Document references also resolve to the
// document type.
Product.byId('111') isa Product // true

// Dangling references, which point to documents
// that don't exist, still resolve to the
// document type. For example, the following
// document doesn't exist.
Product.byId('999') isa Product // true

isa doesn’t support parameterized generic types, such as Ref<A> or Array<String>. Queries that attempt to use isa with such types return an invalid_query error:

// NOT SUPPORTED:
[ 1, 2, 3 ] isa Array<Number>

// NOT SUPPORTED:
Product.all() isa Set<Product>

// NOT SUPPORTED:
Product.byId('111') isa Ref<Product>

Persistable types

Persistable types have values that can be reliably stored, retrieved, and updated in a Fauna database. Documents can only store persistable values. FSL collection schema: Field definitions only allow persistable types.

Persistable types are:

Boolean
Date
Ref (document references), excluding references to named system collection documents
Null
Number, including Double, Int, and Long
String
Time
Array of other persistable types
Object of other persistable types
Tuple of other persistable types
Union of other persistable types

Scalar types

The scalar types are JSON serializable types that hold a single value. Types, including String, Date, and Time, are objects that have built-in methods and properties.

Boolean

A boolean data type has a boolean literal value of true or false.

Boolean variables and expressions can be compared explicitly or implicitly against a boolean literal. In the following example, the if statements are equivalent:

let a = true
if (a == true) {
  // expression
}

if (a) {
  // expression
}

Comparison operators return a boolean value:

let a = 10
let b = 20
a > b

false

Bytes

Reference: Bytes

A Bytes value stores a byte array, represented as a Base64-encoded string. You can use Bytes to store binary data in a Fauna database.

Date

Reference: Date

A date in the YYYY-MM-DD format, such as 2099-11-03.

A Date value is encoded as a string in responses.

Double

See Number.

ID

A 64-bit integer represented as a decimal number that uniquely identifies a resource.

Int

See Number.

Long

See Number.

Null

The Null type has the single value null.

Null is a marker used to indicate that a data value doesn’t exist. It is a representation of missing information, indicating a lack of a value, which differs from a value of zero.

To delete a document field, set the field value to null. The field is not saved after it is deleted. See document.update().

NullDoc

A marker used to indicate that a document doesn’t exist or is inaccessible.

The data type is taken from the collection’s name with the Null prefix. For example, a NullDoc for the Product collection has the NullProduct type.

NullDocs coalesce as a null value. Testing a NullDoc against a value of null returns true.

NullDoc is returned by the byId() or byName() queries and by links from another doc (id or coll) when the linked document doesn’t exist or is inaccessible.

The following lists NullDoc types for system collections:

NullDoc type Description Value

NullDoc type	Description	Value
`NullAccessProvider`	Returned type when an `AccessProvider` document doesn’t exist.	`null`
`NullCollectionDef`	Returned type when a `Collection` document, which has the CollectionDef type, doesn’t exist.	`null`
`NullCredential`	Returned type when a `Credential` document doesn’t exist.	`null`
`NullDatabaseDef`	Returned type when a `Database` document, which has the DatabaseDef type, doesn’t exist.	`null`
`NullFunctionDef`	Returned type when a `Function` document, which has the FunctionDef type, doesn’t exist.	`null`
`NullKey`	Returned type when a `Key` document doesn’t exist.	`null`
`NullRole`	Returned type when a `Role` document doesn’t exist.	`null`
`NullToken`	Returned type when a `Token` document doesn’t exist.	`null`

NullAccessProvider

Returned type when an AccessProvider document doesn’t exist.

null

NullCollectionDef

Returned type when a Collection document, which has the CollectionDef type, doesn’t exist.

null

NullCredential

Returned type when a Credential document doesn’t exist.

null

NullDatabaseDef

Returned type when a Database document, which has the DatabaseDef type, doesn’t exist.

null

NullFunctionDef

Returned type when a Function document, which has the FunctionDef type, doesn’t exist.

null

NullKey

Returned type when a Key document doesn’t exist.

null

NullRole

Returned type when a Role document doesn’t exist.

null

NullToken

Returned type when a Token document doesn’t exist.

null

Number

FQL has built-in types that represent numbers, which are summarized in the following table:

Type	Size, bits	Description	Range	Examples
Double	64	double-precision IEEE-754 floating point		1.1234 1.2e23
Int	32	Signed two’s complement integer	-2³¹ to 2³¹-1	10 -250 1_000_000
Long	64	Signed two’s complement integer	-2⁶³ to 2⁶³-1	922337036854775808 -9223372036854775808

Type

Size, bits

Description

Range

Examples

Double

double-precision IEEE-754 floating point

1.1234
1.2e23

Int

Signed two’s complement integer

-2³¹ to 2³¹-1

10
-250
1_000_000

Long

Signed two’s complement integer

-2⁶³ to 2⁶³-1

922337036854775808
-9223372036854775808

Underscores are permitted in numeric literals as separators to aid readability but have no other significance.

String

Reference: String

String literals are single-quoted string values or double-quoted interpolated string values from the FQL-supported character set.

Single-quoted strings can also include the " and # characters.

Double-quoted strings can also include the ' character.

Use \ to escape a character in a string.

Interpolated strings

Double-quoted strings support the interpolation of expressions in a string. Encode the interpolation string using the #{<expr>} character sequence, where <expr> is an FQL expression:

"Alice is #{3 + 2} years old."

evaluates to:

"Alice is 5 years old."

Heredoc strings

You can use heredoc strings for multiple lines of text that behave similarly to double-quoted strings.

A heredoc string is delimited by tokens that start with the << character sequence followed by a user-defined character and a line break. Conventionally, the token is uppercase characters. The same token terminates a heredoc string and is on a line by itself:

<<+STR
A multiline
string
STR

A heredoc string removes leading whitespace at the beginning of each line, removing the same number of characters in each line:

<<+STR
   A multiline string
     with leading
       whitespaces
STR

evaluates to:

<<-END
  A multiline string
    with leading
      whitespaces
END

Time

Reference: Time

The Time type is an instant in time expressed as a calendar date and time of day in UTC, in the range -999999999-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z

A Time value can store nanosecond precision.

Times can be inserted with offsets but are converted to UTC and the offset component is lost.

A Time value is encoded as a string in responses.

TransactionTime

Reference: TransactionTime

The TransactionTime type is the query transaction expressed as a calendar date and time of day in UTC, in the range -999999999-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z

A TransactionTime value can store nanosecond precision.

A Time value is encoded as a string in responses.

Uuid

Universally Unique IDentifier (UUID) uniquely identifies a resource.

Data reference types

The data reference types represent Fauna resources and have built-in methods and properties.

Collection

Reference: Collection

A Collection groups documents in a database.

CollectionDef

Reference: Collection

A Collection definition, represented as a Collection document. A collection definition is the FQL equivalent of an FSL collection schema.

Database

A database can have Collections, Documents, User-defined functions, security elements such as Keys, Tokens, Credentials, Access Providers, and child databases.

DatabaseDef

Reference: Database

A database definition, represented as a Database document.

Document

Reference: Document

A record in a Collection. You add documents to a collection as JSON-like objects. The document type is taken from the name of the collection of which the document is a member. For example, a document in the Product collection is of type Product, and if the requested document isn’t a member of the collection, the response type is NullProduct.

All documents have metadata fields.

Ref (Document reference)

Learn: Model relationships using document references

A reference to a Document. Can resolve to an existing document or a NullDoc.

Document references contain the document’s collection and document ID.

You can use document references to model relational data and create relationships between documents.

NamedRef

A reference to a Document in a named system collection. Can resolve to an existing document or a NullDoc.

In named collections, each document is uniquely identified by its name instead of a document ID. Named references contain the document’s collection and name.

Function

Reference: Function

A function is an FQL expression stored in a database.

FunctionDef

Reference: Function

A user-defined function (UDF) definition, represented as a Function document. A function definition is the FQL equivalent of an FSL function schema.

Advanced types

The advanced types represent complex objects or types that can hold multiple values. The iterable Array and Set types have built-in properties and methods.

Any

The Any type denotes a field that can be of any other type or might be not present.

Array

Reference: Array

The Array type is a comma-separated list of expressions enclosed by []. An Array can hold mixed types, including functions:

["a", 1 + 1, if (true) "true" else "false", null]

evaluates to:

[
  "a",
  2,
  "true",
  null
]

For array.map(), array.forEach(), and similar methods, Array literals are evaluated left to right.

The Array type is an iterable data structure that has an ordered collection of typed values. An Array:

can hold values of different types.
can be accessed only using positive integers.
is zero-indexed.
can’t contain more than 16,000 elements.

You can use a check constraint with array.distinct() to enforce distinct values within a document’s Array field. See Enforce unique values in an Array field.

Event Source

Reference: Event feeds and event streams

A string-encoded token representing an event source:

"g9WD1YPG..."

When tracked changes occur in a database, the event source emits a related event.

To create an event source, use an FQL query that calls set.eventSource() or set.eventsOn() to a supported Set.

You can use the token to consume the source’s events as an event feed or event stream.

For supported event source methods, see EventSource instance methods.

Iterable

The type of all iterable types:

Array type
Set type

Never

FQL method signatures use the Never type to represent a value that never occurs or the return value of a function that never returns.

See abort() for an example.

Module

The Module type is a singleton object that represents a grouping of functionality. Examples include Math, Query, and Function, and Collections.

A module gets serialized as an @mod value in the tagged format. Use the isa operator for testing a module type.

Object

The Object type is the type of all objects and represents a JSON-like object whose contents are a collection of key:value pairs. The keys must be strings and the values must be valid FQL data types. The value expressions are evaluated sequentially in the order defined, left to right. Objects evaluate to their contents. Objects can be combined to emulate abstract data types found in other functional languages.

Object subtypes:

Struct
Document

Object types may have zero or more field types and an optional wildcard field type.

Examples:

{ x: Number, y: Number } // object with two fields
{ kind: "dog" | "cat" | "bird", age: long }

The wildcard field type opens an object to arbitrary fields that correspond to the wildcard type:

// An object with one `long` field and any number of `string` fields
{ count: Long, *: String }

// An object with any number of arbitrary fields
{ *: Any }

You can use Object static methods to further transform objects.

Set

Reference: Set

A Set is an iterable group of values, typically representing documents in a collection.

Singleton

Every primitive value is also a Singleton type.

Strings: "foo" "bar"
Integers: 1 2 3 -99
Booleans: true or false
null

Singletons can be combined to emulate abstract data types found in other functional languages.

Struct

A Struct is a plain Object that isn’t a Document. The value returned from projection on a document is a Struct.

Tuple

Tuples are sequences of zero or more typed values:

[]                      // The empty tuple +
[string, string]        // tuple of two string values +
[boolean]               // tuple of one boolean value +
[string, long, boolean] // tuple of a string, long, and boolean +
[string[], long[]]      // tuple of an Array of strings and an Array of longs

Tuple values are subtypes of Arrays of the union of the tuple slot types:

[string, string]        // `string[]` +
[boolean]               // `boolean[]` +
[string, long, boolean] // `(string | long | boolean)[]`

Union

Union type allows values of any constituent types:

boolean | number       // all booleans and numbers +
{ x: number } | string // all the object types and strings

Unions can be combined to emulate abstract data types found in other functional languages:

{ type: "point", x: long, y: long } |
{ type: "circle", x: long x: long, radius: long }

Unlike TypeScript, FQL unions that include Any preserve both Any and the original types. Any does not subsume the other types. This allows for more precise type checking and errors. For example:

let foo: Any | Number = 2
foo // Returns `2` with a type of `Any | Number`

The stricter typechecking can impact behavior at runtime. For example, the following TypeScript compiles but would return an error at runtime:

const foo: any  = null;
const bar = (true) ? foo : 2;

// Attempts to access a property of
// null. TypeScript allows this.
bar.baz;

An equivalent FQL query returns an invalid_query error during typechecking:

let foo: Any = null
let bar = if (true) foo else 2

// Attempts to access a property of
// null. FQL returns an error.
bar.baz

Security-related types

The security data types are used with Fauna authentication and authorization APIs.

AccessProvider

Reference: Access providers

An AccessProvider document.

AccessProvider documents are FQL versions of a database’s FSL access provider schema. AccessProvider documents have the AccessProvider type. See Access providers.

Credential

Reference: Credential

A Credential object represents a Credential in a Fauna database.

Key

Reference: Key

A Key is a JSON object document subtype stored in a database Key collection that represents an Key. A key ensures anonymous access to a database to execute operations permitted by the role associated with the key.

Role

Reference: Role

A Role is a JSON object document subtype stored in a database Role collection that represents an Role.

Token

Reference: Token

Tokens are defined as documents in the Token collection, and are used to control identity-based access to a database.