Data types

FQL uses an enhanced Javascript Object Notation (JSON) format for storing and communicating data. JSON is a human and machine-readable open standard that facilitates data interchange. All of JSON’s basic types are supported, including Number, String, Boolean values, as well as Array and Object.

Basic types

Type Description

Boolean

The boolean data type can only store true or false values. These can be directly compared for equality or inequality. They can also be compared to the Boolean literal values of true and false.

{ my_boolean: true }

Null

Null is a special marker used to indicate that a data value does not exist. It is a representation of missing information, indicating a lack of a value. A lack of a value is not the same thing as a value of zero, in the same way that a lack of an answer is not the same thing as an answer of "no".

Null is a value that can be directly compared for application programmer simplicity.
This means that Null == Null returns true.

{ my_null: null }

Number

Numbers can be 64-bit signed two’s complement integers (long ints), or 64-bit double-precision floating point values (doubles); the representation is controlled, or influenced, by a driver’s host language.

Valid numbers include 3, -27, 3.1415. Neither infinity nor NaN are allowed.

JavaScript does not distinguish between integer and floating point numbers as you might expect, storing numbers as floats internally, and treating them as integers in many contexts.

If your client applications involve JavaScript, or you are using the Web Shell or fauna-shell (which are both implement in JavaScript), and your queries depend on the distinction between integers and floats, be sure to use the conversion functions ToDouble and ToInteger as necessary.

Functions that operate on numbers:

`Abs`	Returns the absolute value of a number.
`Acos`	Returns the arc cosine of a number.
`Add`	Returns the sum of one or more numbers.
`Asin`	Returns the arc sine of a number.
`Atan`	Returns the arc tangent of a number.
`BitAnd`	Returns the bitwise AND of one or more numbers.
`BitNot`	Returns the bitwise AND of one or more numbers.
`BitOr`	Returns the bitwise OR of one or more numbers.
`BitXor`	Returns the bitwise exclusive-OR of one or more numbers.
`Ceil`	Returns an integer that is greater than, or equal to, a number.
`Cos`	Returns the cosine of a number.
`Cosh`	Returns the hyperbolic cosine of a number.
`Count`	Counts the items in an array or set.
`Degrees`	Converts a number from radians to degrees.
`Divide`	Returns the quotient of two or more numbers.
`Exp`	Returns e raised to the power of a number.
`Floor`	Returns an integer that is less than, or equal to, a number.
`Hypot`	Returns the length of a hypotenuse of a right triangle, given the lengths of the other two sides.
`Ln`	Returns the natural logarithm (base e) of a number.
`Log`	Returns the natural logarithm (base 10) of a number.
`Max`	Returns the largest value in a list of numbers.
`Mean`	Returns the average value of the items in an array or set.
`Min`	Returns the smallest value in a list of numbers.
`Modulo`	Returns the remainder after dividing a list of numbers.
`Multiply`	Returns the product of a list of numbers.
`Pow`	Returns the value of a number raised to an exponent.
`Radians`	Converts a number from degrees to radians.
`Round`	Returns the integer that is closest to a number.
`Sign`	Returns 1, 0, or -1 to indicate the sign of a number.
`Sin`	Returns the sine of a number.
`Sinh`	Returns the hyperbolic sine of a number.
`Sqrt`	Returns the square root of a number.
`Subtract`	Returns the difference of a list of numbers.
`Sum`	Sums the items in an array or set.
`Tan`	Returns the tangent of a number.
`Tanh`	Returns the hyperbolic tangent of a number.
`Trunc`	Truncates a number to the specified decimal places.

String

String data types store any letters, numbers, whitespaces, and/or symbols in a fixed order.

FQL accepts and communicates strings as UTF-8 encoded strings. For string functions, any arguments or returned values which utilize offsets and lengths operate using code points.

Functions that operate on strings:

`Casefold`	Converts a string into a case-normalized string.
`Concat`	Combines a list of strings into a single string.
`ContainsStr`	Tests whether a string contains a specific string.
`ContainsStrRegex`	Tests whether a string contains a specific pattern.
`EndsWith`	Tests whether a string ends with a specific string.
`FindStr`	Searches for a string within a string.
`FindStrRegex`	Searches for a regex pattern within a string.
`Format`	Formats arguments as a string according to a string of format specifiers.
`LTrim`	Removes all whitespace from the start of a string.
`Length`	Returns the length in codepoints of a string.
`LowerCase`	Converts a string to all lowercase.
`RTrim`	Removes all whitespace from the end of a string.
`RegexEscape`	Creates a regular expression that matches the input string verbatim.
`Repeat`	Creates a new string by repeating a string multiple times.
`ReplaceStr`	Replaces a portion of a string with another string.
`ReplaceStrRegex`	Replaces a pattern in a string with another string.
`Space`	Creates a whitespace string of the specified size.
`StartsWith`	Tests whether a string starts with a specific string.
`SubString`	Returns a portion of a string.
`TitleCase`	Converts a string to use TitleCase.
`Trim`	Removes all whitespace from the start and end of a string.
`UpperCase`	Converts a string to all uppercase.

Literal

A literal is a constant value for a given data type. Boolean, Number, String, and Null all evaluate to their associated type:

true, false   // Boolean
1, 2          // Number
3.4, 1.2e10   // Number
"a", "b"      // String
null          // Null

Array

An Array is a data structure that contains a group of elements. When an Array is used in FQL, it evaluates to its contents.

client.Query(
    Arr(1, 2, Concat(Arr("Hen ", "Wen")))
);

System.out.println(
    client.query(
        Arr(
            Value(1),
            Value(2),
            Concat(Arr(Value("Hen "), Value("Wen")))
        )
    ).get());

result, err := client.Query(
	f.Arr{
		1, 2, f.Concat(f.Arr{"Hen ", "Wen"}),
	})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

client.query(Arr(1, 2, Concat(Arr("Hen ", "Wen"))))

result = client.query(
  [1, 2, q.concat(["Hen ", "Wen"])]
)
print(result)

client.query(
  [1, 2, q.Concat(['Hen ', 'Wen'])]
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

Arr(LongV(1), LongV(2), StringV(Hen Wen))

[1, 2, "Hen Wen"]

[1 2 Hen Wen]

[ 1, 2, "Hen Wen" ]

[ 1, 2, "Hen Wen" ]

[ 1, 2, 'Hen Wen' ]

Functions that operate on arrays:

`All`	Tests whether all of the provided values are true.
`Any`	Tests whether any of the provided values are true.
`Append`	Adds items to end of array.
`Count`	Counts the items in an array or set.
`Difference`	Returns an array of items in one array that are missing from additional arrays.
`Distinct`	Returns an array of the distinct items within multiple arrays.
`Drop`	Removes items from start of array.
`Filter`	Fetches specific items from array.
`Foreach`	Iterates over array items.
`Intersection`	Returns an array of the items that exist in all arrays.
`IsEmpty`	Tests whether an array or set is empty.
`IsNonEmpty`	Tests whether an array or set contains items.
`Map`	Applies a function to all array items.
`Max`	Returns the largest value in a list of numbers.
`Mean`	Returns the average value of the items in an array or set.
`Min`	Returns the smallest value in a list of numbers.
`Prepend`	Adds items to start of array.
`Reduce`	Reduce an array or set to a result via a lambda function.
`Reverse`	Reverses the order of the items in an array.
`Select`	Retrieves a specific field value from a document.
`SelectAll`	Retrieves all values for a specific field from a document.
`Sum`	Sums the items in an array or set.
`Take`	Fetches items from start of array.
`ToObject`	Converts an array to an object.
`Union`	Returns an array that combines the items in multiple arrays.

Object

The Object type represents a JSON-like object, where its values 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 that they were specified, left to right. Objects evaluate to their contents:

client.Query(
    Obj("name", "Hen Wen", "age", Add(100, 10))
);

System.out.println(
    client.query(
        Obj(
            "name", Value("Hen Wen"),
            "age", Add(Value(100), Value(10))
        )
    ).get());

result, err := client.Query(
	f.Obj{"name": "Hen Wen", "age": f.Add(100, 10)})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

client.query(Obj("name" -> "Hen Wen", "age" -> Add(100, 10)))

result = client.query(
  {
    "name": "Hen Wen",
    "age": q.add(100, 10)
  }
)
print(result)

client.query(
  { name: 'Hen Wen', age: q.Add(100, 10) }
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

ObjectV(name: StringV(Hen Wen),age: LongV(110))

{name: "Hen Wen", age: 110}

map[age:110 name:Hen Wen]

{ "name": "Hen Wen", "age": 110 }

{ "name": "Hen Wen", "age": 110 }

{ name: 'Hen Wen', age: 110 }

Functions that operate on objects:

`Merge`	Merge two objects into one, with an optional resolver lambda.
`Select`	Retrieves a specific field value from a document.
`SelectAll`	Retrieves all values for a specific field from a document.
`ToArray`	Converts an object to an array.

Special types

In addition to the basic types, FQL supports the following types beyond those native to JSON:

Type Description

Byte

The Bytes type denotes a Base64-encoded string representing a byte array.

client.Query(
    new byte[] { 0x1, 0x2, 0x3 }
);

System.out.println(
    client.query(
        Value(new byte[]{ 0x1, 0x2, 0x3 })
    ).get());

result, err := client.Query(
	f.BytesV{0x1, 0x2, 0x3})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

client.query(Array[Byte](0x1, 0x2, 0x3))

result = client.query(
  bytearray(b'\x01\x02\x03')
)
print(result)

client.query(
  new Uint8Array([0x1, 0x2, 0x3])
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

BytesV(0x01, 0x02, 0x03)

[0x01 0x02 0x03]

[1 2 3]

[0x01 0x02 0x03]

bytearray(b'\x01\x02\x03')

Bytes("AQID")

Date

The Date type denotes a date, with no associated time zone.

client.Query(
    Date("1970-01-01")
);

System.out.println(
    client.query(
        Date(Value("1970-01-01"))
    ).get());

result, err := client.Query(
	f.Date("1970-01-01"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

client.query(Date("1970-01-01"))

result = client.query(
  q.date("1970-01-01")
)
print(result)

client.query(
  q.Date('1970-01-01')
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

FaunaDate(1970-01-01 12:00:00 AM)

1970-01-01

{0 62135596800 <nil>}

1970-01-01

1970-01-01

Date("1970-01-01")

Functions that operate on times or dates:

`Date`	Converts an ISO-8601 string into a Date.
`DayOfMonth`	Returns the day of the month from a timestamp.
`DayOfWeek`	Returns the day of the week from a timestamp.
`DayOfYear`	Returns the day of the year from a timestamp.
`Epoch`	Creates a timestamp from an offset since 1970-01-01 in seconds, milliseconds, microseconds, or nanoseconds.
`Hour`	Returns the hour from a timestamp.
`Minute`	Returns the minute from a timestamp.
`Month`	Returns the month from a timestamp.
`Now`	Returns a timestamp representing the current transaction time.
`Second`	Returns the second from a timestamp.
`Time`	Converts `now`, or an ISO-8601 string, into a timestamp.
`TimeAdd`	Adds an offset to a provided timestamp/date.
`TimeDiff`	Returns the difference between two timestamps/dates, in specified units.
`TimeSubtract`	Subtracts an offset from a provided timestamp/date.
`Year`	Returns the year from a timestamp.

Page

A Page contains an array of results and other decorated elements. In some cases the entire result set may not fit into the array, so other fields (the cursor fields) allow you to walk the results set in blocks (like pages in a book). The cursor fields retrieve blocks of results before or after the current page of results. When Pages are passed to functions that accept arrays, only the array element of the Page is examined or transformed. Other elements of the Page, such as the cursor, remain unaffected and are passed directly through to the output.

Field Type Description

data

Array

The elements in the page.

after

Cursor

The cursor for the next page, inclusive. Optional.

before

Cursor

The cursor for the previous page, exclusive. Optional.

Functions that operate on pages:

`All`	Tests whether all of the provided values are true.
`Any`	Tests whether any of the provided values are true.
`Append`	Adds items to end of array.
`Count`	Counts the items in an array or set.
`Difference`	Returns an array of items in one array that are missing from additional arrays.
`Distinct`	Returns an array of the distinct items within multiple arrays.
`Drop`	Removes items from start of array.
`Filter`	Fetches specific items from array.
`Foreach`	Iterates over array items.
`Intersection`	Returns an array of the items that exist in all arrays.
`IsEmpty`	Tests whether an array or set is empty.
`IsNonEmpty`	Tests whether an array or set contains items.
`Map`	Applies a function to all array items.
`Max`	Returns the largest value in a list of numbers.
`Mean`	Returns the average value of the items in an array or set.
`Min`	Returns the smallest value in a list of numbers.
`Prepend`	Adds items to start of array.
`Reduce`	Reduce an array or set to a result via a lambda function.
`Reverse`	Reverses the order of the items in an array.
`Select`	Retrieves a specific field value from a document.
`SelectAll`	Retrieves all values for a specific field from a document.
`Sum`	Sums the items in an array or set.
`Take`	Fetches items from start of array.
`ToObject`	Converts an array to an object.
`Union`	Returns an array that combines the items in multiple arrays.

Query

The Query type denotes a query expression object.

Ref

The Ref type denotes a resource reference. Refs may be extracted from documents, or constructed using the Collection, Database, Function, Index, or Role functions, or the general-purpose Ref function.

client.Query(
    Select("ref", Get(Collection("spells")))
);

result, err := client.Query(
	f.Select("ref", f.Get(f.Collection("spells"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

System.out.println(
    client.query(
        Select(Value("ref"), Get(Collection("spells")))
    ).get());

client.query(
  q.Select('ref', q.Get(q.Collection('spells')))
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

result = client.query(
  q.select("ref", q.get(q.collection("spells")))
)
print(result)

println(Await.result(
  client.query(
    Select("ref", Get(Collection("spells")))
  ),
  5.seconds
))

RefV(id = "spells", collection = RefV(id = "collections"))

{spells 0xc00008e300 0xc00008e300 <nil>}

ref(id = "spells", collection = ref(id = "collections"))

Collection("spells")

Ref(id=spells, collection=Ref(id=collections))

ref(id = "spells", collection = ref(id = "collections"))

client.Query(
    Ref(Collection("spells"), "1")
);

System.out.println(
    client.query(
        Ref(Collection(Value("spells")), Value(1))
    ).get());

result, err := client.Query(
	f.Ref(f.Collection("spells"), "1"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

println(Await.result(
  client.query(
    Ref(Collection("spells"), "1")
  ),
  5.seconds
))

result = client.query(
  q.ref(q.collection("spells"), "1")
)
print(result)

client.query(
  q.Ref(q.Collection('spells'), '1')
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

RefV(id = "1", collection = RefV(id = "spells", collection = RefV(id = "collections")))

ref(id = "1", collection = ref(id = "spells", collection = ref(id = "collections")))

{1 0xc000164150 0xc000164150 <nil>}

ref(
  id = "1",
  collection = ref(
    id = "spells",
    collection = ref(
      id = "collections"
    )
  )
)

Ref(id=1, collection=Ref(id=spells, collection=Ref(id=collections)))

Ref(Collection("spells"), "1")

Set

The Set type denotes a set identifier. A set is a group of tuples, typically representing resources or index terms, that are in a specific order.

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

System.out.println(
    client.query(
        Match(
            Index(Value("spells_by_element")),
            Value("fire")
        )
    ).get());

result, err := client.Query(
	f.MatchTerm(f.Index("spells_by_element"), "fire"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

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

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

client.query(
  q.Match(q.Index('spells_by_element'), 'fire')
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

SetRefV(System.Collections.Generic.Dictionary`2[System.String,FaunaDB.Types.Value])

{@set = {match: ref(id = "spells_by_element", collection = ref(id = "indexes")), terms: "fire"}}

{map[match:{spells_by_element 0xc0000bf290 0xc0000bf290 <nil>} terms:fire]}

{
  @set = {
    match: ref(
      id = "spells_by_element",
      collection = ref(id = "indexes")
    ),
    terms: "fire"
  }
}

SetRef({'match': Ref(id=spells_by_element, collection=Ref(id=indexes)), 'terms': 'fire'})

Match(Index("spells_by_element"), "fire")

Functions that operate on sets:

`All`	Tests whether all of the provided values are true.
`Any`	Tests whether any of the provided values are true.
`Count`	Counts the items in an array or set.
`Difference`	Returns the set of items in one set that are missing from additional sets.
`Distinct`	Returns the set of distinct items within a set.
`Events`	Returns the set of events describing the history of a set or document.
`Filter`	Fetches specific items from a set.
`Intersection`	Returns the set of items that exist in all sets.
`IsEmpty`	Tests whether an array or set is empty.
`IsNonEmpty`	Tests whether an array or set contains items.
`Join`	Combines the items in a set with set’s indexed values.
`Match`	Returns the set of items that match search terms.
`Max`	Returns the largest value in a list of numbers.
`Mean`	Returns the average value of the items in an array or set.
`Min`	Returns the smallest value in a list of numbers.
`Range`	Returns a subset of a set, in the specified range.
`Reduce`	Reduce an array or set to a result via a lambda function.
`Reverse`	Reverses the order of the items in a set.
`Singleton`	Returns a set containing the first item of a set.
`Sum`	Sums the items in an array or set.
`Union`	Returns a set that combines the items in multiple sets.

Timestamp

The Timestamp type (usually written as ts) stores an instant in time expressed as a calendar date and time of day in UTC.

A Timestamp can safely store nanosecond precision, but be careful as many operating system clocks provide only microsecond precision.

Timestamps may be inserted with offsets, but are converted to UTC; the offset component is lost.

A Timestamp must be within the range -999999999-01-01T00:00:00Z - 9999-12-31T23:59:59.999999999Z.

A document’s ts field represents the most recent event that modified the document.

client.Query(
    Time("1970-01-01T00:00:00Z")
);

System.out.println(
    client.query(
        Time(Value("1970-01-01T00:00:00Z"))
    ).get());

result, err := client.Query(
	f.Time("1970-01-01T00:00:00Z"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

client.query(Time("1970-01-01T00:00:00Z"))

result = client.query(
  q.time("1970-01-01T00:00:00Z")
)
print(result)

client.query(
  q.Time('1970-01-01T00:00:00Z')
)
.then((ret) => console.log(ret))
.catch((err) => console.error('Error: %s', err))

FaunaTime(1970-01-01T00:00:00Z)

1970-01-01T00:00:00Z

{0 62135596800 <nil>}

1970-01-01T00:00:00Z

FaunaTime('1970-01-01T00:00:00Z')

Time("1970-01-01T00:00:00Z")

Functions that operate on times or dates:

`Date`	Converts an ISO-8601 string into a Date.
`DayOfMonth`	Returns the day of the month from a timestamp.
`DayOfWeek`	Returns the day of the week from a timestamp.
`DayOfYear`	Returns the day of the year from a timestamp.
`Epoch`	Creates a timestamp from an offset since 1970-01-01 in seconds, milliseconds, microseconds, or nanoseconds.
`Hour`	Returns the hour from a timestamp.
`Minute`	Returns the minute from a timestamp.
`Month`	Returns the month from a timestamp.
`Now`	Returns a timestamp representing the current transaction time.
`Second`	Returns the second from a timestamp.
`Time`	Converts `now`, or an ISO-8601 string, into a timestamp.
`TimeAdd`	Adds an offset to a provided timestamp/date.
`TimeDiff`	Returns the difference between two timestamps/dates, in specified units.
`TimeSubtract`	Subtracts an offset from a provided timestamp/date.
`Year`	Returns the year from a timestamp.

Events

Strictly speaking, events aren’t types; they are objects that capture the temporal history of documents by tracking all create, update, and delete operations, as snapshots, over a document’s timeline. However, they have a common structure:

Document events

Field Value Description

Field	Value	Description
`ref`	Ref	The reference to the document.
`action`	String	Either "create","update" or "delete".
`ts`	Number	An integer value representing a UNIX timestamp, with microsecond resolution, at which the event occurred.
`data`	Object	Varies based on the action.

ref

Ref

The reference to the document.

action

String

Either "create","update" or "delete".

ts

Number

An integer value representing a UNIX timestamp, with microsecond resolution, at which the event occurred.

data

Object

Varies based on the action.

Set events

Set events are represented by an object returned when paginating through an index.

Field Value Description

Field	Value	Description
`ref`	Ref	The reference to the document.
`action`	String	Either `add` or `remove`.
`ts`	Timestamp	An integer value representing a UNIX timestamp, with microsecond resolution, at which the event occurred.
`data`	Object	Exactly as defined by the index’s `terms` field.

ref

Ref

The reference to the document.

action

String

Either add or remove.

ts

Timestamp

An integer value representing a UNIX timestamp, with microsecond resolution, at which the event occurred.

data

Object

Exactly as defined by the index’s terms field.

Precedence

Types have an order of precedence. When comparing values of different types, they are ranked in the following order, from least to greatest.

Number (integers and decimals: 0.5 < 1 < 1.5 < 2)
Byte
String
Array (ordered lexically, like strings)
Object (ordered lexically, like strings)
Reference
Timestamp
Date
Boolean (false < true)
Null

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!

Data types

Basic types

Special types

Events

Document events

Set events

Precedence

Keyboard shortcuts

While reading

While searching

URL fragments