docs-devsite/firestore_lite_pipelines.expression.md
Project: /docs/reference/js/_project.yaml Book: /docs/reference/_book.yaml page_type: reference
{% comment %} DO NOT EDIT THIS FILE! This is generated by the JS SDK team, and any local changes will be overwritten. Changes should be made in the source code at https://github.com/firebase/firebase-js-sdk {% endcomment %}
Represents an expression that can be evaluated to a value within the execution of a Pipeline<!-- -->.
Expressions are the building blocks for creating complex queries and transformations in Firestore pipelines. They can represent:
The Expression class provides a fluent API for building expressions. You can chain together method calls to create complex expressions.
<b>Signature:</b>
export declare abstract class Expression
| Property | Modifiers | Type | Description |
|---|---|---|---|
| expressionType | ExpressionType |
| Method | Modifiers | Description |
|---|---|---|
| abs() | Creates an expression that computes the absolute value of a numeric value. | |
| add(second) | Creates an expression that adds this expression to another expression. | |
| arrayAgg() | Creates an aggregation that collects all values of an expression across multiple stage inputs into an array. | |
| arrayAggDistinct() | Creates an aggregation that collects all distinct values of an expression across multiple stage inputs into an array. | |
| arrayConcat(secondArray, otherArrays) | Creates an expression that concatenates an array expression with one or more other arrays. | |
| arrayContains(expression) | Creates an expression that checks if an array contains a specific element. | |
| arrayContains(value) | Creates an expression that checks if an array contains a specific value. | |
| arrayContainsAll(values) | Creates an expression that checks if an array contains all the specified elements. | |
| arrayContainsAll(arrayExpression) | Creates an expression that checks if an array contains all the specified elements. | |
| arrayContainsAny(values) | Creates an expression that checks if an array contains any of the specified elements. | |
| arrayContainsAny(arrayExpression) | Creates an expression that checks if an array contains any of the specified elements. | |
| arrayFilter(alias, filter) | Filters the array using a provided alias and predicate expression. | |
| arrayFirst() | Returns the first element of the array. | |
| arrayFirstN(n) | Returns the first <code>n</code> elements of the array. | |
| arrayFirstN(n) | Returns the first <code>n</code> elements of the array. | |
| arrayGet(offset) | 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. | |
| arrayGet(offsetExpr) | 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. | |
| arrayIndexOf(search) | Returns the first index of the search value in the array, or -1 if not found. | |
| arrayIndexOf(search) | Returns the first index of the search value in the array, or -1 if not found. | |
| arrayIndexOfAll(search) | Returns all indices of the search value in the array. | |
| arrayIndexOfAll(search) | Returns all indices of the search value in the array. | |
| arrayLast() | Returns the last element of the array. | |
| arrayLastIndexOf(search) | Returns the last index of the search value in the array, or -1 if not found. | |
| arrayLastIndexOf(search) | Returns the last index of the search value in the array, or -1 if not found. | |
| arrayLastN(n) | Returns the last <code>n</code> elements of the array. | |
| arrayLastN(n) | Returns the last <code>n</code> elements of the array. | |
| arrayLength() | Creates an expression that calculates the length of an array. | |
| arrayMaximum() | Returns the maximum value in the array. | |
| arrayMaximumN(n) | Returns the largest <code>n</code> elements of the array.<!-- -->Note: Returns the n largest non-null elements in the array, in descending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. | |
| arrayMaximumN(n) | Returns the largest <code>n</code> elements of the array.<!-- -->Note: Returns the n largest non-null elements in the array, in descending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. | |
| arrayMinimum() | Returns the minimum value in the array. | |
| arrayMinimumN(n) | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. | |
| arrayMinimumN(n) | Returns the smallest <code>n</code> elements of the array.<!-- -->Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined. | |
| arrayReverse() | Creates an expression that reverses an array. | |
| arraySlice(offset, length) | Returns a subset of the array. | |
| arraySum() | Creates an expression that computes the sum of the elements in an array. | |
| arrayTransform(elementAlias, transform) | Creates an expression that applies a provided transformation to each element in an array. | |
| arrayTransformWithIndex(elementAlias, indexAlias, transform) | Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression. | |
| as(name) | 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. | |
| asBoolean() | Wraps the expression in a [BooleanExpression]. | |
| ascending() | Creates an Ordering that sorts documents in ascending order based on this expression. | |
| average() | Creates an aggregation that calculates the average (mean) of a numeric field across multiple stage inputs. | |
| byteLength() | Creates an expression that calculates the length of this string expression in bytes. | |
| ceil() | Creates an expression that computes the ceiling of a numeric value. | |
| charLength() | Creates an expression that calculates the character length of a string in UTF-8. | |
| coalesce(replacement, others) | Creates an expression that returns the first non-null, non-absent argument, without evaluating the rest of the arguments. When all arguments are null or absent, returns the last argument. | |
| collectionId() | Creates an expression that returns the collection ID from a path. | |
| concat(second, others) | Creates an expression that concatenates expression results together. | |
| cosineDistance(vectorExpression) | Calculates the cosine distance between two vectors. | |
| cosineDistance(vector) | Calculates the Cosine distance between two vectors. | |
| count() | Creates an aggregation that counts the number of stage inputs with valid evaluations of the expression or field. | |
| countDistinct() | Creates an aggregation that counts the number of distinct values of the expression or field. | |
| descending() | Creates an Ordering that sorts documents in descending order based on this expression. | |
| divide(divisor) | Creates an expression that divides this expression by another expression. | |
| divide(divisor) | Creates an expression that divides this expression by a constant value. | |
| documentId() | Creates an expression that returns the document ID from a path. | |
| dotProduct(vectorExpression) | Calculates the dot product between two vectors. | |
| dotProduct(vector) | Calculates the dot product between two vectors. | |
| endsWith(suffix) | Creates an expression that checks if a string ends with a given postfix. | |
| endsWith(suffix) | Creates an expression that checks if a string ends with a given postfix (represented as an expression). | |
| equal(expression) | Creates an expression that checks if this expression is equal to another expression. | |
| equal(value) | Creates an expression that checks if this expression is equal to a constant value. | |
| equalAny(values) | Creates an expression that checks if this expression is equal to any of the provided values or expressions. | |
| equalAny(arrayExpression) | Creates an expression that checks if this expression is equal to any of the provided values or expressions. | |
| euclideanDistance(vectorExpression) | Calculates the Euclidean distance between two vectors. | |
| euclideanDistance(vector) | Calculates the Euclidean distance between two vectors. | |
| exists() | Creates an expression that checks if a field exists in the document. | |
| exp() | Creates an expression that computes e to the power of this expression. | |
| first() | Creates an aggregation that finds the first value of an expression across multiple stage inputs. | |
| floor() | Creates an expression that computes the floor of a numeric value. | |
| getField(key) | Creates an expression that returns the value of a field from the document that results from the evaluation of this expression. | |
| greaterThan(expression) | Creates an expression that checks if this expression is greater than another expression. | |
| greaterThan(value) | Creates an expression that checks if this expression is greater than a constant value. | |
| greaterThanOrEqual(expression) | Creates an expression that checks if this expression is greater than or equal to another expression. | |
| greaterThanOrEqual(value) | Creates an expression that checks if this expression is greater than or equal to a constant value. | |
| ifAbsent(elseValue) | Creates an expression that returns the <code>elseValue</code> argument if this expression results in an absent value, else return the result of this expression evaluation. | |
| ifAbsent(elseExpression) | Creates an expression that returns the <code>elseValue</code> argument if this expression results in an absent value, else return the result of this expression evaluation. | |
| ifError(catchExpr) | Creates an expression that returns the result of the <code>catchExpr</code> argument if there is an error, else return the result of this expression. | |
| ifError(catchValue) | Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of this expression. | |
| ifNull(elseExpression) | Creates an expression that returns the <code>elseValue</code> argument if this expression evaluates to null, else return the result of this expression evaluation. | |
| ifNull(elseValue) | Creates an expression that returns the <code>elseValue</code> argument if this expression evaluates to null, else return the result of this expression evaluation. | |
| isAbsent() | Creates an expression that returns <code>true</code> if the result of this expression is absent. Otherwise, returns <code>false</code> even if the value is <code>null</code>. | |
| isError() | Creates an expression that checks if a given expression produces an error. | |
| isType(type) | Creates an expression that checks if the result of this expression is of the given type. | |
| join(delimiterExpression) | Creates an expression that joins the elements of an array into a string. | |
| join(delimiter) | Creates an expression that joins the elements of an array field into a string. | |
| last() | Creates an aggregation that finds the last value of an expression across multiple stage inputs. | |
| length() | Creates an expression that calculates the length of a string, array, map, vector, or bytes. | |
| lessThan(experession) | Creates an expression that checks if this expression is less than another expression. | |
| lessThan(value) | Creates an expression that checks if this expression is less than a constant value. | |
| lessThanOrEqual(expression) | Creates an expression that checks if this expression is less than or equal to another expression. | |
| lessThanOrEqual(value) | Creates an expression that checks if this expression is less than or equal to a constant value. | |
| like(pattern) | Creates an expression that performs a case-sensitive string comparison. | |
| like(pattern) | Creates an expression that performs a case-sensitive string comparison. | |
| ln() | Creates an expression that computes the natural logarithm of a numeric value. | |
| log10() | Creates an expression that computes the base-10 logarithm of a numeric value. | |
| logicalMaximum(second, others) | Creates an expression that returns the larger value between this expression and another expression, based on Firestore's value type ordering. | |
| logicalMinimum(second, others) | Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering. | |
| ltrim(valueToTrim) | Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array. | |
| mapEntries() | Creates an expression that returns the entries of a map as an array of maps, where each map contains a <code>"k"</code> property for the key and a <code>"v"</code> property for the value. For example: <code>[{ k: "key1", v: "value1" }, ...]</code>. | |
| mapGet(subfield) | Accesses a value from a map (object) field using the provided key. | |
| mapKeys() | Creates an expression that returns the keys of a map. | |
| mapMerge(secondMap, otherMaps) | Creates an expression that merges multiple map values. | |
| mapRemove(key) | Creates an expression that removes a key from the map produced by evaluating this expression. | |
| mapRemove(keyExpr) | Creates an expression that removes a key from the map produced by evaluating this expression. | |
| mapSet(key, value, moreKeyValues) | Creates an expression that returns a new map with the specified entries added or updated. | |
| mapValues() | Creates an expression that returns the values of a map. | |
| maximum() | Creates an aggregation that finds the maximum value of a field across multiple stage inputs. | |
| minimum() | Creates an aggregation that finds the minimum value of a field across multiple stage inputs. | |
| mod(expression) | Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression. | |
| mod(value) | Creates an expression that calculates the modulo (remainder) of dividing this expression by a constant value. | |
| multiply(second) | Creates an expression that multiplies this expression by another expression. | |
| notEqual(expression) | Creates an expression that checks if this expression is not equal to another expression. | |
| notEqual(value) | Creates an expression that checks if this expression is not equal to a constant value. | |
| notEqualAny(values) | Creates an expression that checks if this expression is not equal to any of the provided values or expressions. | |
| notEqualAny(arrayExpression) | Creates an expression that checks if this expression is not equal to any of the values in the evaluated expression. | |
| parent() | Creates an expression that returns the parent document reference of a document reference. | |
| pow(exponent) | Creates an expression that returns the value of this expression raised to the power of another expression. | |
| pow(exponent) | Creates an expression that returns the value of this expression raised to the power of a constant value. | |
| regexContains(pattern) | Creates an expression that checks if a string contains a specified regular expression as a substring. | |
| regexContains(pattern) | Creates an expression that checks if a string contains a specified regular expression as a substring. | |
| regexFind(pattern) | Creates an expression that returns the first substring of a string expression that matches a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. | |
| regexFind(pattern) | Creates an expression that returns the first substring of a string expression that matches a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. | |
| regexFindAll(pattern) | Creates an expression that evaluates to a list of all substrings in this string expression that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. | |
| regexFindAll(pattern) | Creates an expression that evaluates to a list of all substrings in this string expression that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. | |
| regexMatch(pattern) | Creates an expression that checks if a string matches a specified regular expression. | |
| regexMatch(pattern) | Creates an expression that checks if a string matches a specified regular expression. | |
| reverse() | Creates an expression that reverses this string expression. | |
| round() | Creates an expression that rounds a numeric value to the nearest whole number. | |
| round(decimalPlaces) | Creates an expression that rounds a numeric value to the specified number of decimal places. | |
| round(decimalPlaces) | Creates an expression that rounds a numeric value to the specified number of decimal places. | |
| rtrim(valueToTrim) | Trims whitespace or a specified set of characters/bytes from the end of a string or byte array. | |
| split(delimiter) | Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter. | |
| split(delimiter) | Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter. | |
| sqrt() | Creates an expression that computes the square root of a numeric value. | |
| startsWith(prefix) | Creates an expression that checks if a string starts with a given prefix. | |
| startsWith(prefix) | Creates an expression that checks if a string starts with a given prefix (represented as an expression). | |
| stringConcat(secondString, otherStrings) | Creates an expression that concatenates string expressions together. | |
| stringContains(substring) | Creates an expression that checks if a string contains a specified substring. | |
| stringContains(expr) | Creates an expression that checks if a string contains the string represented by another expression. | |
| stringIndexOf(search) | Creates an expression that finds the index of the first occurrence of a substring or byte sequence. | |
| stringRepeat(repetitions) | Creates an expression that repeats a string or byte array a specified number of times. | |
| stringReplaceAll(find, replacement) | Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement. | |
| stringReplaceOne(find, replacement) | Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement. | |
| stringReverse() | Creates an expression that reverses a string. | |
| substring(position, length) | Creates an expression that returns a substring of the results of this expression. | |
| substring(position, length) | Creates an expression that returns a substring of the results of this expression. | |
| subtract(subtrahend) | Creates an expression that subtracts another expression from this expression. | |
| subtract(subtrahend) | Creates an expression that subtracts a constant value from this expression. | |
| sum() | Creates an aggregation that calculates the sum of a numeric field across multiple stage inputs. | |
| timestampAdd(unit, amount) | Creates an expression that adds a specified amount of time to this timestamp expression. | |
| timestampAdd(unit, amount) | Creates an expression that adds a specified amount of time to this timestamp expression. | |
| timestampDiff(start, unit) | Creates an expression that calculates the difference between this timestamp and another timestamp. | |
| timestampDiff(start, unit) | Creates an expression that calculates the difference between this timestamp and another timestamp. | |
| timestampExtract(part, timezone) | Creates an expression that extracts a specified part from this timestamp expression. | |
| timestampExtract(part, timezone) | Creates an expression that extracts a specified part from this timestamp expression. | |
| timestampSubtract(unit, amount) | Creates an expression that subtracts a specified amount of time from this timestamp expression. | |
| timestampSubtract(unit, amount) | Creates an expression that subtracts a specified amount of time from this timestamp 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). | |
| 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). | |
| 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). | |
| timestampTruncate(granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. | |
| timestampTruncate(granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. | |
| toLower() | Creates an expression that converts a string to lowercase. | |
| toUpper() | Creates an expression that converts a string to uppercase. | |
| trim(valueToTrim) | Creates an expression that removes leading and trailing characters from a string or byte array. | |
| trunc() | Creates an expression that truncates the numeric value to an integer. | |
| trunc(decimalPlaces) | Creates an expression that truncates a numeric value to the specified number of decimal places. | |
| trunc(decimalPlaces) | Creates an expression that truncates a numeric value to the specified number of decimal places. | |
| type() | Creates an expression that returns the data type of this expression's result, as a string. | |
| 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. | |
| 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. | |
| 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. | |
| vectorLength() | Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression. |
<b>Signature:</b>
abstract readonly expressionType: ExpressionType;
Creates an expression that computes the absolute value of a numeric value.
<b>Signature:</b>
abs(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the absolute value of the numeric value.
// Compute the absolute value of the 'price' field.
field("price").abs();
Creates an expression that adds this expression to another expression.
<b>Signature:</b>
add(second: Expression | unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| second | Expression | unknown | The expression or literal to add to this expression. |
<b>Returns:</b>
A new Expression representing the addition operation.
// Add the value of the 'quantity' field and the 'reserve' field.
field("quantity").add(field("reserve"));
Creates an aggregation that collects all values of an expression across multiple stage inputs into an array.
If the expression resolves to an absent value, it is converted to null<!-- -->. The order of elements in the output array is not stable and shouldn't be relied upon.
<b>Signature:</b>
arrayAgg(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg' aggregation.
// Collect all tags from books into an array
field("tags").arrayAgg().as("allTags");
Creates an aggregation that collects all distinct values of an expression across multiple stage inputs into an array.
If the expression resolves to an absent value, it is converted to null<!-- -->. The order of elements in the output array is not stable and shouldn't be relied upon.
<b>Signature:</b>
arrayAggDistinct(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg_distinct' aggregation.
// Collect all distinct tags from books into an array
field("tags").arrayAggDistinct().as("allDistinctTags");
Creates an expression that concatenates an array expression with one or more other arrays.
<b>Signature:</b>
arrayConcat(secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the concatenated array.
// Combine the 'items' array with another array field.
field("items").arrayConcat(field("otherItems"));
Creates an expression that checks if an array contains a specific element.
<b>Signature:</b>
arrayContains(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The element to search for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains' comparison.
// Check if the 'sizes' array contains the value from the 'selectedSize' field
field("sizes").arrayContains(field("selectedSize"));
Creates an expression that checks if an array contains a specific value.
<b>Signature:</b>
arrayContains(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The element to search for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains' comparison.
// Check if the 'colors' array contains "red"
field("colors").arrayContains("red");
Creates an expression that checks if an array contains all the specified elements.
<b>Signature:</b>
arrayContainsAll(values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| values | Array<Expression | unknown> | The elements to check for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains_all' comparison.
// Check if the 'tags' array contains both the value in field "tag1" and the literal value "tag2"
field("tags").arrayContainsAll([field("tag1"), "tag2"]);
Creates an expression that checks if an array contains all the specified elements.
<b>Signature:</b>
arrayContainsAll(arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The elements to check for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains_all' comparison.
// 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"]));
Creates an expression that checks if an array contains any of the specified elements.
<b>Signature:</b>
arrayContainsAny(values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| values | Array<Expression | unknown> | The elements to check for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains_any' comparison.
// Check if the 'categories' array contains either values from field "cate1" or "cate2"
field("categories").arrayContainsAny([field("cate1"), field("cate2")]);
Creates an expression that checks if an array contains any of the specified elements.
<b>Signature:</b>
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The elements to check for in the array. |
<b>Returns:</b>
A new Expression representing the 'array_contains_any' comparison.
// Check if the 'groups' array contains either the value from the 'userGroup' field
// or the value "guest"
field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
Filters the array using a provided alias and predicate expression.
<b>Signature:</b>
arrayFilter(alias: string, filter: BooleanExpression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| alias | string | The variable name to use for each element. |
| filter | BooleanExpression | The predicate boolean expression to filter by. |
<b>Returns:</b>
A new Expression representing the filtered array.
// Filter the 'items' array to only include those where the 'price' is greater than 10
field("items").arrayFilter('item', greaterThan(variable('item.price'), 10));
Returns the first element of the array.
<b>Signature:</b>
arrayFirst(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the first element.
// Get the first element of the 'myArray' field.
field("myArray").arrayFirst();
Returns the first n elements of the array.
<b>Signature:</b>
arrayFirstN(n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the first n elements.
// Get the first 3 elements of the 'myArray' field.
field("myArray").arrayFirstN(3);
Returns the first n elements of the array.
<b>Signature:</b>
arrayFirstN(n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | Expression | An expression evaluating to the number of elements to return. |
<b>Returns:</b>
A new Expression representing the first n elements.
// Get the first n elements of the 'myArray' field.
field("myArray").arrayFirstN(field("count"));
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.
<b>Signature:</b>
arrayGet(offset: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| offset | number | The index of the element to return. |
<b>Returns:</b>
A new Expression representing the 'arrayGet' operation.
// Return the value in the 'tags' field array at index `1`.
field('tags').arrayGet(1);
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.
<b>Signature:</b>
arrayGet(offsetExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| offsetExpr | Expression | An <code>Expression</code> evaluating to the index of the element to return. |
<b>Returns:</b>
A new Expression representing the 'arrayGet' operation.
// Return the value in the tags field array at index specified by field
// 'favoriteTag'.
field('tags').arrayGet(field('favoriteTag'));
Returns the first index of the search value in the array, or -1 if not found.
<b>Signature:</b>
arrayIndexOf(search: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | unknown | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the first index of the value 3 in the 'myArray' field.
field("myArray").arrayIndexOf(3);
Returns the first index of the search value in the array, or -1 if not found.
<b>Signature:</b>
arrayIndexOf(search: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | Expression | An expression evaluating to the value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the first index of the value in 'searchVal' field in the 'myArray' field.
field("myArray").arrayIndexOf(field("searchVal"));
Returns all indices of the search value in the array.
<b>Signature:</b>
arrayIndexOfAll(search: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | unknown | The value to search for. |
<b>Returns:</b>
A new Expression representing the indices.
// Get all indices of the value 3 in the 'myArray' field.
field("myArray").arrayIndexOfAll(3);
Returns all indices of the search value in the array.
<b>Signature:</b>
arrayIndexOfAll(search: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | Expression | An expression evaluating to the value to search for. |
<b>Returns:</b>
A new Expression representing the indices.
// Get all indices of the value in 'searchVal' field in the 'myArray' field.
field("myArray").arrayIndexOfAll(field("searchVal"));
Returns the last element of the array.
<b>Signature:</b>
arrayLast(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the last element.
// Get the last element of the 'myArray' field.
field("myArray").arrayLast();
Returns the last index of the search value in the array, or -1 if not found.
<b>Signature:</b>
arrayLastIndexOf(search: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | unknown | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the last index of the value 3 in the 'myArray' field.
field("myArray").arrayLastIndexOf(3);
Returns the last index of the search value in the array, or -1 if not found.
<b>Signature:</b>
arrayLastIndexOf(search: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | Expression | An expression evaluating to the value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the last index of the value in 'searchVal' field in the 'myArray' field.
field("myArray").arrayLastIndexOf(field("searchVal"));
Returns the last n elements of the array.
<b>Signature:</b>
arrayLastN(n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the last n elements.
// Get the last 3 elements of the 'myArray' field.
field("myArray").arrayLastN(3);
Returns the last n elements of the array.
<b>Signature:</b>
arrayLastN(n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | Expression | An expression evaluating to the number of elements to return. |
<b>Returns:</b>
A new Expression representing the last n elements.
// Get the last n elements of the 'myArray' field.
field("myArray").arrayLastN(field("count"));
Creates an expression that calculates the length of an array.
<b>Signature:</b>
arrayLength(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the length of the array.
// Get the number of items in the 'cart' array
field("cart").arrayLength();
Returns the maximum value in the array.
<b>Signature:</b>
arrayMaximum(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the maximum value.
// Get the maximum value of the 'myArray' field.
field("myArray").arrayMaximum();
Returns the largest n elements of the array.
Note: Returns the n largest non-null elements in the array, in descending order. This does not use a stable sort, meaning the order of equivalent elements is undefined.
<b>Signature:</b>
arrayMaximumN(n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the largest n elements.
// Get the largest 3 elements of the 'myArray' field.
field("myArray").arrayMaximumN(3);
Returns the largest n elements of the array.
Note: Returns the n largest non-null elements in the array, in descending order. This does not use a stable sort, meaning the order of equivalent elements is undefined.
<b>Signature:</b>
arrayMaximumN(n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | Expression | An expression evaluating to the number of elements to return. |
<b>Returns:</b>
A new Expression representing the largest n elements.
// Get the largest n elements of the 'myArray' field.
field("myArray").arrayMaximumN(field("count"));
Returns the minimum value in the array.
<b>Signature:</b>
arrayMinimum(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the minimum value.
// Get the minimum value of the 'myArray' field.
field("myArray").arrayMinimum();
Returns the smallest n elements of the array.
Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined.
<b>Signature:</b>
arrayMinimumN(n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the smallest n elements.
// Get the smallest 3 elements of the 'myArray' field.
field("myArray").arrayMinimumN(3);
Returns the smallest n elements of the array.
Note: Returns the n smallest non-null elements in the array, in ascending order. This does not use a stable sort, meaning the order of equivalent elements is undefined.
<b>Signature:</b>
arrayMinimumN(n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| n | Expression | An expression evaluating to the number of elements to return. |
<b>Returns:</b>
A new Expression representing the smallest n elements.
// Get the smallest n elements of the 'myArray' field.
field("myArray").arrayMinimumN(field("count"));
Creates an expression that reverses an array.
<b>Signature:</b>
arrayReverse(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the reversed array.
// Reverse the value of the 'myArray' field.
field("myArray").arrayReverse();
Returns a subset of the array.
<b>Signature:</b>
arraySlice(offset: number | Expression, length?: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| offset | number | Expression | The starting offset. |
| length | number | Expression | The optional length of the slice. |
<b>Returns:</b>
A new Expression representing the sliced array.
// Get 5 elements from the 'items' array starting from index 2
field("items").arraySlice(2, 5);
// Get n number of elements from the 'items' array starting from index 2
field("items").arraySlice(2, field("count"));
Creates an expression that computes the sum of the elements in an array.
<b>Signature:</b>
arraySum(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the sum of the elements in the array.
// Compute the sum of the elements in the 'scores' field.
field("scores").arraySum();
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
arrayTransform(elementAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elementAlias | string | The variable name to use for each element. |
| transform | Expression | The lambda expression used to transform the elements. |
<b>Returns:</b>
A new Expression representing the arrayTransform operation.
// Transform the 'scores' array by multiplying each score by 10
field("scores").arrayTransform("score", multiply(variable("score"), 10));
Creates an expression that applies a provided transformation to each element in an array, providing the element's index to the transformation expression.
<b>Signature:</b>
arrayTransformWithIndex(elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | Expression | The lambda expression used to transform the elements. |
<b>Returns:</b>
A new Expression representing the arrayTransformWithIndex operation.
// Transform the 'scores' array by adding the index to each score
field("scores").arrayTransformWithIndex("score", "i", add(variable("score"), variable("i")));
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.
<b>Signature:</b>
as(name: string): AliasedExpression;
| Parameter | Type | Description |
|---|---|---|
| name | string | The alias to assign to this expression. |
<b>Returns:</b>
A new AliasedExpression that wraps this expression and associates it with the provided alias.
// 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"));
Wraps the expression in a [BooleanExpression].
<b>Signature:</b>
asBoolean(): BooleanExpression;
<b>Returns:</b>
A [BooleanExpression] representing the same expression.
Creates an Ordering that sorts documents in ascending order based on this expression.
<b>Signature:</b>
ascending(): Ordering;
<b>Returns:</b>
A new Ordering for ascending sorting.
// Sort documents by the 'name' field in ascending order
firestore.pipeline().collection("users")
.sort(field("name").ascending());
Creates an aggregation that calculates the average (mean) of a numeric field across multiple stage inputs.
<b>Signature:</b>
average(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'average' aggregation.
// Calculate the average age of users
field("age").average().as("averageAge");
Creates an expression that calculates the length of this string expression in bytes.
<b>Signature:</b>
byteLength(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the length of the string in bytes.
// Calculate the length of the 'myString' field in bytes.
field("myString").byteLength();
Creates an expression that computes the ceiling of a numeric value.
<b>Signature:</b>
ceil(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the ceiling of the numeric value.
// Compute the ceiling of the 'price' field.
field("price").ceil();
Creates an expression that calculates the character length of a string in UTF-8.
<b>Signature:</b>
charLength(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the length of the string.
// Get the character length of the 'name' field in its UTF-8 form.
field("name").charLength();
Creates an expression that returns the first non-null, non-absent argument, without evaluating the rest of the arguments. When all arguments are null or absent, returns the last argument.
<b>Signature:</b>
coalesce(replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| replacement | Expression | unknown | The value to use if this expression evaluates to null. |
| others | Array<Expression | unknown> | Optional additional values to check if previous values are null. |
<b>Returns:</b>
A new Expression representing the coalesce operation.
// Returns the value of the first non-null, non-absent field among 'preferredName', 'fullName',
// or the last argument if all previous fields are null.
field("preferredName").coalesce(field("fullName"), "Anonymous");
Creates an expression that returns the collection ID from a path.
<b>Signature:</b>
collectionId(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the collectionId operation.
// Get the collection ID from a path.
field("__path__").collectionId();
Creates an expression that concatenates expression results together.
<b>Signature:</b>
concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| second | Expression | unknown | The additional expression or literal to concatenate. |
| others | Array<Expression | unknown> | Optional additional expressions or literals to concatenate. |
<b>Returns:</b>
A new Expression representing the concatenated value.
// Combine the 'firstName', ' ', and 'lastName' fields into a single value.
field("firstName").concat(constant(" "), field("lastName"));
Calculates the cosine distance between two vectors.
<b>Signature:</b>
cosineDistance(vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The other vector (represented as an Expression) to compare against. |
<b>Returns:</b>
A new Expression representing the cosine distance between the two vectors.
// Calculate the cosine distance between the 'userVector' field and the 'itemVector' field
field("userVector").cosineDistance(field("itemVector"));
Calculates the Cosine distance between two vectors.
<b>Signature:</b>
cosineDistance(vector: VectorValue | number[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vector | VectorValue | number[] | The other vector (as a VectorValue) to compare against. |
<b>Returns:</b>
A new Expression representing the Cosine* distance between the two vectors.
// Calculate the Cosine distance between the 'location' field and a target location
field("location").cosineDistance(new VectorValue([37.7749, -122.4194]));
Creates an aggregation that counts the number of stage inputs with valid evaluations of the expression or field.
<b>Signature:</b>
count(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'count' aggregation.
// Count the total number of products
field("productId").count().as("totalProducts");
Creates an aggregation that counts the number of distinct values of the expression or field.
<b>Signature:</b>
countDistinct(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'count_distinct' aggregation.
// Count the distinct number of products
field("productId").countDistinct().as("distinctProducts");
Creates an Ordering that sorts documents in descending order based on this expression.
<b>Signature:</b>
descending(): Ordering;
<b>Returns:</b>
A new Ordering for descending sorting.
// Sort documents by the 'createdAt' field in descending order
firestore.pipeline().collection("users")
.sort(field("createdAt").descending());
Creates an expression that divides this expression by another expression.
<b>Signature:</b>
divide(divisor: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| divisor | Expression | The expression to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'total' field by the 'count' field
field("total").divide(field("count"));
Creates an expression that divides this expression by a constant value.
<b>Signature:</b>
divide(divisor: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| divisor | number | The constant value to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'value' field by 10
field("value").divide(10);
Creates an expression that returns the document ID from a path.
<b>Signature:</b>
documentId(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the documentId operation.
// Get the document ID from a path.
field("__path__").documentId();
Calculates the dot product between two vectors.
<b>Signature:</b>
dotProduct(vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The other vector (as an array of numbers) to calculate with. |
<b>Returns:</b>
A new Expression representing the dot product between the two vectors.
// Calculate the dot product between a feature vector and a target vector
field("features").dotProduct([0.5, 0.8, 0.2]);
Calculates the dot product between two vectors.
<b>Signature:</b>
dotProduct(vector: VectorValue | number[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vector | VectorValue | number[] | The other vector (as an array of numbers) to calculate with. |
<b>Returns:</b>
A new Expression representing the dot product between the two vectors.
// Calculate the dot product between a feature vector and a target vector
field("features").dotProduct(new VectorValue([0.5, 0.8, 0.2]));
Creates an expression that checks if a string ends with a given postfix.
<b>Signature:</b>
endsWith(suffix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| suffix | string | The postfix to check for. |
<b>Returns:</b>
A new Expression representing the 'ends with' comparison.
// Check if the 'filename' field ends with ".txt"
field("filename").endsWith(".txt");
Creates an expression that checks if a string ends with a given postfix (represented as an expression).
<b>Signature:</b>
endsWith(suffix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| suffix | Expression | The postfix expression to check for. |
<b>Returns:</b>
A new Expression representing the 'ends with' comparison.
// Check if the 'url' field ends with the value of the 'extension' field
field("url").endsWith(field("extension"));
Creates an expression that checks if this expression is equal to another expression.
<b>Signature:</b>
equal(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare for equality. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'age' field is equal to 21
field("age").equal(21);
Creates an expression that checks if this expression is equal to a constant value.
<b>Signature:</b>
equal(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for equality. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'city' field is equal to "London"
field("city").equal("London");
Creates an expression that checks if this expression is equal to any of the provided values or expressions.
<b>Signature:</b>
equalAny(values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| values | Array<Expression | unknown> | The values or expressions to check against. |
<b>Returns:</b>
A new Expression representing the 'IN' comparison.
// Check if the 'category' field is either "Electronics" or value of field 'primaryType'
field("category").equalAny(["Electronics", field("primaryType")]);
Creates an expression that checks if this expression is equal to any of the provided values or expressions.
<b>Signature:</b>
equalAny(arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | An expression that evaluates to an array of values to check against. |
<b>Returns:</b>
A new Expression representing the 'IN' comparison.
// Check if the 'category' field is either "Electronics" or value of field 'primaryType'
field("category").equalAny(array(["Electronics", field("primaryType")]));
Calculates the Euclidean distance between two vectors.
<b>Signature:</b>
euclideanDistance(vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The other vector (as an array of numbers) to calculate with. |
<b>Returns:</b>
A new Expression representing the Euclidean distance between the two vectors.
// Calculate the Euclidean distance between the 'location' field and a target location
field("location").euclideanDistance([37.7749, -122.4194]);
Calculates the Euclidean distance between two vectors.
<b>Signature:</b>
euclideanDistance(vector: VectorValue | number[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vector | VectorValue | number[] | The other vector (as a VectorValue) to compare against. |
<b>Returns:</b>
A new Expression representing the Euclidean distance between the two vectors.
// Calculate the Euclidean distance between the 'location' field and a target location
field("location").euclideanDistance(new VectorValue([37.7749, -122.4194]));
Creates an expression that checks if a field exists in the document.
<b>Signature:</b>
exists(): BooleanExpression;
<b>Returns:</b>
A new Expression representing the 'exists' check.
// Check if the document has a field named "phoneNumber"
field("phoneNumber").exists();
Creates an expression that computes e to the power of this expression.
<b>Signature:</b>
exp(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the exp of the numeric value.
// Compute e to the power of the 'value' field.
field("value").exp();
Creates an aggregation that finds the first value of an expression across multiple stage inputs.
<b>Signature:</b>
first(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'first' aggregation.
// Find the first value of the 'rating' field
field("rating").first().as("firstRating");
Creates an expression that computes the floor of a numeric value.
<b>Signature:</b>
floor(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the floor of the numeric value.
// Compute the floor of the 'price' field.
field("price").floor();
Creates an expression that returns the value of a field from the document that results from the evaluation of this expression.
<b>Signature:</b>
getField(key: string | Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| key | string | Expression | The field to access in the document. |
<b>Returns:</b>
A new Expression representing the value of the field in the document.
// Get the value of the "city" field in the "address" document.
field("address").getField("city")
Creates an expression that checks if this expression is greater than another expression.
<b>Signature:</b>
greaterThan(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare for greater than. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the 'age' field is greater than the 'limit' field
field("age").greaterThan(field("limit"));
Creates an expression that checks if this expression is greater than a constant value.
<b>Signature:</b>
greaterThan(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for greater than. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the 'price' field is greater than 100
field("price").greaterThan(100);
Creates an expression that checks if this expression is greater than or equal to another expression.
<b>Signature:</b>
greaterThanOrEqual(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare for greater than or equal to. |
<b>Returns:</b>
A new Expression representing the greater than or equal to comparison.
// Check if the 'quantity' field is greater than or equal to field 'requirement' plus 1
field("quantity").greaterThanOrEqual(field('requirement').add(1));
Creates an expression that checks if this expression is greater than or equal to a constant value.
<b>Signature:</b>
greaterThanOrEqual(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for greater than or equal to. |
<b>Returns:</b>
A new Expression representing the greater than or equal to comparison.
// Check if the 'score' field is greater than or equal to 80
field("score").greaterThanOrEqual(80);
Creates an expression that returns the elseValue argument if this expression results in an absent value, else return the result of this expression evaluation.
<b>Signature:</b>
ifAbsent(elseValue: unknown): Expression;
| Parameter | Type | Description |
|---|---|---|
| elseValue | unknown | The value that will be returned if this Expression evaluates to an absent value. |
<b>Returns:</b>
A new [Expression] representing the ifAbsent operation.
// Returns the value of the optional field 'optional_field', or returns 'default_value'
// if the field is absent.
field("optional_field").ifAbsent("default_value")
Creates an expression that returns the elseValue argument if this expression results in an absent value, else return the result of this expression evaluation.
<b>Signature:</b>
ifAbsent(elseExpression: unknown): Expression;
| Parameter | Type | Description |
|---|---|---|
| elseExpression | unknown | The Expression that will be evaluated if this Expression evaluates to an absent value. |
<b>Returns:</b>
A new [Expression] representing the ifAbsent operation.
// Returns the value of the optional field 'optional_field', or if that is
// absent, then returns the value of the field `default_field`.
field("optional_field").ifAbsent(field('default_field'))
Creates an expression that returns the result of the catchExpr argument if there is an error, else return the result of this expression.
<b>Signature:</b>
ifError(catchExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| catchExpr | Expression | The catch expression that will be evaluated and returned if this expression produces an error. |
<b>Returns:</b>
A new Expression representing the 'ifError' operation.
// 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"));
Creates an expression that returns the catch argument if there is an error, else return the result of this expression.
<b>Signature:</b>
ifError(catchValue: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| catchValue | unknown | The value that will be returned if this expression produces an error. |
<b>Returns:</b>
A new Expression representing the 'ifError' operation.
// Returns the first item in the title field arrays, or returns
// "Default Title"
field("title").arrayGet(0).ifError("Default Title");
Creates an expression that returns the elseValue argument if this expression evaluates to null, else return the result of this expression evaluation.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
ifNull(elseExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elseExpression | Expression | The Expression that will be evaluated if this Expression evaluates to null. |
<b>Returns:</b>
A new Expression representing the ifNull operation.
// Returns the user's preferred name, or if that is null, returns their full name.
field("preferredName").ifNull(field("fullName"))
Creates an expression that returns the elseValue argument if this expression evaluates to null, else return the result of this expression evaluation.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
ifNull(elseValue: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elseValue | unknown | The value that will be returned if this Expression evaluates to null. |
<b>Returns:</b>
A new Expression representing the ifNull operation.
// Returns the user's display name, or returns "Anonymous" if the field is null.
field("displayName").ifNull("Anonymous")
Creates an expression that returns true if the result of this expression is absent. Otherwise, returns false even if the value is null<!-- -->.
<b>Signature:</b>
isAbsent(): BooleanExpression;
<b>Returns:</b>
A new BooleanExpression representing the 'isAbsent' check.
// Check if the field `value` is absent.
field("value").isAbsent();
Creates an expression that checks if a given expression produces an error.
<b>Signature:</b>
isError(): BooleanExpression;
<b>Returns:</b>
A new BooleanExpression representing the 'isError' check.
// Check if the result of a calculation is an error
field("title").arrayContains(1).isError();
Creates an expression that checks if the result of this expression is of the given type.
Null or undefined fields evaluate to skip/error. Use ifAbsent() / isAbsent() to evaluate missing data. Supported values for type are: 'null'<!-- -->, 'array'<!-- -->, 'boolean'<!-- -->, 'bytes'<!-- -->, 'timestamp'<!-- -->, 'geo_point'<!-- -->, 'number'<!-- -->, 'int32'<!-- -->, 'int64'<!-- -->, 'float64'<!-- -->, 'decimal128'<!-- -->, 'map'<!-- -->, 'reference'<!-- -->, 'string'<!-- -->, 'vector'<!-- -->, 'max_key'<!-- -->, 'min_key'<!-- -->, 'object_id'<!-- -->, 'regex'<!-- -->, 'request_timestamp'<!-- -->.
<b>Signature:</b>
isType(type: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| type | string | The type to check for. |
<b>Returns:</b>
A new BooleanExpression that evaluates to true if the expression's result is of the given type, false otherwise.
// Check if the 'price' field is specifically an integer (not just 'number')
field('price').isType('int64');
Creates an expression that joins the elements of an array into a string.
<b>Signature:</b>
join(delimiterExpression: Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| delimiterExpression | Expression | The expression that evaluates to the delimiter string. |
<b>Returns:</b>
A new Expression representing the join operation.
// Join the elements of the 'tags' field with the delimiter from the 'separator' field.
field("tags").join(field("separator"))
Creates an expression that joins the elements of an array field into a string.
<b>Signature:</b>
join(delimiter: string): Expression;
| Parameter | Type | Description |
|---|---|---|
| delimiter | string | The string to use as a delimiter. |
<b>Returns:</b>
A new Expression representing the join operation.
// Join the elements of the 'tags' field with a comma and space.
field("tags").join(", ")
Creates an aggregation that finds the last value of an expression across multiple stage inputs.
<b>Signature:</b>
last(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'last' aggregation.
// Find the last value of the 'rating' field
field("rating").last().as("lastRating");
Creates an expression that calculates the length of a string, array, map, vector, or bytes.
<b>Signature:</b>
length(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the length of the string, array, map, vector, or bytes.
// Get the length of the 'name' field.
field("name").length();
// Get the number of items in the 'cart' array.
field("cart").length();
Creates an expression that checks if this expression is less than another expression.
<b>Signature:</b>
lessThan(experession: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| experession | Expression | The expression to compare for less than. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'age' field is less than 'limit'
field("age").lessThan(field('limit'));
Creates an expression that checks if this expression is less than a constant value.
<b>Signature:</b>
lessThan(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for less than. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'price' field is less than 50
field("price").lessThan(50);
Creates an expression that checks if this expression is less than or equal to another expression.
<b>Signature:</b>
lessThanOrEqual(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare for less than or equal to. |
<b>Returns:</b>
A new Expression representing the less than or equal to comparison.
// Check if the 'quantity' field is less than or equal to 20
field("quantity").lessThan(constant(20));
Creates an expression that checks if this expression is less than or equal to a constant value.
<b>Signature:</b>
lessThanOrEqual(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for less than or equal to. |
<b>Returns:</b>
A new Expression representing the less than or equal to comparison.
// Check if the 'score' field is less than or equal to 70
field("score").lessThan(70);
Creates an expression that performs a case-sensitive string comparison.
<b>Signature:</b>
like(pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | string | The pattern to search for. You can use "%" as a wildcard character. |
<b>Returns:</b>
A new Expression representing the 'like' comparison.
// Check if the 'title' field contains the word "guide" (case-sensitive)
field("title").like("%guide%");
Creates an expression that performs a case-sensitive string comparison.
<b>Signature:</b>
like(pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | Expression | The pattern to search for. You can use "%" as a wildcard character. |
<b>Returns:</b>
A new Expression representing the 'like' comparison.
// Check if the 'title' field contains the word "guide" (case-sensitive)
field("title").like("%guide%");
Creates an expression that computes the natural logarithm of a numeric value.
<b>Signature:</b>
ln(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the natural logarithm of the numeric value.
// Compute the natural logarithm of the 'value' field.
field("value").ln();
Creates an expression that computes the base-10 logarithm of a numeric value.
<b>Signature:</b>
log10(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the base-10 logarithm of the numeric value.
// Compute the base-10 logarithm of the 'value' field.
field("value").log10();
Creates an expression that returns the larger value between this expression and another expression, based on Firestore's value type ordering.
<b>Signature:</b>
logicalMaximum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the logical maximum operation.
// Returns the larger value between the 'timestamp' field and the current timestamp.
field("timestamp").logicalMaximum(currentTimestamp());
Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering.
<b>Signature:</b>
logicalMinimum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the logical minimum operation.
// Returns the smaller value between the 'timestamp' field and the current timestamp.
field("timestamp").logicalMinimum(currentTimestamp());
Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array.
<b>Signature:</b>
ltrim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| valueToTrim | string | Expression | Bytes | Optional. A string or byte array containing the characters/bytes to trim. If not specified, whitespace will be trimmed. |
<b>Returns:</b>
A new Expression representing the trimmed string.
// Trim whitespace from the beginning of the 'userInput' field
field("userInput").ltrim();
// Trim quotes from the beginning of the 'userInput' field
field("userInput").ltrim('"');
Creates an expression that returns the entries of a map as an array of maps, where each map contains a "k" property for the key and a "v" property for the value. For example: [{ k: "key1", v: "value1" }, ...]<!-- -->.
<b>Signature:</b>
mapEntries(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the entries of the map.
// Get the entries of the 'address' map
field("address").mapEntries();
Accesses a value from a map (object) field using the provided key.
<b>Signature:</b>
mapGet(subfield: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| subfield | string | The key to access in the map. |
<b>Returns:</b>
A new Expression representing the value associated with the given key in the map.
// Get the 'city' value from the 'address' map field
field("address").mapGet("city");
Creates an expression that returns the keys of a map.
While the backend generally preserves insertion order, relying on the order of the output array is not guaranteed and should be avoided.
<b>Signature:</b>
mapKeys(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the keys of the map.
// Get the keys of the 'address' map
field("address").mapKeys();
Creates an expression that merges multiple map values.
<b>Signature:</b>
mapMerge(secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the 'mapMerge' operation.
// 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}, {})
Creates an expression that removes a key from the map produced by evaluating this expression.
<b>Signature:</b>
mapRemove(key: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| key | string | The name of the key to remove from the input map. |
<b>Returns:</b>
A new Expression representing the 'mapRemove' operation.
// Removes the key 'baz' from the input map.
map({foo: 'bar', baz: true}).mapRemove('baz');
Creates an expression that removes a key from the map produced by evaluating this expression.
<b>Signature:</b>
mapRemove(keyExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| keyExpr | Expression | An expression that produces the name of the key to remove from the input map. |
<b>Returns:</b>
A new Expression representing the 'mapRemove' operation.
// Removes the key 'baz' from the input map.
map({foo: 'bar', baz: true}).mapRemove(constant('baz'));
@example
Creates an expression that returns a new map with the specified entries added or updated.
Note that mapSet only performs shallow updates to the map. Setting a value to null will retain the key with a null value. To remove a key entirely, use mapRemove<!-- -->.
<b>Signature:</b>
mapSet(key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| key | string | Expression | The key to set. Must be a string or a constant string expression. |
| value | unknown | The value to set. |
| moreKeyValues | unknown[] | Additional key-value pairs to set. |
<b>Returns:</b>
A new Expression representing the map with the entries set.
// Set the 'city' to "San Francisco" in the 'address' map
field("address").mapSet("city", "San Francisco");
Creates an expression that returns the values of a map.
While the backend generally preserves insertion order, relying on the order of the output array is not guaranteed and should be avoided.
<b>Signature:</b>
mapValues(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the values of the map.
// Get the values of the 'address' map
field("address").mapValues();
Creates an aggregation that finds the maximum value of a field across multiple stage inputs.
<b>Signature:</b>
maximum(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'maximum' aggregation.
// Find the highest score in a leaderboard
field("score").maximum().as("highestScore");
Creates an aggregation that finds the minimum value of a field across multiple stage inputs.
<b>Signature:</b>
minimum(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'minimum' aggregation.
// Find the lowest price of all products
field("price").minimum().as("lowestPrice");
Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression.
<b>Signature:</b>
mod(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to divide by. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing the 'value' field by the 'divisor' field
field("value").mod(field("divisor"));
Creates an expression that calculates the modulo (remainder) of dividing this expression by a constant value.
<b>Signature:</b>
mod(value: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| value | number | The constant value to divide by. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing the 'value' field by 10
field("value").mod(10);
Creates an expression that multiplies this expression by another expression.
<b>Signature:</b>
multiply(second: Expression | number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| second | Expression | number | The second expression or literal to multiply by. |
<b>Returns:</b>
A new Expression representing the multiplication operation.
// Multiply the 'quantity' field by the 'price' field
field("quantity").multiply(field("price"));
Creates an expression that checks if this expression is not equal to another expression.
<b>Signature:</b>
notEqual(expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare for inequality. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'status' field is not equal to "completed"
field("status").notEqual("completed");
Creates an expression that checks if this expression is not equal to a constant value.
<b>Signature:</b>
notEqual(value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | unknown | The constant value to compare for inequality. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'country' field is not equal to "USA"
field("country").notEqual("USA");
Creates an expression that checks if this expression is not equal to any of the provided values or expressions.
<b>Signature:</b>
notEqualAny(values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| values | Array<Expression | unknown> | The values or expressions to check against. |
<b>Returns:</b>
A new Expression representing the 'notEqualAny' comparison.
// Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
field("status").notEqualAny(["pending", field("rejectedStatus")]);
Creates an expression that checks if this expression is not equal to any of the values in the evaluated expression.
<b>Signature:</b>
notEqualAny(arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The values or expressions to check against. |
<b>Returns:</b>
A new Expression representing the 'notEqualAny' comparison.
// Check if the 'status' field is not equal to any value in the field 'rejectedStatuses'
field("status").notEqualAny(field('rejectedStatuses'));
Creates an expression that returns the parent document reference of a document reference.
<b>Signature:</b>
parent(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the parent operation.
// Get the parent document reference of a document reference.
field("__path__").parent();
Creates an expression that returns the value of this expression raised to the power of another expression.
<b>Signature:</b>
pow(exponent: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| exponent | Expression | The expression to raise this expression to the power of. |
<b>Returns:</b>
A new Expression representing the power operation.
// Raise the value of the 'base' field to the power of the 'exponent' field.
field("base").pow(field("exponent"));
Creates an expression that returns the value of this expression raised to the power of a constant value.
<b>Signature:</b>
pow(exponent: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| exponent | number | The constant value to raise this expression to the power of. |
<b>Returns:</b>
A new Expression representing the power operation.
// Raise the value of the 'base' field to the power of 2.
field("base").pow(2);
Creates an expression that checks if a string contains a specified regular expression as a substring.
<b>Signature:</b>
regexContains(pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | string | The regular expression to use for the search. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains "example" (case-insensitive)
field("description").regexContains("(?i)example");
Creates an expression that checks if a string contains a specified regular expression as a substring.
<b>Signature:</b>
regexContains(pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | Expression | The regular expression to use for the search. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains the regular expression stored in field 'regex'
field("description").regexContains(field("regex"));
Creates an expression that returns the first substring of a string expression that matches a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
regexFind(pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract the domain from an email address
field("email").regexFind("@.+")
Creates an expression that returns the first substring of a string expression that matches a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
regexFind(pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract the domain from an email address
field("email").regexFind(field("domain"))
Creates an expression that evaluates to a list of all substrings in this string expression that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
regexFindAll(pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new Expression that evaluates to an array of matched substrings.
// Extract all hashtags from a post content field
field("content").regexFindAll("#[A-Za-z0-9_]+")
Creates an expression that evaluates to a list of all substrings in this string expression that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
regexFindAll(pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new Expression that evaluates to an array of matched substrings.
// Extract all names from a post content field
field("content").regexFindAll(field("names"))
Creates an expression that checks if a string matches a specified regular expression.
<b>Signature:</b>
regexMatch(pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | string | The regular expression to use for the match. |
<b>Returns:</b>
A new Expression representing the regular expression match.
// 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,}");
Creates an expression that checks if a string matches a specified regular expression.
<b>Signature:</b>
regexMatch(pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| pattern | Expression | The regular expression to use for the match. |
<b>Returns:</b>
A new Expression representing the regular expression match.
// Check if the 'email' field matches a regular expression stored in field 'regex'
field("email").regexMatch(field("regex"));
Creates an expression that reverses this string expression.
<b>Signature:</b>
reverse(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
field("myString").reverse();
Creates an expression that rounds a numeric value to the nearest whole number.
<b>Signature:</b>
round(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the rounded value.
// Round the value of the 'price' field.
field("price").round();
Creates an expression that rounds a numeric value to the specified number of decimal places.
<b>Signature:</b>
round(decimalPlaces: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| decimalPlaces | number | A constant specifying the rounding precision in decimal places. |
<b>Returns:</b>
A new Expression representing the rounded value.
// Round the value of the 'price' field to two decimal places.
field("price").round(2);
Creates an expression that rounds a numeric value to the specified number of decimal places.
<b>Signature:</b>
round(decimalPlaces: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| decimalPlaces | Expression | An expression specifying the rounding precision in decimal places. |
<b>Returns:</b>
A new Expression representing the rounded value.
// Round the value of the 'price' field to two decimal places.
field("price").round(constant(2));
Trims whitespace or a specified set of characters/bytes from the end of a string or byte array.
<b>Signature:</b>
rtrim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| valueToTrim | string | Expression | Bytes | Optional. A string or byte array containing the characters/bytes to trim. If not specified, whitespace will be trimmed. |
<b>Returns:</b>
A new Expression representing the trimmed string or byte array.
// Trim whitespace from the end of the 'userInput' field
field("userInput").rtrim();
// Trim quotes from the end of the 'userInput' field
field("userInput").rtrim('"');
Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter.
<b>Signature:</b>
split(delimiter: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| delimiter | string |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scoresCsv' field on delimiter ','
field('scoresCsv').split(',')
Creates an expression that splits the result of this expression into an array of substrings based on the provided delimiter.
<b>Signature:</b>
split(delimiter: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| delimiter | Expression |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scores' field on delimiter ',' or ':' depending on the stored format
field('scores').split(conditional(field('format').equal('csv'), constant(','), constant(':')))
Creates an expression that computes the square root of a numeric value.
<b>Signature:</b>
sqrt(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the square root of the numeric value.
// Compute the square root of the 'value' field.
field("value").sqrt();
Creates an expression that checks if a string starts with a given prefix.
<b>Signature:</b>
startsWith(prefix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| prefix | string | The prefix to check for. |
<b>Returns:</b>
A new Expression representing the 'starts with' comparison.
// Check if the 'name' field starts with "Mr."
field("name").startsWith("Mr.");
Creates an expression that checks if a string starts with a given prefix (represented as an expression).
<b>Signature:</b>
startsWith(prefix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| prefix | Expression | The prefix expression to check for. |
<b>Returns:</b>
A new Expression representing the 'starts with' comparison.
// Check if the 'fullName' field starts with the value of the 'firstName' field
field("fullName").startsWith(field("firstName"));
Creates an expression that concatenates string expressions together.
<b>Signature:</b>
stringConcat(secondString: Expression | string, ...otherStrings: Array<Expression | string>): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the concatenated string.
// Combine the 'firstName', " ", and 'lastName' fields into a single string
field("firstName").stringConcat(constant(" "), field("lastName"));
Creates an expression that checks if a string contains a specified substring.
<b>Signature:</b>
stringContains(substring: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| substring | string | The substring to search for. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains "example".
field("description").stringContains("example");
Creates an expression that checks if a string contains the string represented by another expression.
<b>Signature:</b>
stringContains(expr: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the substring to search for. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains the value of the 'keyword' field.
field("description").stringContains(field("keyword"));
Creates an expression that finds the index of the first occurrence of a substring or byte sequence.
<b>Signature:</b>
stringIndexOf(search: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| search | string | Expression | Bytes | The substring or byte sequence to search for. |
<b>Returns:</b>
A new Expression representing the index of the first occurrence.
// Find the index of "foo" in the 'text' field
field("text").stringIndexOf("foo");
Creates an expression that repeats a string or byte array a specified number of times.
<b>Signature:</b>
stringRepeat(repetitions: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| repetitions | number | Expression | The number of times to repeat the string or byte array. |
<b>Returns:</b>
A new Expression representing the repeated string or byte array.
// Repeat the 'label' field 3 times
field("label").stringRepeat(3);
Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement.
<b>Signature:</b>
stringReplaceAll(find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| find | string | Expression | Bytes | The substring or byte sequence to search for. |
| replacement | string | Expression | Bytes | The replacement string or byte sequence. |
<b>Returns:</b>
A new Expression representing the string or byte array with replacements.
// Replace all occurrences of "foo" with "bar" in the 'text' field
field("text").stringReplaceAll("foo", "bar");
Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement.
<b>Signature:</b>
stringReplaceOne(find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| find | string | Expression | Bytes | The substring or byte sequence to search for. |
| replacement | string | Expression | Bytes | The replacement string or byte sequence. |
<b>Returns:</b>
A new Expression representing the string or byte array with the replacement.
// Replace the first occurrence of "foo" with "bar" in the 'text' field
field("text").stringReplaceOne("foo", "bar");
Creates an expression that reverses a string.
<b>Signature:</b>
stringReverse(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
field("myString").stringReverse();
Creates an expression that returns a substring of the results of this expression.
<b>Signature:</b>
substring(position: number, length?: number): FunctionExpression;
| 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. |
<b>Returns:</b>
Creates an expression that returns a substring of the results of this expression.
<b>Signature:</b>
substring(position: Expression, length?: Expression): FunctionExpression;
| 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. |
<b>Returns:</b>
Creates an expression that subtracts another expression from this expression.
<b>Signature:</b>
subtract(subtrahend: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| subtrahend | Expression | The expression to subtract from this expression. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract the 'discount' field from the 'price' field
field("price").subtract(field("discount"));
Creates an expression that subtracts a constant value from this expression.
<b>Signature:</b>
subtract(subtrahend: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| subtrahend | number | The constant value to subtract. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract 20 from the value of the 'total' field
field("total").subtract(20);
Creates an aggregation that calculates the sum of a numeric field across multiple stage inputs.
<b>Signature:</b>
sum(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'sum' aggregation.
// Calculate the total revenue from a set of orders
field("orderAmount").sum().as("totalRevenue");
Creates an expression that adds a specified amount of time to this timestamp expression.
<b>Signature:</b>
timestampAdd(unit: Expression, amount: Expression): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the resulting timestamp.
// Add some duration determined by field 'unit' and 'amount' to the 'timestamp' field.
field("timestamp").timestampAdd(field("unit"), field("amount"));
Creates an expression that adds a specified amount of time to this timestamp expression.
<b>Signature:</b>
timestampAdd(unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| unit | TimeUnit | The unit of time to add (e.g., "day", "hour"). |
| amount | number | The amount of time to add. |
<b>Returns:</b>
A new Expression representing the resulting timestamp.
// Add 1 day to the 'timestamp' field.
field("timestamp").timestampAdd("day", 1);
Creates an expression that calculates the difference between this timestamp and another timestamp.
<b>Signature:</b>
timestampDiff(start: Expression, unit: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| start | Expression | The expression evaluating to the starting timestamp. |
| unit | Expression | The expression evaluates to a unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'. |
<b>Returns:</b>
A new Expression representing the difference as an integer.
// Calculate the difference determined by fields 'startTime' and 'unit'.
field("endTime").timestampDiff(field("startTime"), field("unit"));
Creates an expression that calculates the difference between this timestamp and another timestamp.
<b>Signature:</b>
timestampDiff(start: string | Expression, unit: TimeUnit): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| start | string | Expression | The field name of the starting timestamp. |
| unit | TimeUnit | The unit of time for the difference (e.g., "day", "hour"). |
<b>Returns:</b>
A new Expression representing the difference as an integer.
// Calculate the difference in days between 'endTime' and 'startTime' fields.
field("endTime").timestampDiff("startTime", "day");
Creates an expression that extracts a specified part from this timestamp expression.
<b>Signature:</b>
timestampExtract(part: TimePart, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| part | TimePart | The part to extract from the timestamp (e.g., "year", "month", "day"). |
| timezone | string | Expression | The timezone to use for extraction. Valid values are from the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." |
<b>Returns:</b>
A new Expression representing the extracted part as an integer.
// Extract the year from the 'createdAt' field.
field('createdAt').timestampExtract('year')
Creates an expression that extracts a specified part from this timestamp expression.
<b>Signature:</b>
timestampExtract(part: Expression, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| part | Expression | The expression evaluating to the part to extract. |
| timezone | string | Expression | The timezone to use for extraction. Valid values are from the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1." |
<b>Returns:</b>
A new Expression representing the extracted part as an integer.
// Extract the part specified by the field 'extractionPart' from 'createdAt'.
field('createdAt').timestampExtract(field('extractionPart'))
Creates an expression that subtracts a specified amount of time from this timestamp expression.
<b>Signature:</b>
timestampSubtract(unit: Expression, amount: Expression): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the resulting timestamp.
// Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field.
field("timestamp").timestampSubtract(field("unit"), field("amount"));
Creates an expression that subtracts a specified amount of time from this timestamp expression.
<b>Signature:</b>
timestampSubtract(unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| unit | TimeUnit | The unit of time to subtract (e.g., "day", "hour"). |
| amount | number | The amount of time to subtract. |
<b>Returns:</b>
A new Expression representing the resulting timestamp.
// Subtract 1 day from the 'timestamp' field.
field("timestamp").timestampSubtract("day", 1);
Creates an expression that converts this timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
timestampToUnixMicros(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the number of microseconds since epoch.
// Convert the 'timestamp' field to microseconds since epoch.
field("timestamp").timestampToUnixMicros();
Creates an expression that converts this timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
timestampToUnixMillis(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the number of milliseconds since epoch.
// Convert the 'timestamp' field to milliseconds since epoch.
field("timestamp").timestampToUnixMillis();
Creates an expression that converts this timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
timestampToUnixSeconds(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the number of seconds since epoch.
// Convert the 'timestamp' field to seconds since epoch.
field("timestamp").timestampToUnixSeconds();
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
timestampTruncate(granularity: TimeGranularity, timezone?: string | Expression): FunctionExpression;
| 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". |
<b>Returns:</b>
A new Expression representing the truncated timestamp.
// Truncate the 'createdAt' timestamp to the beginning of the day.
field('createdAt').timestampTruncate('day')
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
timestampTruncate(granularity: Expression, timezone?: string | Expression): FunctionExpression;
| 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". |
<b>Returns:</b>
A new Expression representing the truncated timestamp.
// Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'.
field('createdAt').timestampTruncate(field('granularity'))
Creates an expression that converts a string to lowercase.
<b>Signature:</b>
toLower(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the lowercase string.
// Convert the 'name' field to lowercase
field("name").toLower();
Creates an expression that converts a string to uppercase.
<b>Signature:</b>
toUpper(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the uppercase string.
// Convert the 'title' field to uppercase
field("title").toUpper();
Creates an expression that removes leading and trailing characters from a string or byte array.
<b>Signature:</b>
trim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
| 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. |
<b>Returns:</b>
A new Expression representing the trimmed string or byte array.
// Trim whitespace from the 'userInput' field
field("userInput").trim();
// Trim quotes from the 'userInput' field
field("userInput").trim('"');
Creates an expression that truncates the numeric value to an integer.
<b>Signature:</b>
trunc(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the truncated value.
// Truncate the 'rating' field
field("rating").trunc();
Creates an expression that truncates a numeric value to the specified number of decimal places.
<b>Signature:</b>
trunc(decimalPlaces: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| decimalPlaces | number | A constant specifying the truncation precision in decimal places. |
<b>Returns:</b>
A new Expression representing the truncated value.
// Truncate the value of the 'rating' field to two decimal places.
field("rating").trunc(2);
Creates an expression that truncates a numeric value to the specified number of decimal places.
<b>Signature:</b>
trunc(decimalPlaces: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| decimalPlaces | Expression | An expression specifying the truncation precision in decimal places. |
<b>Returns:</b>
A new Expression representing the truncated value.
// Truncate the value of the 'rating' field to two decimal places.
field("rating").trunc(constant(2));
Creates an expression that returns the data type of this expression's result, as a string.
This is evaluated on the backend. This means: 1. Generic typed elements (like array<string><!-- -->) evaluate strictly to the primitive 'array'<!-- -->. 2. Any custom FirestoreDataConverter mappings are ignored. 3. For numeric values, the backend does not yield the JavaScript "number" type; it evaluates precisely as "int64" or "float64"<!-- -->. 4. For date or timestamp objects, the backend evaluates to "timestamp"<!-- -->.
<b>Signature:</b>
type(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the data type.
// Get the data type of the value in field 'title'
field('title').type()
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.
<b>Signature:</b>
unixMicrosToTimestamp(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'microseconds' field as microseconds since epoch.
field("microseconds").unixMicrosToTimestamp();
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.
<b>Signature:</b>
unixMillisToTimestamp(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'milliseconds' field as milliseconds since epoch.
field("milliseconds").unixMillisToTimestamp();
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.
<b>Signature:</b>
unixSecondsToTimestamp(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'seconds' field as seconds since epoch.
field("seconds").unixSecondsToTimestamp();
Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression.
<b>Signature:</b>
vectorLength(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the length of the vector.
// Get the vector length (dimension) of the field 'embedding'.
field("embedding").vectorLength();