Basic types

FQL has nine built-in value types:

Ferret hosts may also define additional value types — documents, elements, HTTP responses, files, handles, database connections, and other external resources. These are called host values and are covered separately in Host Values.

none

none is Ferret’s equivalent of null, nil, or None in other languages.

It represents the absence of a value.

none is a real value in FQL. It can be assigned to variables, placed inside arrays and objects, returned from functions, and compared with other values.

Unlike SQL null, comparing with none does not automatically produce another none.

none is useful when a value is intentionally absent:

It is useful when that absence needs to remain distinct from ordinary values such as false, 0, "", [], or {}.

Booleans

Boolean values represent truth values.

FQL has two boolean values:

• true
• false

Booleans are commonly produced by comparison operators, logical operators, predicates, and conditions.

Boolean values can be combined with logical operators:

Numbers

FQL uses the number type for numeric values. Numbers can be written as integers or decimals:

Numbers support arithmetic operations:

They can also be compared:

Numbers are ordered by numeric value:

• 1 < 2
• 10 > 2
• -1 < 0

Numeric-looking strings are still strings. FQL does not treat "10" as the same value as 10.

Use explicit conversion functions when a script needs to turn text into a number or a number into text. For example, to_number("10") - 2 returns 8, while "10" - 2 raises an invalid-operation error. A malformed explicit conversion raises a conversion error.

FQL internally distinguishes integers and floats. Most arithmetic and comparison operations work the same for both, but the distinction matters when type-checking functions are used. is_int returns true only for integer values, and is_float returns true only for floating-point values. Use to_int or to_float to convert between the two when needed.

Strings

Strings represent text and can be written as quoted literals:

Strings can be empty:

An empty string is still a text value, not the absence of a value. It is different from none.

Strings are commonly used for names, labels, URLs, selectors, extracted text, keys, and identifiers.

Strings can be compared with other strings. Comparisons use the string contents, so two strings are equal when they contain the same sequence of characters.

String comparisons are always case-sensitive.

When either + operand is a String, Ferret concatenates the String representations of both operands. This is the only arithmetic rule that stringifies otherwise unsupported operand types.

Template literals

Template literals are strings delimited by backticks that support embedded expressions. An expression inside ${...} is evaluated and its result is inserted into the string.

Any FQL expression can appear inside the interpolation:

Template literals can span multiple lines. Backtick strings are useful when constructing text that includes variable data without calling concat.

Arrays

Arrays are ordered collections of values written with square brackets:

Arrays can contain any FQL value:

Arrays preserve the order of their elements.

Array items can be accessed by index using bracket notation:

An empty array represents a collection with no items:

An empty array is not the same as none.

Arrays are commonly produced by for loops and collection operations.

Array elements can be nested:

Use ...expression inside an array literal to copy the elements of another Array or host-provided runtime List into a new array:

Array entries are evaluated once from left to right. Spreading none adds no elements. The copy is shallow: the source list is not changed, but nested values are shared. The spread operand must be an Array, another runtime List, or none; strings, ranges, and values that are merely iterable produce a TypeError.

Objects

An object is an unordered collection of named values, written with curly braces:

Each object entry has a property name and a value, which can be any FQL value.

Object properties can be accessed with dot notation or bracket notation.

Use dot notation when the property name is known ahead of time:

Use bracket notation when the property name comes from a string literal or variable:

Because objects do not preserve key order, property order does not affect object equality. Two objects with the same properties and values are equal, even if those properties were written in a different order.

An empty object represents a record with no properties:

An empty object is not the same as none.

Use ...expression inside an object literal to copy properties from another Object or host-provided runtime Map into a new object:

Object entries are evaluated once from left to right, so a later property replaces an earlier property with the same name, whether either property came from a spread. Spreading none adds no properties. The copy is shallow and does not mutate the source map. The operand must be an Object, another runtime Map, or none; other concrete values produce a TypeError.

Spread is available only while constructing array and object literals. It does not add rest destructuring, spread call arguments, for expansion, deep merging, or mutation.

DateTime values

DateTime values represent a specific point in time.

Use datetime::now() for the current instant or datetime::parse() to parse a date and time string:

let current = datetime::now()

return {
    current: current,
    year: datetime::year(current),
    month: datetime::month(current)
}

DateTime values support native instant comparison and checked arithmetic with native Duration values. Adding a Duration in either operand order produces another DateTime. Subtracting a Duration from a DateTime produces another DateTime, and subtracting two DateTime values produces the elapsed Duration between their canonical instants.

Use is_datetime to check whether a value is a DateTime. to_datetime accepts an existing DateTime or an RFC3339 string. It also accepts an Int or finite Float Unix epoch offset when the unit is explicit: to_datetime(value, "s"), to_datetime(value, "ms"), to_datetime(value, "us"), or to_datetime(value, "ns"). Ferret does not infer an epoch unit from numeric magnitude, and numeric strings are not treated as epoch values.

See the DateTime Standard Library category for the full list of available operations.

Binary values

Binary values represent raw bytes.

They are used for data that should be handled as bytes instead of ordinary text, such as downloaded files, encoded payloads, images, archives, or data exchanged with runtime modules.

Binary values are part of the FQL value model, but they are usually returned by functions, modules, or runtime operations. For example, an HTTP, file, or encoding module may return binary data when the result should be treated as bytes.

Durations

Durations are native FQL values backed by signed nanoseconds. A duration literal is a number immediately followed by a unit suffix. Suffixes are case-insensitive:

Duration literals work anywhere an ordinary expression is accepted. Compound source literals such as 1h30m are not supported; compose literals with arithmetic instead. Duration strings do support compound forms, so to_duration("1h30m") produces the same value as 1h + 30m.

to_duration and scheduling expressions use the broad Duration conversion rules:

Arithmetic and comparison operators do not apply this conversion implicitly. Duration addition and subtraction require two native Durations. Multiplication accepts a native Int or Float in either operand order. Division accepts a native number for scaling or another Duration for a ratio. An exact Duration ratio produces an integer; a fractional ratio produces a float.

Duration equality is also strict: 1s == 1000ms is true, while 1s == 1000 and 1s == "1s" are false. Relational comparison between Duration and a non-Duration value raises an invalid-operation error. Use to_duration(value) explicitly when conversion is intended.

String-triggered + remains concatenation. For example, 1s + "1s" returns "1s1s", while 1s + to_duration("1s") returns 2s.

Conversion, parsing, scaling, and division truncate fractional nanoseconds toward zero. Values outside the signed Duration range raise a range error instead of wrapping. Use to_string when text is required.

Equivalent values have the same normalized string form. For example, 5000ms renders as 5s, and days may render as hours. A zero Duration is false when evaluated by binary and or or; any non-zero Duration is true. Unary ! and not accept only Boolean values. Negative durations are valid values and arithmetic results, but scheduling operations reject them.

Type checks

Scripts often receive values in different shapes. Use type-related functions or predicates when logic needs to branch based on the kind of value being handled.

Type checks are useful when working with external data, optional fields, runtime-backed values, or module results.

See the Types Standard Library category for the full list of available type-checking functions.

Next steps