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.

Operators

This section describes the FQL operators. See Operator precedence for the operator precedence and associativity table.

Assignment

Operator Syntax Description

=

variable [:type] = value

Simple assignment operator assigns the value to the declared variable.

The optional :type notation constrains a value to the given type, where type is one of the supported Types. For example,
let x:String = "5"
is a valid statement, whereas
let x:String = 5
results in an invalid_query error.

Arithmetic

The arithmetic operators perform arithmetic operations on numeric operands.

Operator Syntax Description

+

operand1 + operand2

Addition, sums the operands.

-

operand1 - operand2

Subtraction, subtracts operand2 from operand1.

*

operand1 * operand2

Multiplication, multiplies the operands.

/

operand1 / operand2

Division, divides operand1 by operand2.

%

operand1 % operand2

Modulo, returns the remainder of operand1 divided by operand2 and takes the sign of the dividend.

**

operand1 ** operand2

Exponentiation, returns the result of raising operand1 to the power of operand2.

Concatenation

The plus operator performs concatenation on sting operands.

Operator Syntax Description

+

operand1 + operand2

For String operands, concatenates the operands, left-to-right.

Comparison

Comparison operators return a Boolean value.

For the <, >, ⇐, and >= operators, comparison across types always returns false and comparing non-comparable objects always returns false.

Operator Syntax Description

==

expression1 == expression2

Equal to. Returns true if expression1 and expression2 have the same value. Otherwise, returns false.

  • When comparing documents, only the document id metadata fields are compared and all other fields are ignored.

  • Sets are equal if they have the same elements and the elements are in the same order.

!=

expression1 != expression2

Not equal to. Returns true if expression1 and expression2 do not have the same value. Otherwise, returns false.

>

expression1 > expression2

Greater than. Returns true if expression1 is greater than expression2.

  • Comparison across types returns false.

  • Comparison of non-comparable objects, such as anonymous functions and Set cursors, returns false.

  • Comparing Sets isn’t supported but a Set can be converted to an Array and then compared. See set.toArray().

>=

expression1 >= expression2

Greater than or equal to. Returns true if expression1 is greater than or equal to expression2.

  • Comparison across types returns false.

  • Comparison of non-comparable objects, such as anonymous functions and Set cursors, returns false.

  • Comparing Sets isn’t supported but a Set can be converted to an Array and then compared. See set.toArray().

<

expression1 < expression2

Less than. Returns true if expression1 is less than expression2.

  • Comparison across types returns false.

  • Comparison of non-comparable objects, such as anonymous functions and Set cursors, returns false.

  • Comparing Sets isn’t supported but a Set can be converted to an Array and then compared. See set.toArray().

<=

expression1 <= expression2

Less than or equal to. Returns true if expression1 is less than or equal to expression2.

  • Comparison across types returns false.

  • Comparison of non-comparable objects, such as anonymous functions and Set cursors, returns false.

  • Comparing Sets isn’t supported but a Set can be converted to an Array and then compared. See set.toArray().

isa

expression1 isa <type>

Evaluate if expression1 is of type <type>, which can be any of the supported runtime Types. The <type> must be a module object.
Example: "1" isa String returns true

Logical

Logical operators return a Boolean value.

Operator Syntax Description

||

operand1 || operand2

Logical OR. Returns true if one of the operands is true. Otherwise, returns false.

&&

operand1 && operand2

Logical AND. Returns true if the operands are true. Otherwise, returns false.

Bitwise operators

Operator Syntax Description

|

expression1 | expression2

Bitwise inclusive OR:

expression1 expression2 expression1 | expression2

0

0

0

0

1

1

1

0

1

1

1

1

^

expression1 ^ expression2

Bitwise exclusive OR (XOR):

expression1 expression2 expression1 ^ expression2

0

0

0

0

1

1

1

0

1

1

1

0

&

expression1 & expression2

Bitwise AND:

expression1 expression2 expression1 & expression2

0

0

0

0

1

0

1

0

0

1

1

1

Unary

Operator Syntax Description

-

-operand
- operand

Unary negation. Negates the operand it precedes.

!

!operand

Logical negation (NOT). Inverts the value of the Boolean operand and returns a Boolean value.

Examples:

Unary negation variations:

-5 // -5. A negative literal, not unary negation.

- 5 // -5. Unary negation applied to a literal.

let num = 5
-num // -5. Unary negation of a variable.

Insert a space between - and operand if operand is a literal Number.

Logical NOT:

!false // true

Optional chaining

Operator Syntax Description

?.

object.value?.field

object.method?.(args)

Optional chaining. When accessing a field or invoking a method, if the left side of the expression evaluates to null, return null.

Examples:

let customer = {
  name: "Alice Appleseed",
  address: {
    state: "DC"
  }
}

customer.address?.state

The optional chaining operator can also be used with methods:

let customer = {
  name: "Alice Appleseed",
  address: {
    state: "DC"
  }
}

customer.name?.toLowerCase()

Null coalescing

Operator Syntax Description

??

expression1 ?? expression2

Null coalescing. If expression1 evaluates to null, return the expression2 result. Otherwise, return the expression1 result.

Example:

// Gets a `Customer` collection document.
let customer = Customer.byEmail("carol.clark@example.com").first()

// This customer's `cart` field is `null`.
customer?.cart ?? "Not found" // returns "Not found"

Non-null assertion postfix

Operator Syntax Description

!

expression!

Non-null assertion postfix. Runtime validation: if expression evaluates to null, return an error. Otherwise, return the result.

Example:

let customer = {
  name: "Alice Appleseed",
  address: {
    state: "DC"
  }
}

customer.date! // Returns an error.

Ternary operator

FQL doesn’t have a ternary (conditional) operator. You can get the same result using an if …​ else statement. For example, to perform an upsert:

// Customer email to look up
let email = "alice.appleseed@example.com"

// Customer data to upsert
let data = {
  name: "Alice Appleseed",
  email: "alice.appleseed@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    postalCode: "20220",
    country: "US"
  }
}

// Try to find the existing customer by email.
// If the customer doesn't exist, returns `null`.
let customer = Customer.byEmail(email).first()

// Create or update the customer
// based on existence.
if (customer == null) {
  Customer.create(data)
} else {
  customer!.update(data)
}

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!