Check out v4 of the Fauna CLI
v4 of the Fauna CLI is now in beta. The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start. |
Types
This section lists the FQL data types. FQL supports static typing.
Not all types are representable in JSON. FQL handles values similar to GraphQL where non-JSON types are downcast to a JSON equivalent, which can then be used as-is or recast client-side to a richer type.
Type representation summary:
-
JSON representable values are rendered verbatim.
-
Non-JSON scalar values are reduced to a JSON-compatible representation.
-
Document objects are reduced to JSON objects that include all the fields.
-
Nested documents aren’t expanded.
-
Sets are reduced to the first page of the set, which is equivalent to calling
.paginate()
without arguments. The query response includesbefore
andafter
page references as applicable. -
Singleton objects are reduced to string descriptions.
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:
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
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.
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 |
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.
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 |
---|---|---|
Returned type when an |
|
|
Returned type when a |
|
|
Returned type when a |
|
|
Returned type when a |
|
|
Returned type when a |
|
|
Returned type when a |
|
|
Returned type when a |
|
|
Returned type when a |
|
Number
FQL has built-in types that represent numbers, which are summarized in the following table:
Type | Size, bits | Description | Range | Examples |
---|---|---|---|---|
64 |
double-precision IEEE-754 floating point |
1.1234 |
||
32 |
Signed two’s complement integer |
-231 to 231-1 |
10 |
|
64 |
Signed two’s complement integer |
-263 to 263-1 |
922337036854775808 |
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.
Data reference types
The data reference types represent Fauna resources and have built-in methods and properties.
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.
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 |
---|
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
.
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.
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.
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.
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:
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 }
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
orfalse
-
null
Singletons can be combined to emulate abstract data types found in other functional languages.
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 |
---|
AccessProvider
documents are FQL versions of a database’s FSL
access provider schema.
AccessProvider
documents have the AccessProvider type. See
Access providers.
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.
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!