Expressions

An expression is a piece of FQL code that produces a value.

Expressions appear throughout a query: on the right side of LET and VAR, inside RETURN, in function arguments, conditions, filters, object fields, array items, and other places where a value is expected.

example.fql Ferret v2

query.fql

FQL

LET name = "Ada" LET active = true LET roles = ["admin", "editor"] RETURN { name: name, active: active, roleCount: LENGTH(roles) }

In this example, "Ada", true, ["admin", "editor"], name, active, and LENGTH(roles) are all expressions.

Where expressions are used

Expressions can be used anywhere FQL expects a value.

Common examples include:

variable assignments
return values
function arguments
array items
object field values
filter conditions
loop inputs
conditional branches

example.fql Ferret v2

query.fql

FQL

LET users = [ { name: "Ada", age: 36, active: true }, { name: "Grace", age: 42, active: false }, { name: "Linus", age: 31, active: true } ] FOR user IN users FILTER user.active && user.age >= 35 RETURN { name: user.name, label: CONCAT(user.name, " is active") }

The query uses expressions in several different positions:

users is the input expression for the FOR loop.
user.active && user.age >= 35 is the filter expression.
user.name is an object field value expression.
CONCAT(user.name, " is active") is a function call expression.

Literal expressions

A literal expression writes a value directly in the query.

example.fql Ferret v2

query.fql

FQL

RETURN { none: NONE, boolean: true, number: 42, string: "hello", array: [1, 2, 3], object: { name: "Ada" } }

Literals are the most direct way to create basic values.

For the complete list of built-in value types, see the Values and Types section.

Variable references

A variable reference is an expression that reads the value of a variable.

example.fql Ferret v2

query.fql

FQL

LET name = "Ada" LET greeting = CONCAT("Hello, ", name) RETURN greeting

The expression name evaluates to the value assigned by the earlier LET statement.

Variables are resolved from the current scope. A variable can only be referenced after it has been declared in a scope where it is visible.

Property access

Property access reads a field from an object or runtime-backed value.

example.fql Ferret v2

query.fql

FQL

LET user = { name: "Ada", profile: { city: "London" } } RETURN user.profile.city

Property access can be chained when nested values are being read.

For objects, the accessed property is matched by name. For runtime-backed values, the behavior depends on the value and the runtime that provides it.

Indexed access

Indexed access reads an item from a value by position or key.

example.fql Ferret v2

query.fql

FQL

LET users = ["Ada", "Grace", "Linus"] RETURN users[0]

Indexes are expressions too:

example.fql Ferret v2

query.fql

FQL

LET users = ["Ada", "Grace", "Linus"] LET index = 1 RETURN users[index]

Indexed access is commonly used with arrays. Host values may also support indexed access if the runtime defines that behavior.

Operators

Operators combine expressions into larger expressions.

example.fql Ferret v2

query.fql

FQL

LET price = 100 LET quantity = 3 RETURN price * quantity >= 250

The expression price * quantity produces a number, and comparing it with >= 250 produces a boolean.

See the Operators section for the full list of supported operators and precedence rules.

Function calls

A function call is an expression that invokes a function and produces its result.

example.fql Ferret v2

query.fql

FQL

LET firstName = "Ada" LET lastName = "Lovelace" RETURN CONCAT(UPPER(firstName), " ", UPPER(lastName))

Function arguments are expressions too. The inner calls to UPPER are evaluated and passed as arguments to CONCAT.

For details on function declarations and calls, see the Functions section.

Collection expressions

A collection expression creates an array or object value.

example.fql Ferret v2

query.fql

FQL

LET first = "Ada" LET second = "Grace" RETURN [first, second, "Linus"]

example.fql Ferret v2

query.fql

FQL

LET name = "Ada" LET active = true RETURN { name: name, active: active, label: CONCAT(name, " is active") }

Array items and object field values are expressions. They are evaluated in order and stored in the resulting collection.

Collections can contain any value type, including nested arrays and objects.

example.fql Ferret v2

query.fql

FQL

RETURN [ { name: "Ada", roles: ["admin", "editor"] }, { name: "Grace", roles: ["viewer"] } ]

Object field names become property names in the resulting object.

Conditional expressions

A conditional expression selects a value based on a condition, using the ternary operator.

example.fql Ferret v2

query.fql

FQL

LET user = { name: "Ada", active: true } RETURN user.active ? "active" : "inactive"

The condition is evaluated first. If it is true, the first branch is used. Otherwise, the second branch is used. Both branches are expressions.

See the Ternary Operator section for the full syntax, including the shortcut form.

Subquery expressions

Some query constructs can produce values and be used as expressions.

example.fql Ferret v2

query.fql

FQL

LET users = [ { name: "Ada", active: true }, { name: "Grace", active: false }, { name: "Linus", active: true } ] LET activeUsers = ( FOR user IN users FILTER user.active RETURN user.name ) RETURN activeUsers

Nested query blocks can also be used this way:

example.fql Ferret v2

query.fql

FQL

LET products = ( FOR i IN 1..5 FOR x IN 1..5 RETURN i * x ) RETURN products

A subquery expression evaluates a query block and uses its result as a value. This allows a query result to be assigned to a variable, returned as part of another value, or passed to a function.

See Subquery Expressions for more, including nesting and indexing.

Expressions and statements

Expressions produce values.

Statements describe query structure, control flow, or variable declarations.

For example, LET is a statement. The code on the right side of = is an expression:

example.fql

read-only

LET total = price * quantity

RETURN is also a statement. The value after RETURN is an expression:

example.fql Ferret v2

query.fql

FQL

RETURN total >= 250

Only the expression parts of a statement can be nested inside other expressions.

Evaluation

Expressions are evaluated when the surrounding statement or expression is evaluated.

example.fql Ferret v2

query.fql

FQL

LET users = [ { name: "Ada", active: true }, { name: "Grace", active: false } ] FOR user IN users RETURN { name: user.name, active: user.active }

In this query, the object expression after RETURN is evaluated once for each item produced by the loop.

Expression evaluation follows the structure of the query. Nested expressions are evaluated as needed to produce the value of the outer expression.