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

The elements in the page.

after

The cursor for the next page, inclusive. Optional.

before

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

ref

Ref

The reference to the document.

action

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

ts

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

data

Varies based on the action.

Set events

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

Field Value Description

ref

Ref

The reference to the document.

action

Either add or remove.

ts

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

data

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.

  1. Number (integers and decimals: 0.5 < 1 < 1.5 < 2)

  2. Byte

  3. String

  4. Array (ordered lexically, like strings)

  5. Object (ordered lexically, like strings)

  6. Reference

  7. Timestamp

  8. Date

  9. Boolean (false < true)

  10. Null

Was this article helpful?

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

Thank you for your feedback!