Expression class

A new Expression representing the absolute value of the numeric value.

Example

// Compute the absolute value of the 'price' field.
field("price").abs();

Expression.add()

Creates an expression that adds this expression to another expression.

Signature:

add(second: Expression | unknown): FunctionExpression;

Parameters

Parameter	Type	Description
second	Expression \| unknown	The expression or literal to add to this expression.

Returns:

A new Expression representing the addition operation.

Example

// Add the value of the 'quantity' field and the 'reserve' field.
field("quantity").add(field("reserve"));

Expression.arrayConcat()

Creates an expression that concatenates an array expression with one or more other arrays.

Signature:

arrayConcat(secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;

Parameters

Parameter	Type	Description
secondArray	Expression \| unknown[]	Second array expression or array literal to concatenate.
otherArrays	Array<Expression \| unknown[]>	Optional additional array expressions or array literals to concatenate.

Returns:

A new Expression representing the concatenated array.

Example

// Combine the 'items' array with another array field.
field("items").arrayConcat(field("otherItems"));

Expression.arrayContains()

Creates an expression that checks if an array contains a specific element.

Signature:

arrayContains(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The element to search for in the array.

Returns:

A new Expression representing the 'array_contains' comparison.

Example

// Check if the 'sizes' array contains the value from the 'selectedSize' field
field("sizes").arrayContains(field("selectedSize"));

Expression.arrayContains()

Creates an expression that checks if an array contains a specific value.

Signature:

arrayContains(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The element to search for in the array.

Returns:

A new Expression representing the 'array_contains' comparison.

Example

// Check if the 'colors' array contains "red"
field("colors").arrayContains("red");

Expression.arrayContainsAll()

Creates an expression that checks if an array contains all the specified elements.

Signature:

arrayContainsAll(values: Array<Expression | unknown>): BooleanExpression;

Parameters

Parameter	Type	Description
values	Array<Expression \| unknown>	The elements to check for in the array.

Returns:

A new Expression representing the 'array_contains_all' comparison.

Example

// Check if the 'tags' array contains both the value in field "tag1" and the literal value "tag2"
field("tags").arrayContainsAll([field("tag1"), "tag2"]);

Expression.arrayContainsAll()

Creates an expression that checks if an array contains all the specified elements.

Signature:

arrayContainsAll(arrayExpression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
arrayExpression	Expression	The elements to check for in the array.

Returns:

A new Expression representing the 'array_contains_all' comparison.

Example

// Check if the 'tags' array contains both of the values from field "tag1" and the literal value "tag2"
field("tags").arrayContainsAll(array([field("tag1"), "tag2"]));

Expression.arrayContainsAny()

Creates an expression that checks if an array contains any of the specified elements.

Signature:

arrayContainsAny(values: Array<Expression | unknown>): BooleanExpression;

Parameters

Parameter	Type	Description
values	Array<Expression \| unknown>	The elements to check for in the array.

Returns:

A new Expression representing the 'array_contains_any' comparison.

Example

// Check if the 'categories' array contains either values from field "cate1" or "cate2"
field("categories").arrayContainsAny([field("cate1"), field("cate2")]);

Expression.arrayContainsAny()

Creates an expression that checks if an array contains any of the specified elements.

Signature:

arrayContainsAny(arrayExpression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
arrayExpression	Expression	The elements to check for in the array.

Returns:

A new Expression representing the 'array_contains_any' comparison.

Example

// Check if the 'groups' array contains either the value from the 'userGroup' field
// or the value "guest"
field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));

Expression.arrayGet()

Creates an expression that indexes into an array from the beginning or end and returns the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end.

Signature:

arrayGet(offset: number): FunctionExpression;

Parameters

Parameter	Type	Description
offset	number	The index of the element to return.

Returns:

A new Expression representing the 'arrayGet' operation.

Example

// Return the value in the 'tags' field array at index `1`.
field('tags').arrayGet(1);

Expression.arrayGet()

Signature:

arrayGet(offsetExpr: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
offsetExpr	Expression	An `Expression` evaluating to the index of the element to return.

Returns:

A new Expression representing the 'arrayGet' operation.

Example

// Return the value in the tags field array at index specified by field
// 'favoriteTag'.
field('tags').arrayGet(field('favoriteTag'));

Expression.arrayLength()

Creates an expression that calculates the length of an array.

Signature:

arrayLength(): FunctionExpression;

Returns:

A new Expression representing the length of the array.

Example

// Get the number of items in the 'cart' array
field("cart").arrayLength();

Expression.arrayReverse()

Creates an expression that reverses an array.

Signature:

arrayReverse(): FunctionExpression;

Returns:

A new Expression representing the reversed array.

Example

// Reverse the value of the 'myArray' field.
field("myArray").arrayReverse();

Expression.arraySum()

Creates an expression that computes the sum of the elements in an array.

Signature:

arraySum(): FunctionExpression;

Returns:

A new Expression representing the sum of the elements in the array.

Example

// Compute the sum of the elements in the 'scores' field.
field("scores").arraySum();

Expression.as()

Assigns an alias to this expression.

Aliases are useful for renaming fields in the output of a stage or for giving meaningful names to calculated values.

Signature:

as(name: string): AliasedExpression;

Parameters

Parameter	Type	Description
name	string	The alias to assign to this expression.

Returns:

AliasedExpression

A new AliasedExpression that wraps this expression and associates it with the provided alias.

Example

// Calculate the total price and assign it the alias "totalPrice" and add it to the output.
firestore.pipeline().collection("items")
  .addFields(field("price").multiply(field("quantity")).as("totalPrice"));

Expression.asBoolean()

Wraps the expression in a [BooleanExpression].

Signature:

asBoolean(): BooleanExpression;

Returns:

A [BooleanExpression] representing the same expression.

Expression.ascending()

Creates an Ordering that sorts documents in ascending order based on this expression.

Signature:

ascending(): Ordering;

Returns:

Ordering

A new Ordering for ascending sorting.

Example

// Sort documents by the 'name' field in ascending order
pipeline().collection("users")
  .sort(field("name").ascending());

Expression.average()

Creates an aggregation that calculates the average (mean) of a numeric field across multiple stage inputs.

Signature:

average(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'average' aggregation.

Example

// Calculate the average age of users
field("age").average().as("averageAge");

Expression.byteLength()

Creates an expression that calculates the length of this string expression in bytes.

Signature:

byteLength(): FunctionExpression;

Returns:

A new Expression representing the length of the string in bytes.

Example

// Calculate the length of the 'myString' field in bytes.
field("myString").byteLength();

Expression.ceil()

Creates an expression that computes the ceiling of a numeric value.

Signature:

ceil(): FunctionExpression;

Returns:

A new Expression representing the ceiling of the numeric value.

Example

// Compute the ceiling of the 'price' field.
field("price").ceil();

Expression.charLength()

Creates an expression that calculates the character length of a string in UTF-8.

Signature:

charLength(): FunctionExpression;

Returns:

A new Expression representing the length of the string.

Example

// Get the character length of the 'name' field in its UTF-8 form.
field("name").charLength();

Expression.collectionId()

Creates an expression that returns the collection ID from a path.

Signature:

collectionId(): FunctionExpression;

Returns:

A new Expression representing the collectionId operation.

Example

// Get the collection ID from a path.
field("__path__").collectionId();

Expression.concat()

Creates an expression that concatenates expression results together.

Signature:

concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;

Parameters

Parameter	Type	Description
second	Expression \| unknown	The additional expression or literal to concatenate.
others	Array<Expression \| unknown>	Optional additional expressions or literals to concatenate.

Returns:

A new Expression representing the concatenated value.

Example

// Combine the 'firstName', ' ', and 'lastName' fields into a single value.
field("firstName").concat(constant(" "), field("lastName"));

Expression.cosineDistance()

Calculates the cosine distance between two vectors.

Signature:

cosineDistance(vectorExpression: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
vectorExpression	Expression	The other vector (represented as an Expression) to compare against.

Returns:

A new Expression representing the cosine distance between the two vectors.

Example

// Calculate the cosine distance between the 'userVector' field and the 'itemVector' field
field("userVector").cosineDistance(field("itemVector"));

Expression.cosineDistance()

Calculates the Cosine distance between two vectors.

Signature:

cosineDistance(vector: VectorValue | number[]): FunctionExpression;

Parameters

Parameter	Type	Description
vector	VectorValue \| number[]	The other vector (as a VectorValue) to compare against.

Returns:

A new Expression representing the Cosine* distance between the two vectors.

Example

// Calculate the Cosine distance between the 'location' field and a target location
field("location").cosineDistance(new VectorValue([37.7749, -122.4194]));

Expression.count()

Creates an aggregation that counts the number of stage inputs with valid evaluations of the expression or field.

Signature:

count(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'count' aggregation.

Example

// Count the total number of products
field("productId").count().as("totalProducts");

Expression.countDistinct()

Creates an aggregation that counts the number of distinct values of the expression or field.

Signature:

countDistinct(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'count_distinct' aggregation.

Example

// Count the distinct number of products
field("productId").countDistinct().as("distinctProducts");

Expression.descending()

Creates an Ordering that sorts documents in descending order based on this expression.

Signature:

descending(): Ordering;

Returns:

Ordering

A new Ordering for descending sorting.

Example

// Sort documents by the 'createdAt' field in descending order
firestore.pipeline().collection("users")
  .sort(field("createdAt").descending());

Expression.divide()

Creates an expression that divides this expression by another expression.

Signature:

divide(divisor: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
divisor	Expression	The expression to divide by.

Returns:

A new Expression representing the division operation.

Example

// Divide the 'total' field by the 'count' field
field("total").divide(field("count"));

Expression.divide()

Creates an expression that divides this expression by a constant value.

Signature:

divide(divisor: number): FunctionExpression;

Parameters

Parameter	Type	Description
divisor	number	The constant value to divide by.

Returns:

A new Expression representing the division operation.

Example

// Divide the 'value' field by 10
field("value").divide(10);

Expression.documentId()

Creates an expression that returns the document ID from a path.

Signature:

documentId(): FunctionExpression;

Returns:

A new Expression representing the documentId operation.

Example

// Get the document ID from a path.
field("__path__").documentId();

Expression.dotProduct()

Calculates the dot product between two vectors.

Signature:

dotProduct(vectorExpression: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
vectorExpression	Expression	The other vector (as an array of numbers) to calculate with.

Returns:

A new Expression representing the dot product between the two vectors.

Example

// Calculate the dot product between a feature vector and a target vector
field("features").dotProduct([0.5, 0.8, 0.2]);

Expression.dotProduct()

Calculates the dot product between two vectors.

Signature:

dotProduct(vector: VectorValue | number[]): FunctionExpression;

Parameters

Parameter	Type	Description
vector	VectorValue \| number[]	The other vector (as an array of numbers) to calculate with.

Returns:

A new Expression representing the dot product between the two vectors.

Example

// Calculate the dot product between a feature vector and a target vector
field("features").dotProduct(new VectorValue([0.5, 0.8, 0.2]));

Expression.endsWith()

Creates an expression that checks if a string ends with a given postfix.

Signature:

endsWith(suffix: string): BooleanExpression;

Parameters

Parameter	Type	Description
suffix	string	The postfix to check for.

Returns:

A new Expression representing the 'ends with' comparison.

Example

// Check if the 'filename' field ends with ".txt"
field("filename").endsWith(".txt");

Expression.endsWith()

Creates an expression that checks if a string ends with a given postfix (represented as an expression).

Signature:

endsWith(suffix: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
suffix	Expression	The postfix expression to check for.

Returns:

A new Expression representing the 'ends with' comparison.

Example

// Check if the 'url' field ends with the value of the 'extension' field
field("url").endsWith(field("extension"));

Expression.equal()

Creates an expression that checks if this expression is equal to another expression.

Signature:

equal(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to compare for equality.

Returns:

A new Expression representing the equality comparison.

Example

// Check if the 'age' field is equal to 21
field("age").equal(21);

Expression.equal()

Creates an expression that checks if this expression is equal to a constant value.

Signature:

equal(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for equality.

Returns:

A new Expression representing the equality comparison.

Example

// Check if the 'city' field is equal to "London"
field("city").equal("London");

Expression.equalAny()

Creates an expression that checks if this expression is equal to any of the provided values or expressions.

Signature:

equalAny(values: Array<Expression | unknown>): BooleanExpression;

Parameters

Parameter	Type	Description
values	Array<Expression \| unknown>	The values or expressions to check against.

Returns:

A new Expression representing the 'IN' comparison.

Example

// Check if the 'category' field is either "Electronics" or value of field 'primaryType'
field("category").equalAny("Electronics", field("primaryType"));

Expression.equalAny()

Creates an expression that checks if this expression is equal to any of the provided values or expressions.

Signature:

equalAny(arrayExpression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
arrayExpression	Expression	An expression that evaluates to an array of values to check against.

Returns:

A new Expression representing the 'IN' comparison.

Example

// Check if the 'category' field is either "Electronics" or value of field 'primaryType'
field("category").equalAny(array(["Electronics", field("primaryType")]));

Expression.euclideanDistance()

Calculates the Euclidean distance between two vectors.

Signature:

euclideanDistance(vectorExpression: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
vectorExpression	Expression	The other vector (as an array of numbers) to calculate with.

Returns:

A new Expression representing the Euclidean distance between the two vectors.

Example

// Calculate the Euclidean distance between the 'location' field and a target location
field("location").euclideanDistance([37.7749, -122.4194]);

Expression.euclideanDistance()

Calculates the Euclidean distance between two vectors.

Signature:

euclideanDistance(vector: VectorValue | number[]): FunctionExpression;

Parameters

Parameter	Type	Description
vector	VectorValue \| number[]	The other vector (as a VectorValue) to compare against.

Returns:

A new Expression representing the Euclidean distance between the two vectors.

Example

// Calculate the Euclidean distance between the 'location' field and a target location
field("location").euclideanDistance(new VectorValue([37.7749, -122.4194]));

Expression.exists()

Creates an expression that checks if a field exists in the document.

Signature:

exists(): BooleanExpression;

Returns:

A new Expression representing the 'exists' check.

Example

// Check if the document has a field named "phoneNumber"
field("phoneNumber").exists();

Expression.exp()

Creates an expression that computes e to the power of this expression.

Signature:

exp(): FunctionExpression;

Returns:

A new Expression representing the exp of the numeric value.

Example

// Compute e to the power of the 'value' field.
field("value").exp();

Expression.floor()

Creates an expression that computes the floor of a numeric value.

Signature:

floor(): FunctionExpression;

Returns:

A new Expression representing the floor of the numeric value.

Example

// Compute the floor of the 'price' field.
field("price").floor();

Expression.greaterThan()

Creates an expression that checks if this expression is greater than another expression.

Signature:

greaterThan(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to compare for greater than.

Returns:

A new Expression representing the greater than comparison.

Example

// Check if the 'age' field is greater than the 'limit' field
field("age").greaterThan(field("limit"));

Expression.greaterThan()

Creates an expression that checks if this expression is greater than a constant value.

Signature:

greaterThan(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for greater than.

Returns:

A new Expression representing the greater than comparison.

Example

// Check if the 'price' field is greater than 100
field("price").greaterThan(100);

Expression.greaterThanOrEqual()

Creates an expression that checks if this expression is greater than or equal to another expression.

Signature:

greaterThanOrEqual(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to compare for greater than or equal to.

Returns:

A new Expression representing the greater than or equal to comparison.

Example

// Check if the 'quantity' field is greater than or equal to field 'requirement' plus 1
field("quantity").greaterThanOrEqual(field('requirement').add(1));

Expression.greaterThanOrEqual()

Creates an expression that checks if this expression is greater than or equal to a constant value.

Signature:

greaterThanOrEqual(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for greater than or equal to.

Returns:

A new Expression representing the greater than or equal to comparison.

Example

// Check if the 'score' field is greater than or equal to 80
field("score").greaterThanOrEqual(80);

Expression.ifAbsent()

Creates an expression that returns the elseValue argument if this expression results in an absent value, else return the result of the this expression evaluation.

Signature:

ifAbsent(elseValue: unknown): Expression;

Parameters

Parameter	Type	Description
elseValue	unknown	The value that will be returned if this Expression evaluates to an absent value.

Returns:

A new [Expression] representing the ifAbsent operation.

Example

// Returns the value of the optional field 'optional_field', or returns 'default_value'
// if the field is absent.
field("optional_field").ifAbsent("default_value")

Expression.ifAbsent()

Creates an expression that returns the elseValue argument if this expression results in an absent value, else return the result of this expression evaluation.

// Returns the value of the optional field 'optional_field', or if that is
// absent, then returns the value of the field `
field("optional_field").ifAbsent(field('default_field'))

Signature:

ifAbsent(elseExpression: unknown): Expression;

Parameters

Parameter	Type	Description
elseExpression	unknown	The Expression that will be evaluated if this Expression evaluates to an absent value.

Returns:

A new [Expression] representing the ifAbsent operation.

Expression.ifError()

Creates an expression that returns the result of the catchExpr argument if there is an error, else return the result of this expression.

Signature:

ifError(catchExpr: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
catchExpr	Expression	The catch expression that will be evaluated and returned if this expression produces an error.

Returns:

A new Expression representing the 'ifError' operation.

Example

// Returns the first item in the title field arrays, or returns
// the entire title field if the array is empty or the field is another type.
field("title").arrayGet(0).ifError(field("title"));

Expression.ifError()

Creates an expression that returns the catch argument if there is an error, else return the result of this expression.

Signature:

ifError(catchValue: unknown): FunctionExpression;

Parameters

Parameter	Type	Description
catchValue	unknown	The value that will be returned if this expression produces an error.

Returns:

A new Expression representing the 'ifError' operation.

Example

// Returns the first item in the title field arrays, or returns
// "Default Title"
field("title").arrayGet(0).ifError("Default Title");

Expression.isAbsent()

Creates an expression that returns true if the result of this expression is absent. Otherwise, returns false even if the value is null.

Signature:

isAbsent(): BooleanExpression;

Returns:

A new BooleanExpression representing the 'isAbsent' check.

Example

// Check if the field `value` is absent.
field("value").isAbsent();
@example

Expression.isError()

Creates an expression that checks if a given expression produces an error.

Signature:

isError(): BooleanExpression;

Returns:

A new BooleanExpression representing the 'isError' check.

Example

// Check if the result of a calculation is an error
field("title").arrayContains(1).isError();

Expression.join()

Creates an expression that joins the elements of an array into a string.

Signature:

join(delimiterExpression: Expression): Expression;

Parameters

Parameter	Type	Description
delimiterExpression	Expression	The expression that evaluates to the delimiter string.

Returns:

A new Expression representing the join operation.

Example

// Join the elements of the 'tags' field with the delimiter from the 'separator' field.
field("tags").join(field("separator"))

Expression.join()

Creates an expression that joins the elements of an array field into a string.

Signature:

join(delimiter: string): Expression;

Parameters

Parameter	Type	Description
delimiter	string	The string to use as a delimiter.

Returns:

A new Expression representing the join operation.

Example

// Join the elements of the 'tags' field with a comma and space.
field("tags").join(", ")

Expression.length()

Creates an expression that calculates the length of a string, array, map, vector, or bytes.

Signature:

length(): FunctionExpression;

Returns:

A new Expression representing the length of the string, array, map, vector, or bytes.

Example

// Get the length of the 'name' field.
field("name").length();

// Get the number of items in the 'cart' array.
field("cart").length();

Expression.lessThan()

Creates an expression that checks if this expression is less than another expression.

Signature:

lessThan(experession: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
experession	Expression	The expression to compare for less than.

Returns:

A new Expression representing the less than comparison.

Example

// Check if the 'age' field is less than 'limit'
field("age").lessThan(field('limit'));

Expression.lessThan()

Creates an expression that checks if this expression is less than a constant value.

Signature:

lessThan(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for less than.

Returns:

A new Expression representing the less than comparison.

Example

// Check if the 'price' field is less than 50
field("price").lessThan(50);

Expression.lessThanOrEqual()

Creates an expression that checks if this expression is less than or equal to another expression.

Signature:

lessThanOrEqual(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to compare for less than or equal to.

Returns:

A new Expression representing the less than or equal to comparison.

Example

// Check if the 'quantity' field is less than or equal to 20
field("quantity").lessThan(constant(20));

Expression.lessThanOrEqual()

Creates an expression that checks if this expression is less than or equal to a constant value.

Signature:

lessThanOrEqual(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for less than or equal to.

Returns:

A new Expression representing the less than or equal to comparison.

Example

// Check if the 'score' field is less than or equal to 70
field("score").lessThan(70);

Expression.like()

Creates an expression that performs a case-sensitive string comparison.

Signature:

like(pattern: string): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	string	The pattern to search for. You can use "%" as a wildcard character.

Returns:

A new Expression representing the 'like' comparison.

Example

// Check if the 'title' field contains the word "guide" (case-sensitive)
field("title").like("%guide%");

Expression.like()

Creates an expression that performs a case-sensitive string comparison.

Signature:

like(pattern: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	Expression	The pattern to search for. You can use "%" as a wildcard character.

Returns:

A new Expression representing the 'like' comparison.

Example

// Check if the 'title' field contains the word "guide" (case-sensitive)
field("title").like("%guide%");

Expression.ln()

Creates an expression that computes the natural logarithm of a numeric value.

Signature:

ln(): FunctionExpression;

Returns:

A new Expression representing the natural logarithm of the numeric value.

Example

// Compute the natural logarithm of the 'value' field.
field("value").ln();

Expression.log10()

Creates an expression that computes the base-10 logarithm of a numeric value.

Signature:

log10(): FunctionExpression;

Returns:

A new Expression representing the base-10 logarithm of the numeric value.

Example

// Compute the base-10 logarithm of the 'value' field.
field("value").log10();

Expression.logicalMaximum()

Creates an expression that returns the larger value between this expression and another expression, based on Firestore's value type ordering.

Signature:

logicalMaximum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;

Parameters

Parameter	Type	Description
second	Expression \| unknown	The second expression or literal to compare with.
others	Array<Expression \| unknown>	Optional additional expressions or literals to compare with.

Returns:

A new Expression representing the logical maximum operation.

Example

// Returns the larger value between the 'timestamp' field and the current timestamp.
field("timestamp").logicalMaximum(Function.currentTimestamp());

Expression.logicalMinimum()

Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering.

Signature:

logicalMinimum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;

Parameters

Parameter	Type	Description
second	Expression \| unknown	The second expression or literal to compare with.
others	Array<Expression \| unknown>	Optional additional expressions or literals to compare with.

Returns:

A new Expression representing the logical minimum operation.

Example

// Returns the smaller value between the 'timestamp' field and the current timestamp.
field("timestamp").logicalMinimum(Function.currentTimestamp());

Expression.mapGet()

Accesses a value from a map (object) field using the provided key.

Signature:

mapGet(subfield: string): FunctionExpression;

Parameters

Parameter	Type	Description
subfield	string	The key to access in the map.

Returns:

A new Expression representing the value associated with the given key in the map.

Example

// Get the 'city' value from the 'address' map field
field("address").mapGet("city");

Expression.mapMerge()

Creates an expression that merges multiple map values.

Signature:

mapMerge(secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;

Parameters

Parameter	Type	Description
secondMap	Record<string, unknown> \| Expression	A required second map to merge. Represented as a literal or an expression that returns a map.
otherMaps	Array<Record<string, unknown> \| Expression>	Optional additional maps to merge. Each map is represented as a literal or an expression that returns a map.

Returns:

A new Expression representing the 'mapMerge' operation.

Example

// Merges the map in the settings field with, a map literal, and a map in
// that is conditionally returned by another expression
field('settings').mapMerge({ enabled: true }, conditional(field('isAdmin'), { admin: true}, {})

Expression.mapRemove()

Creates an expression that removes a key from the map produced by evaluating this expression.

Signature:

mapRemove(key: string): FunctionExpression;

Parameters

Parameter	Type	Description
key	string	The name of the key to remove from the input map.

Returns:

A new Expression representing the 'mapRemove' operation.

Example

// Removes the key 'baz' from the input map.
map({foo: 'bar', baz: true}).mapRemove('baz');

Expression.mapRemove()

Creates an expression that removes a key from the map produced by evaluating this expression.

Signature:

mapRemove(keyExpr: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
keyExpr	Expression	An expression that produces the name of the key to remove from the input map.

Returns:

A new Expression representing the 'mapRemove' operation.

Example

// Removes the key 'baz' from the input map.
map({foo: 'bar', baz: true}).mapRemove(constant('baz'));
@example

Expression.maximum()

Creates an aggregation that finds the maximum value of a field across multiple stage inputs.

Signature:

maximum(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'maximum' aggregation.

Example

// Find the highest score in a leaderboard
field("score").maximum().as("highestScore");

Expression.minimum()

Creates an aggregation that finds the minimum value of a field across multiple stage inputs.

Signature:

minimum(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'minimum' aggregation.

Example

// Find the lowest price of all products
field("price").minimum().as("lowestPrice");

Expression.mod()

Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression.

Signature:

mod(expression: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to divide by.

Returns:

A new Expression representing the modulo operation.

Example

// Calculate the remainder of dividing the 'value' field by the 'divisor' field
field("value").mod(field("divisor"));

Expression.mod()

Creates an expression that calculates the modulo (remainder) of dividing this expression by a constant value.

Signature:

mod(value: number): FunctionExpression;

Parameters

Parameter	Type	Description
value	number	The constant value to divide by.

Returns:

A new Expression representing the modulo operation.

Example

// Calculate the remainder of dividing the 'value' field by 10
field("value").mod(10);

Expression.multiply()

Creates an expression that multiplies this expression by another expression.

Signature:

multiply(second: Expression | number): FunctionExpression;

Parameters

Parameter	Type	Description
second	Expression \| number	The second expression or literal to multiply by.

Returns:

A new Expression representing the multiplication operation.

Example

// Multiply the 'quantity' field by the 'price' field
field("quantity").multiply(field("price"));

Expression.notEqual()

Creates an expression that checks if this expression is not equal to another expression.

Signature:

notEqual(expression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expression	Expression	The expression to compare for inequality.

Returns:

A new Expression representing the inequality comparison.

Example

// Check if the 'status' field is not equal to "completed"
field("status").notEqual("completed");

Expression.notEqual()

Creates an expression that checks if this expression is not equal to a constant value.

Signature:

notEqual(value: unknown): BooleanExpression;

Parameters

Parameter	Type	Description
value	unknown	The constant value to compare for inequality.

Returns:

A new Expression representing the inequality comparison.

Example

// Check if the 'country' field is not equal to "USA"
field("country").notEqual("USA");

Expression.notEqualAny()

Creates an expression that checks if this expression is not equal to any of the provided values or expressions.

Signature:

notEqualAny(values: Array<Expression | unknown>): BooleanExpression;

Parameters

Parameter	Type	Description
values	Array<Expression \| unknown>	The values or expressions to check against.

Returns:

A new Expression representing the 'notEqualAny' comparison.

Example

// Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
field("status").notEqualAny(["pending", field("rejectedStatus")]);

Expression.notEqualAny()

Creates an expression that checks if this expression is not equal to any of the values in the evaluated expression.

Signature:

notEqualAny(arrayExpression: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
arrayExpression	Expression	The values or expressions to check against.

Returns:

A new Expression representing the 'notEqualAny' comparison.

Example

// Check if the 'status' field is not equal to any value in the field 'rejectedStatuses'
field("status").notEqualAny(field('rejectedStatuses'));

Expression.pow()

Creates an expression that returns the value of this expression raised to the power of another expression.

Signature:

pow(exponent: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
exponent	Expression	The expression to raise this expression to the power of.

Returns:

A new Expression representing the power operation.

Example

// Raise the value of the 'base' field to the power of the 'exponent' field.
field("base").pow(field("exponent"));

Expression.pow()

Creates an expression that returns the value of this expression raised to the power of a constant value.

Signature:

pow(exponent: number): FunctionExpression;

Parameters

Parameter	Type	Description
exponent	number	The constant value to raise this expression to the power of.

Returns:

A new Expression representing the power operation.

Example

// Raise the value of the 'base' field to the power of 2.
field("base").pow(2);

Expression.regexContains()

Creates an expression that checks if a string contains a specified regular expression as a substring.

Signature:

regexContains(pattern: string): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	string	The regular expression to use for the search.

Returns:

A new Expression representing the 'contains' comparison.

Example

// Check if the 'description' field contains "example" (case-insensitive)
field("description").regexContains("(?i)example");

Expression.regexContains()

Creates an expression that checks if a string contains a specified regular expression as a substring.

Signature:

regexContains(pattern: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	Expression	The regular expression to use for the search.

Returns:

A new Expression representing the 'contains' comparison.

Example

// Check if the 'description' field contains the regular expression stored in field 'regex'
field("description").regexContains(field("regex"));

Expression.regexMatch()

Creates an expression that checks if a string matches a specified regular expression.

Signature:

regexMatch(pattern: string): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	string	The regular expression to use for the match.

Returns:

A new Expression representing the regular expression match.

Example

// Check if the 'email' field matches a valid email pattern
field("email").regexMatch("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");

Expression.regexMatch()

Creates an expression that checks if a string matches a specified regular expression.

Signature:

regexMatch(pattern: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
pattern	Expression	The regular expression to use for the match.

Returns:

A new Expression representing the regular expression match.

Example

// Check if the 'email' field matches a regular expression stored in field 'regex'
field("email").regexMatch(field("regex"));

Expression.reverse()

Creates an expression that reverses this string expression.

Signature:

reverse(): FunctionExpression;

Returns:

A new Expression representing the reversed string.

Example

// Reverse the value of the 'myString' field.
field("myString").reverse();

Expression.round()

Creates an expression that rounds a numeric value to the nearest whole number.

Signature:

round(): FunctionExpression;

Returns:

A new Expression representing the rounded value.

Example

// Round the value of the 'price' field.
field("price").round();

Expression.round()

Creates an expression that rounds a numeric value to the specified number of decimal places.

Signature:

round(decimalPlaces: number): FunctionExpression;

Parameters

Parameter	Type	Description
decimalPlaces	number	A constant specifying the rounding precision in decimal places.

Returns:

A new Expression representing the rounded value.

Example

// Round the value of the 'price' field to two decimal places.
field("price").round(2);

Expression.round()

Creates an expression that rounds a numeric value to the specified number of decimal places.

Signature:

round(decimalPlaces: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
decimalPlaces	Expression	An expression specifying the rounding precision in decimal places.

Returns:

A new Expression representing the rounded value.

Example

// Round the value of the 'price' field to two decimal places.
field("price").round(constant(2));

Expression.split()

Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter.

Signature:

split(delimiter: string): FunctionExpression;

Parameters

Parameter	Type	Description
delimiter	string

Returns:

A new Expression representing the split function.

Example

// Split the 'scoresCsv' field on delimiter ','
field('scoresCsv').split(',')

Expression.split()

Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter.

Signature:

split(delimiter: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
delimiter	Expression

Returns:

A new Expression representing the split function.

Example

// Split the 'scores' field on delimiter ',' or ':' depending on the stored format
field('scores').split(conditional(field('format').equal('csv'), constant(','), constant(':'))

Expression.sqrt()

Creates an expression that computes the square root of a numeric value.

Signature:

sqrt(): FunctionExpression;

Returns:

A new Expression representing the square root of the numeric value.

Example

// Compute the square root of the 'value' field.
field("value").sqrt();

Expression.startsWith()

Creates an expression that checks if a string starts with a given prefix.

Signature:

startsWith(prefix: string): BooleanExpression;

Parameters

Parameter	Type	Description
prefix	string	The prefix to check for.

Returns:

A new Expression representing the 'starts with' comparison.

Example

// Check if the 'name' field starts with "Mr."
field("name").startsWith("Mr.");

Expression.startsWith()

Creates an expression that checks if a string starts with a given prefix (represented as an expression).

Signature:

startsWith(prefix: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
prefix	Expression	The prefix expression to check for.

Returns:

A new Expression representing the 'starts with' comparison.

Example

// Check if the 'fullName' field starts with the value of the 'firstName' field
field("fullName").startsWith(field("firstName"));

Expression.stringConcat()

Creates an expression that concatenates string expressions together.

Signature:

stringConcat(secondString: Expression | string, ...otherStrings: Array<Expression | string>): FunctionExpression;

Parameters

Parameter	Type	Description
secondString	Expression \| string	The additional expression or string literal to concatenate.
otherStrings	Array<Expression \| string>	Optional additional expressions or string literals to concatenate.

Returns:

A new Expression representing the concatenated string.

Example

// Combine the 'firstName', " ", and 'lastName' fields into a single string
field("firstName").stringConcat(constant(" "), field("lastName"));

Expression.stringContains()

Creates an expression that checks if a string contains a specified substring.

Signature:

stringContains(substring: string): BooleanExpression;

Parameters

Parameter	Type	Description
substring	string	The substring to search for.

Returns:

A new Expression representing the 'contains' comparison.

Example

// Check if the 'description' field contains "example".
field("description").stringContains("example");

Expression.stringContains()

Creates an expression that checks if a string contains the string represented by another expression.

Signature:

stringContains(expr: Expression): BooleanExpression;

Parameters

Parameter	Type	Description
expr	Expression	The expression representing the substring to search for.

Returns:

A new Expression representing the 'contains' comparison.

Example

// Check if the 'description' field contains the value of the 'keyword' field.
field("description").stringContains(field("keyword"));

Expression.stringReverse()

Creates an expression that reverses a string.

Signature:

stringReverse(): FunctionExpression;

Returns:

A new Expression representing the reversed string.

Example

// Reverse the value of the 'myString' field.
field("myString").stringReverse();

Expression.substring()

Creates an expression that returns a substring of the results of this expression.

Signature:

substring(position: number, length?: number): FunctionExpression;

Parameters

Parameter	Type	Description
position	number	Index of the first character of the substring.
length	number	Length of the substring. If not provided, the substring will end at the end of the input.

Returns:

Expression.substring()

Creates an expression that returns a substring of the results of this expression.

Signature:

substring(position: Expression, length?: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
position	Expression	An expression returning the index of the first character of the substring.
length	Expression	An expression returning the length of the substring. If not provided the substring will end at the end of the input.

Returns:

Expression.subtract()

Creates an expression that subtracts another expression from this expression.

Signature:

subtract(subtrahend: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
subtrahend	Expression	The expression to subtract from this expression.

Returns:

A new Expression representing the subtraction operation.

Example

// Subtract the 'discount' field from the 'price' field
field("price").subtract(field("discount"));

Expression.subtract()

Creates an expression that subtracts a constant value from this expression.

Signature:

subtract(subtrahend: number): FunctionExpression;

Parameters

Parameter	Type	Description
subtrahend	number	The constant value to subtract.

Returns:

A new Expression representing the subtraction operation.

Example

// Subtract 20 from the value of the 'total' field
field("total").subtract(20);

Expression.sum()

Creates an aggregation that calculates the sum of a numeric field across multiple stage inputs.

Signature:

sum(): AggregateFunction;

Returns:

A new AggregateFunction representing the 'sum' aggregation.

Example

// Calculate the total revenue from a set of orders
field("orderAmount").sum().as("totalRevenue");

Expression.timestampAdd()

Creates an expression that adds a specified amount of time to this timestamp expression.

Signature:

timestampAdd(unit: Expression, amount: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
unit	Expression	The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
amount	Expression	The expression evaluates to amount of the unit.

Returns:

A new Expression representing the resulting timestamp.

Example

// Add some duration determined by field 'unit' and 'amount' to the 'timestamp' field.
field("timestamp").timestampAdd(field("unit"), field("amount"));

Expression.timestampAdd()

Creates an expression that adds a specified amount of time to this timestamp expression.

Signature:

timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;

Parameters

Parameter	Type	Description
unit	'microsecond' \| 'millisecond' \| 'second' \| 'minute' \| 'hour' \| 'day'	The unit of time to add (e.g., "day", "hour").
amount	number	The amount of time to add.

Returns:

A new Expression representing the resulting timestamp.

Example

// Add 1 day to the 'timestamp' field.
field("timestamp").timestampAdd("day", 1);

Expression.timestampSubtract()

Creates an expression that subtracts a specified amount of time from this timestamp expression.

Signature:

timestampSubtract(unit: Expression, amount: Expression): FunctionExpression;

Parameters

Parameter	Type	Description
unit	Expression	The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
amount	Expression	The expression evaluates to amount of the unit.

Returns:

A new Expression representing the resulting timestamp.

Example

// Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field.
field("timestamp").timestampSubtract(field("unit"), field("amount"));

Expression.timestampSubtract()

Creates an expression that subtracts a specified amount of time from this timestamp expression.

Signature:

timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;

Parameters

Parameter	Type	Description
unit	'microsecond' \| 'millisecond' \| 'second' \| 'minute' \| 'hour' \| 'day'	The unit of time to subtract (e.g., "day", "hour").
amount	number	The amount of time to subtract.

Returns:

A new Expression representing the resulting timestamp.

Example

// Subtract 1 day from the 'timestamp' field.
field("timestamp").timestampSubtract("day", 1);

Expression.timestampToUnixMicros()

Creates an expression that converts this timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).

Signature:

timestampToUnixMicros(): FunctionExpression;

Returns:

A new Expression representing the number of microseconds since epoch.

Example

// Convert the 'timestamp' field to microseconds since epoch.
field("timestamp").timestampToUnixMicros();

Expression.timestampToUnixMillis()

Creates an expression that converts this timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).

Signature:

timestampToUnixMillis(): FunctionExpression;

Returns:

A new Expression representing the number of milliseconds since epoch.

Example

// Convert the 'timestamp' field to milliseconds since epoch.
field("timestamp").timestampToUnixMillis();

Expression.timestampToUnixSeconds()

Creates an expression that converts this timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).

Signature:

timestampToUnixSeconds(): FunctionExpression;

Returns:

A new Expression representing the number of seconds since epoch.

Example

// Convert the 'timestamp' field to seconds since epoch.
field("timestamp").timestampToUnixSeconds();

Expression.timestampTruncate()

Creates an expression that truncates a timestamp to a specified granularity.

Signature:

timestampTruncate(granularity: TimeGranularity, timezone?: string | Expression): FunctionExpression;

Parameters

Parameter	Type	Description
granularity	TimeGranularity	The granularity to truncate to.
timezone	string \| Expression	The timezone to use for truncation. Valid values are from the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".

Returns:

A new Expression representing the truncated timestamp.

Example

// Truncate the 'createdAt' timestamp to the beginning of the day.
field('createdAt').timestampTruncate('day')

Expression.timestampTruncate()

Creates an expression that truncates a timestamp to a specified granularity.

Signature:

timestampTruncate(granularity: Expression, timezone?: string | Expression): FunctionExpression;

Parameters

Parameter	Type	Description
granularity	Expression	The granularity to truncate to.
timezone	string \| Expression	The timezone to use for truncation. Valid values are from the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".

Returns:

A new Expression representing the truncated timestamp.

Example

// Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'.
field('createdAt').timestampTruncate(field('granularity'))

Expression.toLower()

Creates an expression that converts a string to lowercase.

Signature:

toLower(): FunctionExpression;

Returns:

A new Expression representing the lowercase string.

Example

// Convert the 'name' field to lowercase
field("name").toLower();

Expression.toUpper()

Creates an expression that converts a string to uppercase.

Signature:

toUpper(): FunctionExpression;

Returns:

A new Expression representing the uppercase string.

Example

// Convert the 'title' field to uppercase
field("title").toUpper();

Expression.trim()

Creates an expression that removes leading and trailing characters from a string or byte array.

Signature:

trim(valueToTrim?: string | Expression | Bytes): FunctionExpression;

Parameters

Parameter	Type	Description
valueToTrim	string \| Expression \| Bytes	Optional This parameter is treated as a set of characters or bytes that will be trimmed from the input. If not specified, then whitespace will be trimmed.

Returns:

A new Expression representing the trimmed string or byte array.

Example

// Trim whitespace from the 'userInput' field
field("userInput").trim();

// Trim quotes from the 'userInput' field
field("userInput").trim('"');

Expression.type()

Creates an expression that returns the data type of this expression's result, as a string.

Signature:

type(): FunctionExpression;

Returns:

A new Expression representing the data type.

Example

// Get the data type of the value in field 'title'
field('title').type()

Expression.unixMicrosToTimestamp()

Creates an expression that interprets this expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.

Signature:

unixMicrosToTimestamp(): FunctionExpression;

Returns:

A new Expression representing the timestamp.

Example

// Interpret the 'microseconds' field as microseconds since epoch.
field("microseconds").unixMicrosToTimestamp();

Expression.unixMillisToTimestamp()

Creates an expression that interprets this expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.

Signature:

unixMillisToTimestamp(): FunctionExpression;

Returns:

A new Expression representing the timestamp.

Example

// Interpret the 'milliseconds' field as milliseconds since epoch.
field("milliseconds").unixMillisToTimestamp();

Expression.unixSecondsToTimestamp()

Creates an expression that interprets this expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.

Signature:

unixSecondsToTimestamp(): FunctionExpression;

Returns:

A new Expression representing the timestamp.

Example

// Interpret the 'seconds' field as seconds since epoch.
field("seconds").unixSecondsToTimestamp();

Expression.vectorLength()

Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression.

Signature:

vectorLength(): FunctionExpression;

Returns: