docs-devsite/firestore_lite_pipelines.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 %}
| Function | Description |
|---|---|
| <b>function()</b> | |
| countAll() | Creates an aggregation that counts the total number of stage inputs. |
| currentDocument() | Creates an expression that represents the current document being processed. |
| currentTimestamp() | Creates an expression that evaluates to the current server timestamp. |
| rand() | Creates an expression that generates a random number between 0.0 and 1.0 but not including 1.0. |
| score() | <b><i>(Public Preview)</i></b> Evaluates to the search score that reflects the topicality of the document to all of the text predicates (for example: <code>documentMatches</code>) in the search query. If <code>SearchOptions.query</code> is not set or does not contain any text predicates, then this topicality score will always be <code>0</code>. |
| <b>function(array, ...)</b> | |
| arrayContains(array, element) | Creates an expression that checks if an array expression contains a specific element. |
| arrayContains(array, element) | Creates an expression that checks if an array expression contains a specific element. |
| arrayContainsAll(array, values) | Creates an expression that checks if an array expression contains all the specified elements. |
| arrayContainsAll(array, arrayExpression) | Creates an expression that checks if an array expression contains all the specified elements. |
| arrayContainsAny(array, values) | Creates an expression that checks if an array expression contains any of the specified elements. |
| arrayContainsAny(array, values) | Creates an expression that checks if an array expression contains any of the specified elements. |
| arrayLength(array) | Creates an expression that calculates the length of an array expression. |
| <b>function(arrayExpression, ...)</b> | |
| arrayFilter(arrayExpression, alias, filter) | Creates an expression that filters an array using a provided alias and predicate expression. |
| arrayFirst(arrayExpression) | Creates an expression that returns the first element of an array. |
| arrayFirstN(arrayExpression, n) | Creates an expression that returns the first <code>n</code> elements of an array. |
| arrayFirstN(arrayExpression, n) | Creates an expression that returns the first <code>n</code> elements of an array. |
| arrayGet(arrayExpression, offset) | Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end. |
| arrayGet(arrayExpression, offsetExpr) | Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end. |
| arrayIndexOf(arrayExpression, search) | Creates an expression that returns the first index of the search value in an array. Returns -1 if the value is not found. |
| arrayIndexOfAll(arrayExpression, search) | Creates an expression that returns all indices of the search value in an array. |
| arrayLast(arrayExpression) | Creates an expression that returns the last element of an array. |
| arrayLastIndexOf(arrayExpression, search) | Creates an expression that returns the last index of the search value in an array. Returns -1 if the value is not found. |
| arrayLastN(arrayExpression, n) | Creates an expression that returns the last <code>n</code> elements of an array. |
| arrayLastN(arrayExpression, n) | Creates an expression that returns the last <code>n</code> elements of an array. |
| arrayMaximum(arrayExpression) | Creates an expression that returns the maximum value in an array. |
| arrayMaximumN(arrayExpression, n) | Creates an expression that returns the largest <code>n</code> elements of an 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(arrayExpression, n) | Creates an expression that returns the largest <code>n</code> elements of an 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(arrayExpression) | Creates an expression that returns the minimum value in an array. |
| arrayMinimumN(arrayExpression, n) | Creates an expression that returns the smallest <code>n</code> elements of an 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(arrayExpression, n) | Creates an expression that returns the smallest <code>n</code> elements of an 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. |
| arraySlice(arrayExpression, offset, length) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| arrayTransform(arrayExpression, elementAlias, transform) | Creates an expression that applies a provided transformation to each element in an array. |
| arrayTransformWithIndex(arrayExpression, 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. |
| join(arrayExpression, delimiterExpression) | Creates an expression that joins the elements of an array into a string. |
| join(arrayExpression, delimiter) | Creates an expression that joins the elements of an array into a string. |
| <b>function(arrayField, ...)</b> | |
| arrayGet(arrayField, offset) | Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end. |
| arrayGet(arrayField, offsetExpr) | Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end. |
| <b>function(arrayFieldName, ...)</b> | |
| join(arrayFieldName, delimiter) | Creates an expression that joins the elements of an array into a string. |
| join(arrayFieldName, delimiterExpression) | Creates an expression that joins the elements of an array into a string. |
| <b>function(base, ...)</b> | |
| pow(base, exponent) | Creates an expression that returns the value of the base expression raised to the power of the exponent expression. |
| pow(base, exponent) | Creates an expression that returns the value of the base expression raised to the power of the exponent. |
| pow(base, exponent) | Creates an expression that returns the value of the base field raised to the power of the exponent expression. |
| pow(base, exponent) | Creates an expression that returns the value of the base field raised to the power of the exponent. |
| <b>function(booleanExpr, ...)</b> | |
| countIf(booleanExpr) | Creates an aggregation that counts the number of stage inputs where the provided boolean expression evaluates to true. |
| not(booleanExpr) | Creates an expression that negates a filter condition. |
| <b>function(condition, ...)</b> | |
| conditional(condition, thenExpr, elseExpr) | Creates a conditional expression that evaluates to a 'then' expression if a condition is true and an 'else' expression if the condition is false. |
| switchOn(condition, result, others) | Creates an expression that evaluates to the result corresponding to the first true condition. |
| <b>function(documentPath, ...)</b> | |
| documentId(documentPath) | Creates an expression that returns the document ID from a path. |
| parent_2(documentPath) | Creates an expression that returns the parent document reference of a document reference. |
| <b>function(documentPathExpr, ...)</b> | |
| documentId(documentPathExpr) | Creates an expression that returns the document ID from a path. |
| parent_2(documentPathExpr) | Creates an expression that returns the parent document reference of a document reference. |
| <b>function(element, ...)</b> | |
| notEqualAny(element, values) | Creates an expression that checks if an expression is not equal to any of the provided values or expressions. |
| notEqualAny(element, arrayExpression) | Creates an expression that checks if an expression is not equal to any of the provided values or expressions. |
| <b>function(elements, ...)</b> | |
| array(elements) | Creates an expression that creates a Firestore array value from an input array. |
| map(elements) | Creates an expression that creates a Firestore map value from an input object. |
| <b>function(endExpression, ...)</b> | |
| timestampDiff(endExpression, startFieldName, unit) | Creates an expression that calculates the difference between two timestamps. |
| timestampDiff(endExpression, startExpression, unit) | Creates an expression that calculates the difference between two timestamps. |
| <b>function(endFieldName, ...)</b> | |
| timestampDiff(endFieldName, startFieldName, unit) | |
| timestampDiff(endFieldName, startExpression, unit) | Creates an expression that calculates the difference between two timestamps. |
| <b>function(expr, ...)</b> | |
| abs(expr) | Creates an expression that computes the absolute value of a numeric value. |
| ascending(expr) | Creates an Ordering that sorts documents in ascending order based on an expression. |
| byteLength(expr) | Creates an expression that calculates the byte length of a string in UTF-8, or just the length of a Blob. |
| countDistinct(expr) | Creates an aggregation that counts the number of distinct values of a field. |
| descending(expr) | Creates an Ordering that sorts documents in descending order based on an expression. |
| floor(expr) | Creates an expression that computes the floor of a numeric value. |
| timestampToUnixMicros(expr) | Creates an expression that converts a timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| timestampToUnixMillis(expr) | Creates an expression that converts a timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| timestampToUnixSeconds(expr) | Creates an expression that converts a timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| unixMicrosToTimestamp(expr) | Creates an expression that interprets an expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| unixMillisToTimestamp(expr) | Creates an expression that interprets an expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| unixSecondsToTimestamp(expr) | Creates an expression that interprets an expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| <b>function(expression, ...)</b> | |
| arrayAgg(expression) | Creates an aggregation that collects all values of an expression across multiple stage inputs into an array. |
| arrayAggDistinct(expression) | Creates an aggregation that collects all distinct values of an expression across multiple stage inputs into an array. |
| arraySum(expression) | Creates an expression that computes the sum of the elements in an array. |
| average(expression) | Creates an aggregation that calculates the average (mean) of values from an expression across multiple stage inputs. |
| ceil(expression) | Creates an expression that computes the ceiling of a numeric value. |
| coalesce(expression, 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(expression) | Creates an expression that returns the collection ID from a path. |
| count(expression) | Creates an aggregation that counts the number of stage inputs with valid evaluations of the provided expression. |
| divide(expression, value) | Creates an expression that divides an expression by a constant value. |
| equal(expression, value) | Creates an expression that checks if an expression is equal to a constant value. |
| equalAny(expression, values) | Creates an expression that checks if an expression, when evaluated, is equal to any of the provided values or expressions. |
| equalAny(expression, arrayExpression) | Creates an expression that checks if an expression is equal to any of the provided values. |
| exp(expression) | Creates an expression that computes e to the power of the expression's result. |
| first(expression) | Creates an aggregation that finds the first value of an expression across multiple stage inputs. |
| greaterThan(expression, value) | Creates an expression that checks if an expression is greater than a constant value. |
| greaterThanOrEqual(expression, value) | Creates an expression that checks if an expression is greater than or equal to a constant value. |
| isType(expression, type) | Creates an expression that checks if the result of an expression is of the given type. |
| last(expression) | Creates an aggregation that finds the last value of an expression across multiple stage inputs. |
| length_2(expression) | Creates an expression that calculates the length of a string, array, map, vector, or bytes. |
| lessThan(expression, value) | Creates an expression that checks if an expression is less than a constant value. |
| lessThanOrEqual(expression, value) | Creates an expression that checks if an expression is less than or equal to a constant value. |
| ln(expression) | Creates an expression that computes the natural logarithm of a numeric value. |
| log(expression, base) | Creates an expression that computes the logarithm of an expression to a given base. |
| log(expression, base) | Creates an expression that computes the logarithm of an expression to a given base. |
| log10(expression) | Creates an expression that computes the base-10 logarithm of a numeric value. |
| ltrim(expression, valueToTrim) | Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array. |
| maximum(expression) | Creates an aggregation that finds the maximum value of an expression across multiple stage inputs. |
| minimum(expression) | Creates an aggregation that finds the minimum value of an expression across multiple stage inputs. |
| mod(expression, value) | Creates an expression that calculates the modulo (remainder) of dividing an expression by a constant. |
| notEqual(expression, value) | Creates an expression that checks if an expression is not equal to a constant value. |
| round(expression) | Creates an expression that rounds a numeric value to the nearest whole number. |
| round(expression, decimalPlaces) | Creates an expression that rounds a numeric value to the specified number of decimal places. |
| rtrim(expression, valueToTrim) | Trims whitespace or a specified set of characters/bytes from the end of a string or byte array. |
| split(expression, delimiter) | Creates an expression that splits a string into an array of substrings based on the provided delimiter. |
| split(expression, delimiter) | Creates an expression that splits a string into an array of substrings based on the provided delimiter. |
| sqrt(expression) | Creates an expression that computes the square root of a numeric value. |
| stringIndexOf(expression, search) | Creates an expression that finds the index of the first occurrence of a substring or byte sequence. |
| stringRepeat(expression, repetitions) | Creates an expression that repeats a string or byte array a specified number of times. |
| stringReplaceAll(expression, find, replacement) | Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement. |
| stringReplaceOne(expression, find, replacement) | Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement. |
| subtract(expression, value) | Creates an expression that subtracts a constant value from an expression. |
| sum(expression) | Creates an aggregation that calculates the sum of values from an expression across multiple stage inputs. |
| trunc(expression) | Creates an expression that truncates the numeric value of an expression to an integer. |
| trunc(expression, decimalPlaces) | Creates an expression that truncates a numeric value to the specified number of decimal places. |
| type(expression) | Creates an expression that returns the data type of an expression's result. |
| <b>function(field, ...)</b> | |
| isAbsent(field) | Creates an expression that returns <code>true</code> if a field is absent. Otherwise, returns <code>false</code> even if the field value is <code>null</code>. |
| reverse(field) | Creates an expression that reverses a string value in the specified field. |
| stringReverse(field) | Creates an expression that reverses a string value in the specified field. |
| substring(field, position, length) | Creates an expression that returns a substring of a string or byte array. |
| substring(field, position, length) | Creates an expression that returns a substring of a string or byte array. |
| <b>function(fieldName, ...)</b> | |
| abs(fieldName) | Creates an expression that computes the absolute value of a numeric value. |
| add(fieldName, second) | Creates an expression that adds a field's value to an expression. |
| arrayAgg(fieldName) | Creates an aggregation that collects all values of a field across multiple stage inputs into an array. |
| arrayAggDistinct(fieldName) | Creates an aggregation that collects all distinct values of a field across multiple stage inputs into an array. |
| arrayContains(fieldName, element) | Creates an expression that checks if a field's array value contains a specific element. |
| arrayContains(fieldName, element) | Creates an expression that checks if a field's array value contains a specific value. |
| arrayContainsAll(fieldName, values) | Creates an expression that checks if a field's array value contains all the specified values or expressions. |
| arrayContainsAll(fieldName, arrayExpression) | Creates an expression that checks if a field's array value contains all the specified values or expressions. |
| arrayContainsAny(fieldName, values) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| arrayContainsAny(fieldName, values) | Creates an expression that checks if a field's array value contains any of the specified elements. |
| arrayFilter(fieldName, alias, filter) | Creates an expression that filters an array using a provided alias and predicate expression. |
| arrayFirst(fieldName) | Creates an expression that returns the first element of an array. |
| arrayFirstN(fieldName, n) | Creates an expression that returns the first <code>n</code> elements of an array. |
| arrayFirstN(fieldName, n) | Creates an expression that returns the first <code>n</code> elements of an array. |
| arrayIndexOf(fieldName, search) | Creates an expression that returns the first index of the search value in an array. Returns -1 if the value is not found. |
| arrayIndexOfAll(fieldName, search) | Creates an expression that returns all indices of the search value in an array. |
| arrayLast(fieldName) | Creates an expression that returns the last element of an array. |
| arrayLastIndexOf(fieldName, search) | Creates an expression that returns the last index of the search value in an array. Returns -1 if the value is not found. |
| arrayLastN(fieldName, n) | Creates an expression that returns the last <code>n</code> elements of an array. |
| arrayLastN(fieldName, n) | Creates an expression that returns the last <code>n</code> elements of an array. |
| arrayLength(fieldName) | Creates an expression that calculates the length of an array in a specified field. |
| arrayMaximum(fieldName) | Creates an expression that returns the maximum value in an array. |
| arrayMaximumN(fieldName, n) | Creates an expression that returns the largest <code>n</code> elements of an 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(fieldName, n) | Creates an expression that returns the largest <code>n</code> elements of an 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(fieldName) | Creates an expression that returns the minimum value in an array. |
| arrayMinimumN(fieldName, n) | Creates an expression that returns the smallest <code>n</code> elements of an 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(fieldName, n) | Creates an expression that returns the smallest <code>n</code> elements of an 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. |
| arraySlice(fieldName, offset, length) | Creates an expression that returns a slice of an array from <code>offset</code> with <code>length</code> elements. |
| arraySum(fieldName) | Creates an expression that computes the sum of the elements in an array. |
| arrayTransform(fieldName, elementAlias, transform) | Creates an expression that applies a provided transformation to each element in an array. |
| arrayTransformWithIndex(fieldName, 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. |
| ascending(fieldName) | Creates an Ordering that sorts documents in ascending order based on a field. |
| average(fieldName) | Creates an aggregation that calculates the average (mean) of a field's values across multiple stage inputs. |
| byteLength(fieldName) | Creates an expression that calculates the length of a string represented by a field in UTF-8 bytes, or just the length of a Blob. |
| ceil(fieldName) | Creates an expression that computes the ceiling of a numeric value. |
| charLength(fieldName) | Creates an expression that calculates the character length of a string field in UTF8. |
| coalesce(fieldName, 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(fieldName) | Creates an expression that returns the collection ID from a path. |
| concat(fieldName, second, others) | Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed. |
| cosineDistance(fieldName, vector) | Calculates the Cosine distance between a field's vector value and a literal vector value. |
| cosineDistance(fieldName, vectorExpression) | Calculates the Cosine distance between a field's vector value and a vector expression. |
| count(fieldName) | Creates an aggregation that counts the number of stage inputs where the input field exists. |
| descending(fieldName) | Creates an Ordering that sorts documents in descending order based on a field. |
| divide(fieldName, expressions) | Creates an expression that divides a field's value by an expression. |
| divide(fieldName, value) | Creates an expression that divides a field's value by a constant value. |
| dotProduct(fieldName, vector) | Calculates the dot product between a field's vector value and a double array. |
| dotProduct(fieldName, vectorExpression) | Calculates the dot product between a field's vector value and a vector expression. |
| endsWith(fieldName, suffix) | Creates an expression that checks if a field's value ends with a given postfix. |
| endsWith(fieldName, suffix) | Creates an expression that checks if a field's value ends with a given postfix. |
| equal(fieldName, expression) | Creates an expression that checks if a field's value is equal to an expression. |
| equal(fieldName, value) | Creates an expression that checks if a field's value is equal to a constant value. |
| equalAny(fieldName, values) | Creates an expression that checks if a field's value is equal to any of the provided values or expressions. |
| equalAny(fieldName, arrayExpression) | Creates an expression that checks if a field's value is equal to any of the provided values or expressions. |
| euclideanDistance(fieldName, vector) | Calculates the Euclidean distance between a field's vector value and a double array. |
| euclideanDistance(fieldName, vectorExpression) | Calculates the Euclidean distance between a field's vector value and a vector expression. |
| exists(fieldName) | Creates an expression that checks if a field exists. |
| exp(fieldName) | Creates an expression that computes e to the power of the expression's result. |
| first(fieldName) | Creates an aggregation that finds the first value of a field across multiple stage inputs. |
| floor(fieldName) | Creates an expression that computes the floor of a numeric value. |
| geoDistance(fieldName, location) | <b><i>(Public Preview)</i></b> Evaluates to the distance in meters between the location in the specified field and the query location. |
| greaterThan(fieldName, expression) | Creates an expression that checks if a field's value is greater than an expression. |
| greaterThan(fieldName, value) | Creates an expression that checks if a field's value is greater than a constant value. |
| greaterThanOrEqual(fieldName, value) | Creates an expression that checks if a field's value is greater than or equal to an expression. |
| greaterThanOrEqual(fieldName, value) | Creates an expression that checks if a field's value is greater than or equal to a constant value. |
| isType(fieldName, type) | Creates an expression that checks if the value in the specified field is of the given type. |
| last(fieldName) | Creates an aggregation that finds the last value of a field across multiple stage inputs. |
| length_2(fieldName) | Creates an expression that calculates the length of a string, array, map, vector, or bytes. |
| lessThan(fieldName, expression) | Creates an expression that checks if a field's value is less than an expression. |
| lessThan(fieldName, value) | Creates an expression that checks if a field's value is less than a constant value. |
| lessThanOrEqual(fieldName, expression) | Creates an expression that checks if a field's value is less than or equal to an expression. |
| lessThanOrEqual(fieldName, value) | Creates an expression that checks if a field's value is less than or equal to a constant value. |
| like(fieldName, pattern) | Creates an expression that performs a case-sensitive wildcard string comparison against a field. |
| like(fieldName, pattern) | Creates an expression that performs a case-sensitive wildcard string comparison against a field. |
| ln(fieldName) | Creates an expression that computes the natural logarithm of a numeric value. |
| log(fieldName, base) | Creates an expression that computes the logarithm of a field to a given base. |
| log(fieldName, base) | Creates an expression that computes the logarithm of a field to a given base. |
| log10(fieldName) | Creates an expression that computes the base-10 logarithm of a numeric value. |
| logicalMaximum(fieldName, second, others) | Creates an expression that returns the largest value between multiple input expressions or literal values. Based on Firestore's value type ordering. |
| logicalMinimum(fieldName, second, others) | Creates an expression that returns the smallest value between a field's value and other input expressions or literal values. Based on Firestore's value type ordering. |
| ltrim(fieldName, valueToTrim) | Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array. |
| mapGet(fieldName, subField) | Accesses a value from a map (object) field using the provided key. |
| maximum(fieldName) | Creates an aggregation that finds the maximum value of a field across multiple stage inputs. |
| minimum(fieldName) | Creates an aggregation that finds the minimum value of a field across multiple stage inputs. |
| mod(fieldName, expression) | Creates an expression that calculates the modulo (remainder) of dividing a field's value by an expression. |
| mod(fieldName, value) | Creates an expression that calculates the modulo (remainder) of dividing a field's value by a constant. |
| multiply(fieldName, second) | Creates an expression that multiplies a field's value by an expression. |
| notEqual(fieldName, expression) | Creates an expression that checks if a field's value is not equal to an expression. |
| notEqual(fieldName, value) | Creates an expression that checks if a field's value is not equal to a constant value. |
| notEqualAny(fieldName, values) | Creates an expression that checks if a field's value is not equal to any of the provided values or expressions. |
| notEqualAny(fieldName, arrayExpression) | Creates an expression that checks if a field's value is not equal to any of the values in the evaluated expression. |
| regexContains(fieldName, pattern) | Creates an expression that checks if a string field contains a specified regular expression as a substring. |
| regexContains(fieldName, pattern) | Creates an expression that checks if a string field contains a specified regular expression as a substring. |
| regexFind(fieldName, pattern) | Creates an expression that returns the first substring of a string field that matches a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexFind(fieldName, pattern) | Creates an expression that returns the first substring of a string field that matches a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexFindAll(fieldName, pattern) | Creates an expression that evaluates to a list of all substrings in a string field that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexFindAll(fieldName, pattern) | Creates an expression that evaluates to a list of all substrings in a string field that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexMatch(fieldName, pattern) | Creates an expression that checks if a string field matches a specified regular expression. |
| regexMatch(fieldName, pattern) | Creates an expression that checks if a string field matches a specified regular expression. |
| round(fieldName) | Creates an expression that rounds a numeric value to the nearest whole number. |
| round(fieldName, decimalPlaces) | Creates an expression that rounds a numeric value to the specified number of decimal places. |
| rtrim(fieldName, valueToTrim) | Trims whitespace or a specified set of characters/bytes from the end of a string or byte array. |
| split(fieldName, delimiter) | Creates an expression that splits the value of a field on the provided delimiter. |
| split(fieldName, delimiter) | Creates an expression that splits the value of a field on the provided delimiter. |
| sqrt(fieldName) | Creates an expression that computes the square root of a numeric value. |
| startsWith(fieldName, prefix) | Creates an expression that checks if a field's value starts with a given prefix. |
| startsWith(fieldName, prefix) | Creates an expression that checks if a field's value starts with a given prefix. |
| stringConcat(fieldName, secondString, otherStrings) | Creates an expression that concatenates string functions, fields or constants together. |
| stringContains(fieldName, substring) | Creates an expression that checks if a string field contains a specified substring. |
| stringContains(fieldName, substring) | Creates an expression that checks if a string field contains a substring specified by an expression. |
| stringIndexOf(fieldName, search) | Creates an expression that finds the index of the first occurrence of a substring or byte sequence. |
| stringRepeat(fieldName, repetitions) | Creates an expression that repeats a string or byte array a specified number of times. |
| stringReplaceAll(fieldName, find, replacement) | Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement. |
| stringReplaceOne(fieldName, find, replacement) | Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement. |
| subtract(fieldName, expression) | Creates an expression that subtracts an expression from a field's value. |
| subtract(fieldName, value) | Creates an expression that subtracts a constant value from a field's value. |
| sum(fieldName) | Creates an aggregation that calculates the sum of a field's values across multiple stage inputs. |
| timestampAdd(fieldName, unit, amount) | Creates an expression that adds a specified amount of time to a timestamp represented by a field. |
| timestampExtract(fieldName, part, timezone) | Creates an expression that extracts a specified part from a timestamp. |
| timestampExtract(fieldName, part, timezone) | Creates an expression that extracts a specified part from a timestamp. |
| timestampSubtract(fieldName, unit, amount) | Creates an expression that subtracts a specified amount of time from a timestamp represented by a field. |
| timestampToUnixMicros(fieldName) | Creates an expression that converts a timestamp field to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| timestampToUnixMillis(fieldName) | Creates an expression that converts a timestamp field to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| timestampToUnixSeconds(fieldName) | Creates an expression that converts a timestamp field to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC). |
| timestampTruncate(fieldName, granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. |
| timestampTruncate(fieldName, granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. |
| toLower(fieldName) | Creates an expression that converts a string field to lowercase. |
| toUpper(fieldName) | Creates an expression that converts a string field to uppercase. |
| trim(fieldName, valueToTrim) | Creates an expression that removes leading and trailing whitespace from a string or byte array. |
| trunc(fieldName) | Creates an expression that truncates the numeric value of a field to an integer. |
| trunc(fieldName, decimalPlaces) | Creates an expression that truncates a numeric expression to the specified number of decimal places. |
| type(fieldName) | Creates an expression that returns the data type of the data in the specified field. |
| unixMicrosToTimestamp(fieldName) | Creates an expression that interprets a field's value as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| unixMillisToTimestamp(fieldName) | Creates an expression that interprets a field's value as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| unixSecondsToTimestamp(fieldName) | Creates an expression that interprets a field's value as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp. |
| vectorLength(fieldName) | Creates an expression that calculates the length of a Firestore Vector represented by a field. |
| <b>function(first, ...)</b> | |
| add(first, second) | Creates an expression that adds two expressions together. |
| and(first, second, more) | Creates an expression that performs a logical 'AND' operation on multiple filter conditions. |
| concat(first, second, others) | Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed. |
| logicalMaximum(first, second, others) | Creates an expression that returns the largest value between multiple input expressions or literal values. Based on Firestore's value type ordering. |
| logicalMinimum(first, second, others) | Creates an expression that returns the smallest value between multiple input expressions and literal values. Based on Firestore's value type ordering. |
| multiply(first, second) | Creates an expression that multiplies two expressions together. |
| nor(first, second, more) | Creates an expression that performs a logical 'NOR' operation on multiple filter conditions. |
| or(first, second, more) | Creates an expression that performs a logical 'OR' operation on multiple filter conditions. |
| xor(first, second, additionalConditions) | Creates an expression that performs a logical 'XOR' (exclusive OR) operation on multiple BooleanExpressions. |
| <b>function(firstArray, ...)</b> | |
| arrayConcat(firstArray, secondArray, otherArrays) | Creates an expression that concatenates an array expression with other arrays. |
| <b>function(firstArrayField, ...)</b> | |
| arrayConcat(firstArrayField, secondArray, otherArrays) | Creates an expression that concatenates a field's array value with other arrays. |
| <b>function(firstMap, ...)</b> | |
| mapMerge(firstMap, secondMap, otherMaps) | Creates an expression that merges multiple map values. |
| <b>function(firstString, ...)</b> | |
| stringConcat(firstString, secondString, otherStrings) | Creates an expression that concatenates string expressions together. |
| <b>function(ifExpr, ...)</b> | |
| ifAbsent(ifExpr, elseExpr) | Creates an expression that returns the <code>elseExpr</code> argument if <code>ifExpr</code> is absent, else return the result of the <code>ifExpr</code> argument evaluation. |
| ifAbsent(ifExpr, elseValue) | Creates an expression that returns the <code>elseValue</code> argument if <code>ifExpr</code> is absent, else return the result of the <code>ifExpr</code> argument evaluation. |
| ifNull(ifExpr, elseExpr) | Creates an expression that returns the <code>elseExpr</code> argument if <code>ifExpr</code> is null, else return the result of the <code>ifExpr</code> argument evaluation. |
| ifNull(ifExpr, elseValue) | Creates an expression that returns the <code>elseValue</code> argument if <code>ifExpr</code> is null, else return the result of the <code>ifExpr</code> argument evaluation. |
| <b>function(ifFieldName, ...)</b> | |
| ifAbsent(ifFieldName, elseExpr) | Creates an expression that returns the <code>elseExpr</code> argument if <code>ifFieldName</code> is absent, else return the value of the field. |
| ifAbsent(ifFieldName, elseValue) | Creates an expression that returns the <code>elseValue</code> argument if <code>ifFieldName</code> is absent, else return the value of the field. |
| ifNull(ifFieldName, elseExpr) | Creates an expression that returns the <code>elseExpr</code> argument if <code>ifFieldName</code> field is null, else return the value of the field. |
| ifNull(ifFieldName, elseValue) | Creates an expression that returns the <code>elseValue</code> argument if <code>ifFieldName</code> field is null, else return the value of the field. |
| <b>function(input, ...)</b> | |
| substring(input, position, length) | Creates an expression that returns a substring of a string or byte array. |
| substring(input, position, length) | Creates an expression that returns a substring of a string or byte array. |
| <b>function(left, ...)</b> | |
| divide(left, right) | Creates an expression that divides two expressions. |
| equal(left, right) | Creates an expression that checks if two expressions are equal. |
| greaterThan(left, right) | Creates an expression that checks if the first expression is greater than the second expression. |
| greaterThanOrEqual(left, right) | Creates an expression that checks if the first expression is greater than or equal to the second expression. |
| lessThan(left, right) | Creates an expression that checks if the first expression is less than the second expression. |
| lessThanOrEqual(left, right) | Creates an expression that checks if the first expression is less than or equal to the second expression. |
| mod(left, right) | Creates an expression that calculates the modulo (remainder) of dividing two expressions. |
| notEqual(left, right) | Creates an expression that checks if two expressions are not equal. |
| subtract(left, right) | Creates an expression that subtracts two expressions. |
| <b>function(mapExpr, ...)</b> | |
| mapRemove(mapExpr, key) | Creates an expression that removes a key from the map produced by evaluating an expression. |
| mapRemove(mapExpr, keyExpr) | Creates an expression that removes a key from the map produced by evaluating an expression. |
| <b>function(mapExpression, ...)</b> | |
| mapEntries(mapExpression) | 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(mapExpression, subField) | Accesses a value from a map (object) expression using the provided key. |
| mapKeys(mapExpression) | Creates an expression that returns the keys of a map. |
| mapSet(mapExpression, key, value, moreKeyValues) | Creates an expression that returns a new map with the specified entries added or updated. |
| mapValues(mapExpression) | Creates an expression that returns the values of a map. |
| <b>function(mapField, ...)</b> | |
| mapEntries(mapField) | 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>. |
| mapKeys(mapField) | Creates an expression that returns the keys of a map. |
| mapMerge(mapField, secondMap, otherMaps) | Creates an expression that merges multiple map values. |
| mapRemove(mapField, key) | Creates an expression that removes a key from the map at the specified field name. |
| mapRemove(mapField, keyExpr) | Creates an expression that removes a key from the map at the specified field name. |
| mapSet(mapField, key, value, moreKeyValues) | Creates an expression that returns a new map with the specified entries added or updated. |
| mapValues(mapField) | Creates an expression that returns the values of a map. |
| <b>function(name, ...)</b> | |
| field(name) | Creates a Field instance representing the field at the given path.<!-- -->The path can be a simple field name (e.g., "name") or a dot-separated path to a nested field (e.g., "address.city"). |
| variable(name) | Creates an expression that retrieves the value of a variable bound via <code>define()</code>. |
| <b>function(options, ...)</b> | |
| subcollection(options) | Creates a new Pipeline targeted at a subcollection relative to the current document context. This creates a pipeline without a database instance, suitable for embedding as a subquery. If executed directly, this pipeline will fail. |
| <b>function(path, ...)</b> | |
| field(path) | Creates a Field instance representing the field at the given path. |
| subcollection(path) | Creates a new Pipeline targeted at a subcollection relative to the current document context. This creates a pipeline without a database instance, suitable for embedding as a subquery. If executed directly, this pipeline will fail. |
| <b>function(pipeline, ...)</b> | |
| execute(pipeline) | Executes this pipeline and returns a Promise to represent the asynchronous operation.<!-- -->The returned Promise can be used to track the progress of the pipeline execution and retrieve the results (or handle any errors) asynchronously.<!-- -->The pipeline results are returned as a PipelineSnapshot that contains a list of PipelineResult objects. Each PipelineResult typically represents a single key/value map that has passed through all the stages of the pipeline, however this might differ depending on the stages involved in the pipeline. For example:<ul> <li>If there are no stages or only transformation stages, each PipelineResult represents a single document.</li> <li>If there is an aggregation, only a single PipelineResult is returned, representing the aggregated results over the entire dataset .</li> <li>If there is an aggregation stage with grouping, each PipelineResult represents a distinct group and its associated aggregated values.</li> </ul> |
| <b>function(rquery, ...)</b> | |
| documentMatches(rquery) | <b><i>(Public Preview)</i></b> Perform a full-text search on all indexed search fields in the document. |
| <b>function(stringExpression, ...)</b> | |
| charLength(stringExpression) | Creates an expression that calculates the character length of a string expression in UTF-8. |
| endsWith(stringExpression, suffix) | Creates an expression that checks if a string expression ends with a given postfix. |
| endsWith(stringExpression, suffix) | Creates an expression that checks if a string expression ends with a given postfix. |
| like(stringExpression, pattern) | Creates an expression that performs a case-sensitive wildcard string comparison. |
| like(stringExpression, pattern) | Creates an expression that performs a case-sensitive wildcard string comparison. |
| regexContains(stringExpression, pattern) | Creates an expression that checks if a string expression contains a specified regular expression as a substring. |
| regexContains(stringExpression, pattern) | Creates an expression that checks if a string expression contains a specified regular expression as a substring. |
| regexFind(stringExpression, 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(stringExpression, 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(stringExpression, pattern) | Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexFindAll(stringExpression, pattern) | Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression.<!-- -->This expression uses the RE2 regular expression syntax. |
| regexMatch(stringExpression, pattern) | Creates an expression that checks if a string expression matches a specified regular expression. |
| regexMatch(stringExpression, pattern) | Creates an expression that checks if a string expression matches a specified regular expression. |
| reverse(stringExpression) | Creates an expression that reverses a string. |
| startsWith(stringExpression, prefix) | Creates an expression that checks if a string expression starts with a given prefix. |
| startsWith(stringExpression, prefix) | Creates an expression that checks if a string expression starts with a given prefix. |
| stringContains(stringExpression, substring) | Creates an expression that checks if a string expression contains a specified substring. |
| stringContains(stringExpression, substring) | Creates an expression that checks if a string expression contains a substring specified by another expression. |
| stringReverse(stringExpression) | Creates an expression that reverses a string. |
| toLower(stringExpression) | Creates an expression that converts a string expression to lowercase. |
| toUpper(stringExpression) | Creates an expression that converts a string expression to uppercase. |
| trim(stringExpression, valueToTrim) | Creates an expression that removes leading and trailing characters from a string or byte array expression. |
| <b>function(timestamp, ...)</b> | |
| timestampAdd(timestamp, unit, amount) | Creates an expression that adds a specified amount of time to a timestamp. |
| timestampAdd(timestamp, unit, amount) | Creates an expression that adds a specified amount of time to a timestamp. |
| timestampSubtract(timestamp, unit, amount) | Creates an expression that subtracts a specified amount of time from a timestamp. |
| timestampSubtract(timestamp, unit, amount) | Creates an expression that subtracts a specified amount of time from a timestamp. |
| <b>function(timestampExpression, ...)</b> | |
| timestampExtract(timestampExpression, part, timezone) | Creates an expression that extracts a specified part from a timestamp. |
| timestampExtract(timestampExpression, part, timezone) | Creates an expression that extracts a specified part from a timestamp. |
| timestampTruncate(timestampExpression, granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. |
| timestampTruncate(timestampExpression, granularity, timezone) | Creates an expression that truncates a timestamp to a specified granularity. |
| <b>function(tryExpr, ...)</b> | |
| ifError(tryExpr, catchExpr) | Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of the <code>try</code> argument evaluation.<!-- -->This overload is useful when a BooleanExpression is required. |
| ifError(tryExpr, catchExpr) | Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of the <code>try</code> argument evaluation. |
| ifError(tryExpr, catchValue) | Creates an expression that returns the <code>catch</code> argument if there is an error, else return the result of the <code>try</code> argument evaluation. |
| <b>function(value, ...)</b> | |
| constant(value) | Creates a <code>Constant</code> instance for a number value. |
| constant(value) | Creates a <code>Constant</code> instance for a VectorValue value. |
| constant(value) | Creates a <code>Constant</code> instance for a string value. |
| constant(value) | Creates a <code>BooleanExpression</code> instance for a boolean value. |
| constant(value) | Creates a <code>Constant</code> instance for a null value. |
| constant(value) | Creates a <code>Constant</code> instance for a GeoPoint value. |
| constant(value) | Creates a <code>Constant</code> instance for a Timestamp value. |
| constant(value) | Creates a <code>Constant</code> instance for a Date value. |
| constant(value) | Creates a <code>Constant</code> instance for a Bytes value. |
| constant(value) | Creates a <code>Constant</code> instance for a DocumentReference value. |
| exists(value) | Creates an expression that checks if a field exists. |
| isAbsent(value) | Creates an expression that returns <code>true</code> if a value is absent. Otherwise, returns <code>false</code> even if the value is <code>null</code>. |
| isError(value) | Creates an expression that checks if a given expression produces an error. |
| <b>function(vectorExpression, ...)</b> | |
| cosineDistance(vectorExpression, vector) | Calculates the Cosine distance between a vector expression and a vector literal. |
| cosineDistance(vectorExpression, otherVectorExpression) | Calculates the Cosine distance between two vector expressions. |
| dotProduct(vectorExpression, vector) | Calculates the dot product between a vector expression and a double array. |
| dotProduct(vectorExpression, otherVectorExpression) | Calculates the dot product between two vector expressions. |
| euclideanDistance(vectorExpression, vector) | Calculates the Euclidean distance between a vector expression and a double array. |
| euclideanDistance(vectorExpression, otherVectorExpression) | Calculates the Euclidean distance between two vector expressions. |
| vectorLength(vectorExpression) | Creates an expression that calculates the length of a Firestore Vector. |
| Class | Description |
|---|---|
| AggregateFunction | A class that represents an aggregate function. |
| AliasedAggregate | An AggregateFunction with alias. |
| AliasedExpression | |
| BooleanExpression | An interface that represents a filter condition. |
| Bytes | An immutable object representing an array of bytes. |
| CollectionReference | A <code>CollectionReference</code> object can be used for adding documents, getting document references, and querying for documents (using query()<!-- -->). |
| DocumentReference | A <code>DocumentReference</code> refers to a document location in a Firestore database and can be used to write, read, or listen to the location. The document at the referenced location may or may not exist. |
| DocumentSnapshot | A <code>DocumentSnapshot</code> contains data read from a document in your Firestore database. The data can be extracted with <code>.data()</code> or <code>.get(<field>)</code> to get a specific field.<!-- -->For a <code>DocumentSnapshot</code> that points to a non-existing document, any data access will return 'undefined'. You can use the <code>exists()</code> method to explicitly verify a document's existence. |
| Expression | 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:<!-- -->- **Field references:** Access values from document fields. - **Literals:** Represent constant values (strings, numbers, booleans). - **Function calls:** Apply functions to one or more expressions.<!-- -->The <code>Expression</code> class provides a fluent API for building expressions. You can chain together method calls to create complex expressions. |
| Field | Represents a reference to a field in a Firestore document, or outputs of a Pipeline stage.<p>Field references are used to access document field values in expressions and to specify fields for sorting, filtering, and projecting data in Firestore pipelines.<p>You can create a <code>Field</code> instance using the static method: |
| FieldPath | A <code>FieldPath</code> refers to a field in a document. The path may consist of a single field name (referring to a top-level field in the document), or a list of field names (referring to a nested field in the document).<!-- -->Create a <code>FieldPath</code> by providing field names. If more than one field name is provided, the path will point to a nested field in a document. |
| FieldValue | Sentinel values that can be used when writing document fields with <code>set()</code> or <code>update()</code>. |
| Firestore | The Cloud Firestore service interface.<!-- -->Do not call this constructor directly. Instead, use getFirestore()<!-- -->. |
| FunctionExpression | This class defines the base class for Firestore Pipeline functions, which can be evaluated within pipeline execution.<!-- -->Typically, you would not use this class or its children directly. Use either the functions like and()<!-- -->, equal()<!-- -->, or the methods on Expression (Expression.equal()<!-- -->, Expression.lessThan()<!-- -->, etc.) to construct new Function instances. |
| GeoPoint | An immutable object representing a geographic location in Firestore. The location is represented as latitude/longitude pair.<!-- -->Latitude values are in the range of [-90, 90]. Longitude values are in the range of [-180, 180]. |
| Ordering | Represents an ordering criterion for sorting documents in a Firestore pipeline.<!-- -->You create <code>Ordering</code> instances using the <code>ascending</code> and <code>descending</code> helper functions. |
| Pipeline | The Pipeline class provides a flexible and expressive framework for building complex data transformation and query pipelines for Firestore.<!-- -->A pipeline takes data sources, such as Firestore collections or collection groups, and applies a series of stages that are chained together. Each stage takes the output from the previous stage (or the data source) and produces an output for the next stage (or as the final output of the pipeline).<!-- -->Expressions can be used within each stage to filter and transform data through the stage.<!-- -->NOTE: The chained stages do not prescribe exactly how Firestore will execute the pipeline. Instead, Firestore only guarantees that the result is the same as if the chained stages were executed in order.<!-- -->Usage Examples: |
| PipelineResult | A PipelineResult contains data read from a Firestore Pipeline. The data can be extracted with the PipelineResult.data() or PipelineResult.get() methods.<p>If the PipelineResult represents a non-document result, <code>ref</code> will return a undefined value. |
| PipelineSnapshot | Represents the results of a Firestore pipeline execution.<!-- -->A <code>PipelineSnapshot</code> contains zero or more PipelineResult objects representing the documents returned by a pipeline query. It provides methods to iterate over the documents and access metadata about the query results. |
| PipelineSource | Provides the entry point for defining the data source of a Firestore Pipeline<!-- -->.<!-- -->Use the methods of this class (e.g., PipelineSource.collection()<!-- -->, PipelineSource.collectionGroup()<!-- -->, PipelineSource.database()<!-- -->, or PipelineSource.documents()<!-- -->) to specify the initial data for your pipeline, such as a collection, a collection group, the entire database, or a set of specific documents. |
| Query | A <code>Query</code> refers to a query which you can read or listen to. You can also construct refined <code>Query</code> objects by adding filters and ordering. |
| QueryDocumentSnapshot | A <code>QueryDocumentSnapshot</code> contains data read from a document in your Firestore database as part of a query. The document is guaranteed to exist and its data can be extracted with <code>.data()</code> or <code>.get(<field>)</code> to get a specific field.<!-- -->A <code>QueryDocumentSnapshot</code> offers the same API surface as a <code>DocumentSnapshot</code>. Since query results contain only existing documents, the <code>exists</code> property will always be true and <code>data()</code> will never return 'undefined'. |
| Timestamp | A <code>Timestamp</code> represents a point in time independent of any time zone or calendar, represented as seconds and fractions of seconds at nanosecond resolution in UTC Epoch time.<!-- -->It is encoded using the Proleptic Gregorian Calendar which extends the Gregorian calendar backwards to year one. It is encoded assuming all minutes are 60 seconds long, i.e. leap seconds are "smeared" so that no leap second table is needed for interpretation. Range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.<!-- -->For examples and further specifications, refer to the Timestamp definition<!-- -->. |
| VectorValue | Represents a vector type in Firestore documents. Create an instance with <code>vector()</code>. |
| Interface | Description |
|---|---|
| DocumentData | Document data (for use with setDoc()<!-- -->) consists of fields mapped to values. |
| FirestoreDataConverter | Converter used by <code>withConverter()</code> to transform user objects of type <code>AppModelType</code> into Firestore data of type <code>DbModelType</code>.<!-- -->Using the converter allows you to specify generic type arguments when storing and retrieving objects from Firestore.<!-- -->In this context, an "AppModel" is a class that is used in an application to package together related information and functionality. Such a class could, for example, have properties with complex, nested data types, properties used for memoization, properties of types not supported by Firestore (such as <code>symbol</code> and <code>bigint</code>), and helper functions that perform compound operations. Such classes are not suitable and/or possible to store into a Firestore database. Instead, instances of such classes need to be converted to "plain old JavaScript objects" (POJOs) with exclusively primitive properties, potentially nested inside other POJOs or arrays of POJOs. In this context, this type is referred to as the "DbModel" and would be an object suitable for persisting into Firestore. For convenience, applications can implement <code>FirestoreDataConverter</code> and register the converter with Firestore objects, such as <code>DocumentReference</code> or <code>Query</code>, to automatically convert <code>AppModel</code> to <code>DbModel</code> when storing into Firestore, and convert <code>DbModel</code> to <code>AppModel</code> when retrieving from Firestore. |
| Selectable | An interface that represents a selectable expression. |
| Type Alias | Description |
|---|---|
| AddFieldsStageOptions | Options defining how an AddFieldsStage is evaluated. See Pipeline.addFields()<!-- -->. |
| AggregateStageOptions | Options defining how an AggregateStage is evaluated. See Pipeline.aggregate()<!-- -->. |
| CollectionGroupStageOptions | Defines the configuration options for a CollectionGroupStage within a pipeline. This type extends StageOptions and provides specific settings for how a collection group is identified and processed during pipeline execution.<!-- -->See PipelineSource.collectionGroup() to create a collection group stage. |
| CollectionStageOptions | Options defining how a CollectionStage is evaluated. See PipelineSource.collection()<!-- -->. |
| DatabaseStageOptions | Options defining how a DatabaseStage is evaluated. See PipelineSource.database()<!-- -->. |
| DefineStageOptions | Options defining how a DefineStage is evaluated. See Pipeline.define()<!-- -->. |
| DistinctStageOptions | Options defining how a DistinctStage is evaluated. See Pipeline.distinct()<!-- -->. |
| DocumentsStageOptions | Options defining how a DocumentsStage is evaluated. See PipelineSource.documents()<!-- -->. |
| ExpressionType | An enumeration of the different types of expressions. |
| FindNearestStageOptions | Options defining how a FindNearestStage is evaluated. See Pipeline.findNearest()<!-- -->. |
| LimitStageOptions | Options defining how a LimitStage is evaluated. See Pipeline.limit()<!-- -->. |
| OffsetStageOptions | Options defining how an OffsetStage is evaluated. See Pipeline.offset()<!-- -->. |
| OneOf | Utility type to create an type that only allows one property of the Type param T to be set. |
| PartialWithFieldValue | Similar to TypeScript's <code>Partial<T></code>, but allows nested fields to be omitted and FieldValues to be passed in as property values. |
| Primitive | Primitive types. |
| RemoveFieldsStageOptions | Options defining how a RemoveFieldsStage is evaluated. See Pipeline.removeFields()<!-- -->. |
| ReplaceWithStageOptions | Options defining how a ReplaceWithStage is evaluated. See Pipeline.replaceWith()<!-- -->. |
| SampleStageOptions | Defines the options for evaluating a sample stage within a pipeline. This type combines common StageOptions with a specific configuration where only one of the defined sampling methods can be applied.<!-- -->See Pipeline.sample() to create a sample stage.. |
| SearchStageOptions | <b><i>(Public Preview)</i></b> Options defining how a SearchStage is evaluated. See . |
| SelectStageOptions | Options defining how a SelectStage is evaluated. See Pipeline.select()<!-- -->. |
| SetOptions | An options object that configures the behavior of setDoc()<!-- -->, and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a <code>SetOptions</code> with <code>merge: true</code>. |
| SortStageOptions | Options defining how a SortStage is evaluated. See Pipeline.sort()<!-- -->. |
| StageOptions | Options defining how a Stage is evaluated. |
| SubcollectionStageOptions | Options defining how a <code>SubcollectionStage</code> is evaluated. |
| TimeGranularity | Specify time granularity for expressions. |
| TimePart | Specify time parts for <code>timestampExtract</code> expressions. |
| TimeUnit | Specify time units for expressions. |
| UnionStageOptions | Options defining how a UnionStage is evaluated. See Pipeline.union()<!-- -->. |
| UnnestStageOptions | Represents the specific options available for configuring an <code>UnnestStage</code> within a pipeline. |
| WhereStageOptions | Options defining how a WhereStage is evaluated. See Pipeline.where()<!-- -->. |
| WithFieldValue | Allows FieldValues to be passed in as a property value while maintaining type safety. |
Creates an aggregation that counts the total number of stage inputs.
<b>Signature:</b>
export declare function countAll(): AggregateFunction;
<b>Returns:</b>
A new AggregateFunction representing the 'countAll' aggregation.
// Count the total number of input documents
countAll().as("totalDocument");
Creates an expression that represents the current document being processed.
<b>Signature:</b>
export declare function currentDocument(): Expression;
<b>Returns:</b>
An Expression representing the current document.
// Define the current document as a variable "doc"
firestore.pipeline().collection("books")
.define(currentDocument().as("doc"))
// Access a field from the defined document variable
.select(variable("doc").mapGet("title"));
Creates an expression that evaluates to the current server timestamp.
<b>Signature:</b>
export declare function currentTimestamp(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the current server timestamp.
// Get the current server timestamp
currentTimestamp()
Creates an expression that generates a random number between 0.0 and 1.0 but not including 1.0.
<b>Signature:</b>
export declare function rand(): FunctionExpression;
<b>Returns:</b>
A new Expression representing the rand operation.
// Generate a random number between 0.0 and 1.0.
rand();
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Evaluates to the search score that reflects the topicality of the document to all of the text predicates (for example: documentMatches<!-- -->) in the search query. If SearchOptions.query is not set or does not contain any text predicates, then this topicality score will always be 0<!-- -->.
This Expression can only be used within a Search stage.
<b>Signature:</b>
export declare function score(): Expression;
<b>Returns:</b>
db.pipeline().collection('restaurants').search({
query: 'waffles',
sort: score().descending()
})
Creates an expression that checks if an array expression contains a specific element.
<b>Signature:</b>
export declare function arrayContains(array: Expression, element: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| element | Expression | 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 the value of field 'selectedColor'
arrayContains(field("colors"), field("selectedColor"));
Creates an expression that checks if an array expression contains a specific element.
<b>Signature:</b>
export declare function arrayContains(array: Expression, element: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| element | 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"
arrayContains(field("colors"), "red");
Creates an expression that checks if an array expression contains all the specified elements.
<b>Signature:</b>
export declare function arrayContainsAll(array: Expression, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| 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 all of the values: "SciFi", "Adventure", and the value from field "tag1"
arrayContainsAll(field("tags"), [field("tag1"), constant("SciFi"), "Adventure"]);
Creates an expression that checks if an array expression contains all the specified elements.
<b>Signature:</b>
export declare function arrayContainsAll(array: Expression, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| 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 all of the values: "SciFi", "Adventure", and the value from field "tag1"
arrayContainsAll(field("tags"), [field("tag1"), constant("SciFi"), "Adventure"]);
Creates an expression that checks if an array expression contains any of the specified elements.
<b>Signature:</b>
export declare function arrayContainsAny(array: Expression, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| 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 "Science"
arrayContainsAny(field("categories"), [field("cate1"), "Science"]);
Creates an expression that checks if an array expression contains any of the specified elements.
<b>Signature:</b>
export declare function arrayContainsAny(array: Expression, values: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to check. |
| values | Expression | An expression that evaluates to an array, whose 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 "Science"
arrayContainsAny(field("categories"), array([field("cate1"), "Science"]));
Creates an expression that calculates the length of an array expression.
<b>Signature:</b>
export declare function arrayLength(array: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| array | Expression | The array expression to calculate the length of. |
<b>Returns:</b>
A new Expression representing the length of the array.
// Get the number of items in the 'cart' array
arrayLength(field("cart"));
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
export declare function arrayFilter(arrayExpression: Expression, alias: string, filter: BooleanExpression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 "scores" to include only values greater than 50
arrayFilter(field("scores"), "score", greaterThan(variable("score"), 50));
Creates an expression that returns the first element of an array.
<b>Signature:</b>
export declare function arrayFirst(arrayExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
<b>Returns:</b>
A new Expression representing the first element.
// Get the first tag from the 'tags' array field
arrayFirst(field("tags"));
Creates an expression that returns the first n elements of an array.
<b>Signature:</b>
export declare function arrayFirstN(arrayExpression: Expression, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the first n elements.
// Get the first 3 elements from an array expression
arrayFirstN(field("tags"), 3);
Creates an expression that returns the first n elements of an array.
<b>Signature:</b>
export declare function arrayFirstN(arrayExpression: Expression, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 from an array expression
arrayFirstN(field("tags"), field("count"));
Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end.
<b>Signature:</b>
export declare function arrayGet(arrayExpression: Expression, offset: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | An <code>Expression</code> evaluating to an array. |
| 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.
arrayGet(field('tags'), 1);
Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end.
<b>Signature:</b>
export declare function arrayGet(arrayExpression: Expression, offsetExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | An <code>Expression</code> evaluating to an array. |
| 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'.
arrayGet(field('tags'), field('favoriteTag'));
Creates an expression that returns the first index of the search value in an array. Returns -1 if the value is not found.
<b>Signature:</b>
export declare function arrayIndexOf(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the index of "politics" in the 'tags' array field
arrayIndexOf(field("tags"), "politics");
Creates an expression that returns all indices of the search value in an array.
<b>Signature:</b>
export declare function arrayIndexOfAll(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the indices.
// Get all indices of 5 in the 'scores' array field
arrayIndexOfAll(field("scores"), 5);
Creates an expression that returns the last element of an array.
<b>Signature:</b>
export declare function arrayLast(arrayExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
<b>Returns:</b>
A new Expression representing the last element.
// Get the last tag from the 'tags' array field
arrayLast(field("tags"));
Creates an expression that returns the last index of the search value in an array. Returns -1 if the value is not found.
<b>Signature:</b>
export declare function arrayLastIndexOf(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the last index of "politics" in the 'tags' array field
arrayLastIndexOf(field("tags"), "politics");
Creates an expression that returns the last n elements of an array.
<b>Signature:</b>
export declare function arrayLastN(arrayExpression: Expression, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the last n elements.
// Get the last 3 elements from an array expression
arrayLastN(field("tags"), 3);
Creates an expression that returns the last n elements of an array.
<b>Signature:</b>
export declare function arrayLastN(arrayExpression: Expression, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 from an array expression
arrayLastN(field("tags"), field("count"));
Creates an expression that returns the maximum value in an array.
<b>Signature:</b>
export declare function arrayMaximum(arrayExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
<b>Returns:</b>
A new Expression representing the maximum value.
// Get the maximum value from the 'scores' array field
arrayMaximum(field("scores"));
Creates an expression that returns the largest n elements of an 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>
export declare function arrayMaximumN(arrayExpression: Expression, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the largest n elements.
// Get the top 3 elements from an array expression
arrayMaximumN(field("scores"), 3);
Creates an expression that returns the largest n elements of an 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>
export declare function arrayMaximumN(arrayExpression: Expression, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 top n elements from an array expression
arrayMaximumN(field("scores"), field("count"));
Creates an expression that returns the minimum value in an array.
<b>Signature:</b>
export declare function arrayMinimum(arrayExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
<b>Returns:</b>
A new Expression representing the minimum value.
// Get the minimum value from the 'scores' array field
arrayMinimum(field("scores"));
Creates an expression that returns the smallest n elements of an 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>
export declare function arrayMinimumN(arrayExpression: Expression, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the smallest n elements.
// Get the bottom 3 scores from the 'scores' array field
arrayMinimumN(field("scores"), 3);
Creates an expression that returns the smallest n elements of an 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>
export declare function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 bottom n scores from the 'scores' array field
arrayMinimumN(field("scores"), field("count"));
Creates an expression that returns a slice of an array from offset with length elements.
<b>Signature:</b>
export declare function arraySlice(arrayExpression: Expression, offset: number | Expression, length?: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 an array expression starting from index 2
arraySlice(field("items"), 2, 5);
// Get n elements from an array expression starting from index 2
arraySlice(field("items"), 2, field("length"));
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
export declare function arrayTransform(arrayExpression: Expression, elementAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| 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 transformed array.
// Transform "scores" array by multiplying each score by 10
arrayTransform(field("scores"), "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>
export declare function arrayTransformWithIndex(arrayExpression: Expression, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | The expression representing the array. |
| elementAlias | string | The variable name to use for each element. |
| indexAlias | string | The variable name to use for the current index. |
| transform | Expression | The expression used to transform the elements. |
<b>Returns:</b>
A new Expression representing the transformed array.
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex(field("scores"), "score", "i", add(variable("score"), variable("i")));
Creates an expression that joins the elements of an array into a string.
<b>Signature:</b>
export declare function join(arrayExpression: Expression, delimiterExpression: Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | An expression that evaluates to an array. |
| delimiterExpression | Expression | The expression that evaluates to the delimiter string. |
<b>Returns:</b>
A new Expression representing the join operation.
// Join an array of string using the delimiter from the 'separator' field.
join(array(['foo', 'bar']), field("separator"))
Creates an expression that joins the elements of an array into a string.
<b>Signature:</b>
export declare function join(arrayExpression: Expression, delimiter: string): Expression;
| Parameter | Type | Description |
|---|---|---|
| arrayExpression | Expression | An expression that evaluates to an array. |
| 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.
join(field("tags"), ", ")
Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end.
<b>Signature:</b>
export declare function arrayGet(arrayField: string, offset: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayField | string | The name of the array field. |
| 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.
arrayGet('tags', 1);
Creates an expression that indexes into an array from the beginning or end and return the element. If the offset exceeds the array length, an error is returned. A negative offset, starts from the end.
<b>Signature:</b>
export declare function arrayGet(arrayField: string, offsetExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| arrayField | string | The name of the array field. |
| 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'.
arrayGet('tags', field('favoriteTag'));
Creates an expression that joins the elements of an array into a string.
<b>Signature:</b>
export declare function join(arrayFieldName: string, delimiter: string): Expression;
| Parameter | Type | Description |
|---|---|---|
| arrayFieldName | string | The name of the field containing the array. |
| 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.
join("tags", ", ")
Creates an expression that joins the elements of an array into a string.
<b>Signature:</b>
export declare function join(arrayFieldName: string, delimiterExpression: Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| arrayFieldName | string | The name of the field containing the array. |
| 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.
join('tags', field("separator"))
Creates an expression that returns the value of the base expression raised to the power of the exponent expression.
<b>Signature:</b>
export declare function pow(base: Expression, exponent: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| base | Expression | The expression to raise to the power of the exponent. |
| exponent | Expression | The expression to raise the base 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.
pow(field("base"), field("exponent"));
Creates an expression that returns the value of the base expression raised to the power of the exponent.
<b>Signature:</b>
export declare function pow(base: Expression, exponent: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| base | Expression | The expression to raise to the power of the exponent. |
| exponent | number | The constant value to raise the base 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.
pow(field("base"), 2);
Creates an expression that returns the value of the base field raised to the power of the exponent expression.
<b>Signature:</b>
export declare function pow(base: string, exponent: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| base | string | The name of the field to raise to the power of the exponent. |
| exponent | Expression | The expression to raise the base 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.
pow("base", field("exponent"));
Creates an expression that returns the value of the base field raised to the power of the exponent.
<b>Signature:</b>
export declare function pow(base: string, exponent: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| base | string | The name of the field to raise to the power of the exponent. |
| exponent | number | The constant value to raise the base 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.
pow("base", 2);
Creates an aggregation that counts the number of stage inputs where the provided boolean expression evaluates to true.
<b>Signature:</b>
export declare function countIf(booleanExpr: BooleanExpression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| booleanExpr | BooleanExpression | The boolean expression to evaluate on each input. |
<b>Returns:</b>
A new AggregateFunction representing the 'countIf' aggregation.
// Count the number of documents where 'is_active' field equals true
countIf(field("is_active").equal(true)).as("numActiveDocuments");
Creates an expression that negates a filter condition.
<b>Signature:</b>
export declare function not(booleanExpr: BooleanExpression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| booleanExpr | BooleanExpression | The filter condition to negate. |
<b>Returns:</b>
A new Expression representing the negated filter condition.
// Find documents where the 'completed' field is NOT true
not(equal("completed", true));
Creates a conditional expression that evaluates to a 'then' expression if a condition is true and an 'else' expression if the condition is false.
<b>Signature:</b>
export declare function conditional(condition: BooleanExpression, thenExpr: Expression, elseExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| condition | BooleanExpression | The condition to evaluate. |
| thenExpr | Expression | The expression to evaluate if the condition is true. |
| elseExpr | Expression | The expression to evaluate if the condition is false. |
<b>Returns:</b>
A new Expression representing the conditional expression.
// If 'age' is greater than 18, return "Adult"; otherwise, return "Minor".
conditional(
greaterThan("age", 18), constant("Adult"), constant("Minor"));
Creates an expression that evaluates to the result corresponding to the first true condition.
This function behaves like a switch statement. It accepts an alternating sequence of conditions and their corresponding results. If an odd number of arguments is provided, the final argument serves as a default fallback result. If no default is provided and no condition evaluates to true, it throws an error.
<b>Signature:</b>
export declare function switchOn(condition: BooleanExpression, result: Expression, ...others: Array<BooleanExpression | Expression>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| condition | BooleanExpression | The first condition to check. |
| result | Expression | The result if the first condition is true. |
| others | Array<BooleanExpression | Expression<!-- -->> | Additional conditions and results, and optionally a default value. |
<b>Returns:</b>
A new Expression representing the switch operation.
// Return "Active" if field "status" is 1, "Pending" if field "status" is 2,
// and default to "Unknown" if none of the conditions are true.
switchOn(
equal(field("status"), 1), constant("Active"),
equal(field("status"), 2), constant("Pending"),
constant("Unknown")
)
Creates an expression that returns the document ID from a path.
<b>Signature:</b>
export declare function documentId(documentPath: string | DocumentReference): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| documentPath | string | DocumentReference |
<b>Returns:</b>
A new Expression representing the documentId operation.
// Get the document ID from a path.
documentId(myDocumentReference);
Creates an expression that returns the parent document reference of a document reference.
<b>Signature:</b>
declare function parent_2(documentPath: string | DocumentReference): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| documentPath | string | DocumentReference | A string path or DocumentReference to get the parent from. |
<b>Returns:</b>
A new Expression representing the parent operation.
// Get the parent document reference of a document reference.
parent(myDocumentReference);
Creates an expression that returns the document ID from a path.
<b>Signature:</b>
export declare function documentId(documentPathExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| documentPathExpr | Expression |
<b>Returns:</b>
A new Expression representing the documentId operation.
// Get the document ID from a path.
documentId(field("__path__"));
Creates an expression that returns the parent document reference of a document reference.
<b>Signature:</b>
declare function parent_2(documentPathExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| documentPathExpr | Expression | An Expression evaluating to a document reference. |
<b>Returns:</b>
A new Expression representing the parent operation.
// Get the parent document reference of a document reference.
parent(field("__path__"));
Creates an expression that checks if an expression is not equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function notEqualAny(element: Expression, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| element | Expression | The expression to compare. |
| values | Array<Expression | unknown> | The values to check against. |
<b>Returns:</b>
A new Expression representing the 'NOT IN' comparison.
// Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
notEqualAny(field("status"), ["pending", field("rejectedStatus")]);
Creates an expression that checks if an expression is not equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function notEqualAny(element: Expression, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| element | Expression | The expression to compare. |
| arrayExpression | Expression | The values to check against. |
<b>Returns:</b>
A new Expression representing the 'NOT IN' comparison.
// Check if the 'status' field is neither "pending" nor the value of the field 'rejectedStatus'
notEqualAny(field("status"), ["pending", field("rejectedStatus")]);
Creates an expression that creates a Firestore array value from an input array.
<b>Signature:</b>
export declare function array(elements: unknown[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elements | unknown[] | The input array to evaluate in the expression. |
<b>Returns:</b>
A new Expression representing the array function.
// Create an array value from the input array and reference the 'baz' field value from the input document.
array(['bar', field('baz')]).as('foo');
Creates an expression that creates a Firestore map value from an input object.
<b>Signature:</b>
export declare function map(elements: Record<string, unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| elements | Record<string, unknown> | The input map to evaluate in the expression. |
<b>Returns:</b>
A new Expression representing the map function.
// Create a map from the input object and reference the 'baz' field value from the input document.
map({foo: 'bar', baz: field('baz')}).as('data');
Creates an expression that calculates the difference between two timestamps.
<b>Signature:</b>
export declare function timestampDiff(endExpression: Expression, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| endExpression | Expression | The ending timestamp for the difference calculation. |
| startFieldName | string | The name of the field representing the starting timestamp. |
| unit | TimeUnit | Expression | 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 an ending timestamp expression and 'startTime' field.
timestampDiff(field('endTime'), 'startTime', 'day')
Creates an expression that calculates the difference between two timestamps.
<b>Signature:</b>
export declare function timestampDiff(endExpression: Expression, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| endExpression | Expression | The ending timestamp for the difference calculation. |
| startExpression | Expression | The starting timestamp for the difference calculation. |
| unit | TimeUnit | Expression | 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 two timestamp expressions.
timestampDiff(field('endTime'), field('startTime'), 'day')
<b>Signature:</b>
export declare function timestampDiff(endFieldName: string, startFieldName: string, unit: TimeUnit | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| endFieldName | string | |
| startFieldName | string | |
| unit | TimeUnit | Expression |
<b>Returns:</b>
Creates an expression that calculates the difference between two timestamps.
<b>Signature:</b>
export declare function timestampDiff(endFieldName: string, startExpression: Expression, unit: TimeUnit | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| endFieldName | string | The name of the field representing the ending timestamp. |
| startExpression | Expression | The starting timestamp for the difference calculation. |
| unit | TimeUnit | Expression | 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' field and a starting timestamp expression.
timestampDiff('endTime', field('startTime'), 'day')
Creates an expression that computes the absolute value of a numeric value.
<b>Signature:</b>
export declare function abs(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression to compute the absolute value of. |
<b>Returns:</b>
A new Expression representing the absolute value of the numeric value.
Creates an Ordering that sorts documents in ascending order based on an expression.
<b>Signature:</b>
export declare function ascending(expr: Expression): Ordering;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression to create an ascending ordering for. |
<b>Returns:</b>
A new Ordering for ascending sorting.
// Sort documents by the 'name' field in lowercase in ascending order
firestore.pipeline().collection("users")
.sort(ascending(field("name").toLower()));
Creates an expression that calculates the byte length of a string in UTF-8, or just the length of a Blob.
<b>Signature:</b>
export declare function byteLength(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the string. |
<b>Returns:</b>
A new Expression representing the length of the string in bytes.
// Calculate the length of the 'myString' field in bytes.
byteLength(field("myString"));
Creates an aggregation that counts the number of distinct values of a field.
<b>Signature:</b>
export declare function countDistinct(expr: Expression | string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | string | The expression or field to count distinct values of. |
<b>Returns:</b>
A new AggregateFunction representing the 'count_distinct' aggregation.
Creates an Ordering that sorts documents in descending order based on an expression.
<b>Signature:</b>
export declare function descending(expr: Expression): Ordering;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression to create a descending ordering for. |
<b>Returns:</b>
A new Ordering for descending sorting.
// Sort documents by the 'name' field in lowercase in descending order
firestore.pipeline().collection("users")
.sort(descending(field("name").toLower()));
Creates an expression that computes the floor of a numeric value.
<b>Signature:</b>
export declare function floor(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression to compute the floor of. |
<b>Returns:</b>
A new Expression representing the floor of the numeric value.
Creates an expression that converts a timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixMicros(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of microseconds since epoch.
// Convert the 'timestamp' field to microseconds since epoch.
timestampToUnixMicros(field("timestamp"));
Creates an expression that converts a timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixMillis(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of milliseconds since epoch.
// Convert the 'timestamp' field to milliseconds since epoch.
timestampToUnixMillis(field("timestamp"));
Creates an expression that converts a timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixSeconds(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of seconds since epoch.
// Convert the 'timestamp' field to seconds since epoch.
timestampToUnixSeconds(field("timestamp"));
Creates an expression that interprets an expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixMicrosToTimestamp(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the number of microseconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'microseconds' field as microseconds since epoch.
unixMicrosToTimestamp(field("microseconds"));
Creates an expression that interprets an expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixMillisToTimestamp(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the number of milliseconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'milliseconds' field as milliseconds since epoch.
unixMillisToTimestamp(field("milliseconds"));
Creates an expression that interprets an expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixSecondsToTimestamp(expr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expr | Expression | The expression representing the number of seconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'seconds' field as seconds since epoch.
unixSecondsToTimestamp(field("seconds"));
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>
export declare function arrayAgg(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to collect values from. |
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg' aggregation.
// Collect all tags from books into an array
arrayAgg(field("tags")).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>
export declare function arrayAggDistinct(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to collect values from. |
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg_distinct' aggregation.
// Collect all distinct tags from books into an array
arrayAggDistinct(field("tags")).as("allDistinctTags");
Creates an expression that computes the sum of the elements in an array.
<b>Signature:</b>
export declare function arraySum(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric array, which the sum will be computed for. |
<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.
arraySum(field("scores"));
Creates an aggregation that calculates the average (mean) of values from an expression across multiple stage inputs.
<b>Signature:</b>
export declare function average(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the values to average. |
<b>Returns:</b>
A new AggregateFunction representing the 'average' aggregation.
// Calculate the average age of users
average(field("age")).as("averageAge");
Creates an expression that computes the ceiling of a numeric value.
<b>Signature:</b>
export declare function ceil(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the ceiling will be computed for. |
<b>Returns:</b>
A new Expression representing the ceiling of the numeric value.
// Compute the ceiling of the 'price' field.
ceil(field("price"));
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>
export declare function coalesce(expression: Expression, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The first expression to check for null. |
| replacement | Expression | unknown | The fallback expression or value if the first one is null. |
| others | Array<Expression | unknown> | Optional additional expressions to check if previous ones 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.
coalesce(field("preferredName"), field("fullName"), constant("Anonymous"))
Creates an expression that returns the collection ID from a path.
<b>Signature:</b>
export declare function collectionId(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a path, which the collection ID will be extracted from. |
<b>Returns:</b>
A new Expression representing the collectionId operation.
// Get the collection ID from a path.
collectionId(field("__name__"));
Creates an aggregation that counts the number of stage inputs with valid evaluations of the provided expression.
<b>Signature:</b>
export declare function count(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to count. |
<b>Returns:</b>
A new AggregateFunction representing the 'count' aggregation.
// Count the number of items where the price is greater than 10
count(field("price").greaterThan(10)).as("expensiveItemCount");
Creates an expression that divides an expression by a constant value.
<b>Signature:</b>
export declare function divide(expression: Expression, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to be divided. |
| value | unknown | The constant value to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'value' field by 10
divide(field("value"), 10);
Creates an expression that checks if an expression is equal to a constant value.
<b>Signature:</b>
export declare function equal(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'age' field is equal to 21
equal(field("age"), 21);
Creates an expression that checks if an expression, when evaluated, is equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function equalAny(expression: Expression, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression whose results to compare. |
| values | Array<Expression | unknown> | The 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'
equalAny(field("category"), [constant("Electronics"), field("primaryType")]);
Creates an expression that checks if an expression is equal to any of the provided values.
<b>Signature:</b>
export declare function equalAny(expression: Expression, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression whose results to compare. |
| arrayExpression | Expression | An expression that evaluates to an array, whose elements to check for equality to the input. |
<b>Returns:</b>
A new Expression representing the 'IN' comparison.
// Check if the 'category' field is set to a value in the disabledCategories field
equalAny(field("category"), field('disabledCategories'));
Creates an expression that computes e to the power of the expression's result.
<b>Signature:</b>
export declare function exp(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression |
<b>Returns:</b>
A new Expression representing the exp of the numeric value.
// Compute e to the power of 2.
exp(constant(2));
Creates an aggregation that finds the first value of an expression across multiple stage inputs.
<b>Signature:</b>
export declare function first(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to find the first value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'first' aggregation.
// Find the first value of the 'rating' field
first(field("rating")).as("firstRating");
Creates an expression that checks if an expression is greater than a constant value.
<b>Signature:</b>
export declare function greaterThan(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the 'age' field is greater than 18
greaterThan(field("age"), 18);
Creates an expression that checks if an expression is greater than or equal to a constant value.
<b>Signature:</b>
export declare function greaterThanOrEqual(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare 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 10
greaterThanOrEqual(field("quantity"), 10);
Creates an expression that checks if the result of an 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>
export declare function isType(expression: Expression, type: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to check. |
| 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 result of a calculation is a number
isType(add('count', 1), 'number')
Creates an aggregation that finds the last value of an expression across multiple stage inputs.
<b>Signature:</b>
export declare function last(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to find the last value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'last' aggregation.
// Find the last value of the 'rating' field
last(field("rating")).as("lastRating");
Creates an expression that calculates the length of a string, array, map, vector, or bytes.
<b>Signature:</b>
declare function length_2(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a string, array, map, vector, or bytes, which the length will be calculated for. |
<b>Returns:</b>
A new Expression representing the length of the string, array, map, vector, or bytes.
// Get the length of the 'name' field.
length(field("name"));
// Get the number of items in the 'cart' array.
length(field("cart"));
Creates an expression that checks if an expression is less than a constant value.
<b>Signature:</b>
export declare function lessThan(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'age' field is less than 30
lessThan(field("age"), 30);
Creates an expression that checks if an expression is less than or equal to a constant value.
<b>Signature:</b>
export declare function lessThanOrEqual(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare 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
lessThan(field("quantity"), 20);
Creates an expression that computes the natural logarithm of a numeric value.
<b>Signature:</b>
export declare function ln(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the natural logarithm will be computed for. |
<b>Returns:</b>
A new Expression representing the natural logarithm of the numeric value.
// Compute the natural logarithm of the 'value' field.
ln(field("value"));
Creates an expression that computes the logarithm of an expression to a given base.
<b>Signature:</b>
export declare function log(expression: Expression, base: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the logarithm will be computed for. |
| base | number | The base of the logarithm. |
<b>Returns:</b>
A new Expression representing the logarithm of the numeric value.
// Compute the logarithm of the 'value' field with base 10.
log(field("value"), 10);
Creates an expression that computes the logarithm of an expression to a given base.
<b>Signature:</b>
export declare function log(expression: Expression, base: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the logarithm will be computed for. |
| base | Expression | The base of the logarithm. |
<b>Returns:</b>
A new Expression representing the logarithm of the numeric value.
// Compute the logarithm of the 'value' field with the base in the 'base' field.
log(field("value"), field("base"));
Creates an expression that computes the base-10 logarithm of a numeric value.
<b>Signature:</b>
export declare function log10(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the base-10 logarithm will be computed for. |
<b>Returns:</b>
A new Expression representing the base-10 logarithm of the numeric value.
// Compute the base-10 logarithm of the 'value' field.
log10(field("value"));
Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array.
<b>Signature:</b>
export declare function ltrim(expression: Expression, valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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 beginning of the 'userInput' field
ltrim(field("userInput"));
// Trim quotes from the beginning of the 'userInput' field
ltrim(field("userInput"), '"');
Creates an aggregation that finds the maximum value of an expression across multiple stage inputs.
<b>Signature:</b>
export declare function maximum(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to find the maximum value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'maximum' aggregation.
// Find the highest score in a leaderboard
maximum(field("score")).as("highestScore");
Creates an aggregation that finds the minimum value of an expression across multiple stage inputs.
<b>Signature:</b>
export declare function minimum(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to find the minimum value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'minimum' aggregation.
// Find the lowest price of all products
minimum(field("price")).as("lowestPrice");
Creates an expression that calculates the modulo (remainder) of dividing an expression by a constant.
<b>Signature:</b>
export declare function mod(expression: Expression, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The dividend expression. |
| value | unknown | The divisor constant. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing 'field1' by 5.
mod(field("field1"), 5);
Creates an expression that checks if an expression is not equal to a constant value.
<b>Signature:</b>
export declare function notEqual(expression: Expression, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'status' field is not equal to "completed"
notEqual(field("status"), "completed");
Creates an expression that rounds a numeric value to the nearest whole number.
<b>Signature:</b>
export declare function round(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which will be rounded. |
<b>Returns:</b>
A new Expression representing the rounded value.
// Round the value of the 'price' field.
round(field("price"));
Creates an expression that rounds a numeric value to the specified number of decimal places.
<b>Signature:</b>
export declare function round(expression: Expression, decimalPlaces: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which will be rounded. |
| decimalPlaces | number | Expression | A constant or 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.
round(field("price"), constant(2));
Trims whitespace or a specified set of characters/bytes from the end of a string or byte array.
<b>Signature:</b>
export declare function rtrim(expression: Expression, valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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
rtrim(field("userInput"));
// Trim quotes from the end of the 'userInput' field
rtrim(field("userInput"), '"');
Creates an expression that splits a string into an array of substrings based on the provided delimiter.
<b>Signature:</b>
export declare function split(expression: Expression, delimiter: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | Split the result of this expression. |
| delimiter | string | Split on this delimiter. |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scoresCsv' field on delimiter ','
split(field('scoresCsv'), ',')
Creates an expression that splits a string into an array of substrings based on the provided delimiter.
<b>Signature:</b>
export declare function split(expression: Expression, delimiter: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | Split the result of this expression. |
| delimiter | Expression | Split on this delimiter returned by evaluating this expression. |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scores' field on delimiter ',' or ':' depending on the stored format
split(field('scores'), conditional(field('format').equal('csv'), constant(','), constant(':')))
Creates an expression that computes the square root of a numeric value.
<b>Signature:</b>
export declare function sqrt(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which the square root will be computed for. |
<b>Returns:</b>
A new Expression representing the square root of the numeric value.
// Compute the square root of the 'value' field.
sqrt(field("value"));
Creates an expression that finds the index of the first occurrence of a substring or byte sequence.
<b>Signature:</b>
export declare function stringIndexOf(expression: Expression, search: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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
stringIndexOf(field("text"), "foo");
Creates an expression that repeats a string or byte array a specified number of times.
<b>Signature:</b>
export declare function stringRepeat(expression: Expression, repetitions: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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
stringRepeat(field("label"), 3);
Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement.
<b>Signature:</b>
export declare function stringReplaceAll(expression: Expression, find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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
stringReplaceAll(field("text"), "foo", "bar");
Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement.
<b>Signature:</b>
export declare function stringReplaceOne(expression: Expression, find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression representing the string or byte array. |
| 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
stringReplaceOne(field("text"), "foo", "bar");
Creates an expression that subtracts a constant value from an expression.
<b>Signature:</b>
export declare function subtract(expression: Expression, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to subtract from. |
| value | unknown | The constant value to subtract. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract the constant value 2 from the 'value' field
subtract(field("value"), 2);
Creates an aggregation that calculates the sum of values from an expression across multiple stage inputs.
<b>Signature:</b>
export declare function sum(expression: Expression): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | The expression to sum up. |
<b>Returns:</b>
A new AggregateFunction representing the 'sum' aggregation.
// Calculate the total revenue from a set of orders
sum(field("orderAmount")).as("totalRevenue");
Creates an expression that truncates the numeric value of an expression to an integer.
<b>Signature:</b>
export declare function trunc(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which will be truncated. |
<b>Returns:</b>
A new Expression representing the truncated value.
// Truncate the value of the 'rating' field.
trunc(field("rating"));
Creates an expression that truncates a numeric value to the specified number of decimal places.
<b>Signature:</b>
export declare function trunc(expression: Expression, decimalPlaces: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression | An expression evaluating to a numeric value, which will be truncated. |
| decimalPlaces | number | Expression | A constant or 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.
trunc(field("rating"), constant(2));
Creates an expression that returns the data type of an expression's result.
<b>Signature:</b>
export declare function type(expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| expression | Expression |
<b>Returns:</b>
A new Expression representing the data type.
// Get the data type of a conditional expression
type(conditional(exists('foo'), constant(1), constant(true)))
Creates an expression that returns true if a field is absent. Otherwise, returns false even if the field value is null<!-- -->.
<b>Signature:</b>
export declare function isAbsent(field: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| field | string | The field to check. |
<b>Returns:</b>
A new Expression representing the 'isAbsent' check.
// Check if the field `value` is absent.
isAbsent("value");
Creates an expression that reverses a string value in the specified field.
<b>Signature:</b>
export declare function reverse(field: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| field | string | The name of the field representing the string to reverse. |
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
reverse("myString");
Creates an expression that reverses a string value in the specified field.
<b>Signature:</b>
export declare function stringReverse(field: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| field | string | The name of the field representing the string to reverse. |
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
stringReverse("myString");
Creates an expression that returns a substring of a string or byte array.
<b>Signature:</b>
export declare function substring(field: string, position: number, length?: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| field | string | The name of a field containing a string or byte array to compute the substring from. |
| position | number | Index of the first character of the substring. |
| length | number | Length of the substring. |
<b>Returns:</b>
Creates an expression that returns a substring of a string or byte array.
<b>Signature:</b>
export declare function substring(field: string, position: Expression, length?: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| field | string | The name of a field containing a string or byte array to compute the substring from. |
| position | Expression | An expression that returns the index of the first character of the substring. |
| length | Expression | An expression that returns the length of the substring. |
<b>Returns:</b>
Creates an expression that computes the absolute value of a numeric value.
<b>Signature:</b>
export declare function abs(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field to compute the absolute value of. |
<b>Returns:</b>
A new Expression representing the absolute value of the numeric value.
Creates an expression that adds a field's value to an expression.
<b>Signature:</b>
export declare function add(fieldName: string, second: Expression | unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the value to add. |
| second | Expression | unknown | The second expression or literal to add. |
<b>Returns:</b>
A new Expression representing the addition operation.
// Add the value of the 'quantity' field and the 'reserve' field.
add("quantity", field("reserve"));
Creates an aggregation that collects all values of a field 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>
export declare function arrayAgg(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to collect values from. |
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg' aggregation.
// Collect all tags from books into an array
arrayAgg("tags").as("allTags");
Creates an aggregation that collects all distinct values of a field 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>
export declare function arrayAggDistinct(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to collect values from. |
<b>Returns:</b>
A new AggregateFunction representing the 'array_agg_distinct' aggregation.
// Collect all distinct tags from books into an array
arrayAggDistinct("tags").as("allDistinctTags");
Creates an expression that checks if a field's array value contains a specific element.
<b>Signature:</b>
export declare function arrayContains(fieldName: string, element: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| element | Expression | 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 the value of field 'selectedColor'
arrayContains("colors", field("selectedColor"));
Creates an expression that checks if a field's array value contains a specific value.
<b>Signature:</b>
export declare function arrayContains(fieldName: string, element: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| element | 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"
arrayContains("colors", "red");
Creates an expression that checks if a field's array value contains all the specified values or expressions.
<b>Signature:</b>
export declare function arrayContainsAll(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| 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 of the values from field 'tag1', the value "SciFi", and "Adventure"
arrayContainsAll("tags", [field("tag1"), "SciFi", "Adventure"]);
Creates an expression that checks if a field's array value contains all the specified values or expressions.
<b>Signature:</b>
export declare function arrayContainsAll(fieldName: string, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| 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', the value "SciFi", and "Adventure"
arrayContainsAll("tags", [field("tag1"), "SciFi", "Adventure"]);
Creates an expression that checks if a field's array value contains any of the specified elements.
<b>Signature:</b>
export declare function arrayContainsAny(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| 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 'groups' array contains either the value from the 'userGroup' field
// or the value "guest"
arrayContainsAny("categories", [field("cate1"), "Science"]);
Creates an expression that checks if a field's array value contains any of the specified elements.
<b>Signature:</b>
export declare function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| values | Expression | An expression that evaluates to an array, whose elements to check for in the array field. |
<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"
arrayContainsAny("categories", array([field("cate1"), "Science"]));
Creates an expression that filters an array using a provided alias and predicate expression.
<b>Signature:</b>
export declare function arrayFilter(fieldName: string, alias: string, filter: BooleanExpression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| alias | string | The variable name to use for each element. |
| filter | BooleanExpression | The predicate boolean expression to evaluate for each element. |
<b>Returns:</b>
A new Expression representing the filtered array.
// Get a filtered array of the 'scores' field containing only elements greater than 50.
arrayFilter("scores", "score", greaterThan(variable("score"), 50));
Creates an expression that returns the first element of an array.
<b>Signature:</b>
export declare function arrayFirst(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
<b>Returns:</b>
A new Expression representing the first element.
// Get the first tag from the 'tags' array field
arrayFirst("tags");
Creates an expression that returns the first n elements of an array.
<b>Signature:</b>
export declare function arrayFirstN(fieldName: string, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the first n elements.
// Get the first 3 tags from the 'tags' array field
arrayFirstN("tags", 3);
Creates an expression that returns the first n elements of an array.
<b>Signature:</b>
export declare function arrayFirstN(fieldName: string, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 tags from the 'tags' array field
arrayFirstN("tags", field("count"));
Creates an expression that returns the first index of the search value in an array. Returns -1 if the value is not found.
<b>Signature:</b>
export declare function arrayIndexOf(fieldName: string, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the index of "politics" in the 'tags' array field
arrayIndexOf("tags", "politics");
Creates an expression that returns all indices of the search value in an array.
<b>Signature:</b>
export declare function arrayIndexOfAll(fieldName: string, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the indices.
// Get all indices of 5 in the 'scores' array field
arrayIndexOfAll("scores", 5);
Creates an expression that returns the last element of an array.
<b>Signature:</b>
export declare function arrayLast(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
<b>Returns:</b>
A new Expression representing the last element.
// Get the last tag from the 'tags' array field
arrayLast("tags");
Creates an expression that returns the last index of the search value in an array. Returns -1 if the value is not found.
<b>Signature:</b>
export declare function arrayLastIndexOf(fieldName: string, search: unknown | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array to search. |
| search | unknown | Expression | The value to search for. |
<b>Returns:</b>
A new Expression representing the index.
// Get the last index of "politics" in the 'tags' array field
arrayLastIndexOf("tags", "politics");
Creates an expression that returns the last n elements of an array.
<b>Signature:</b>
export declare function arrayLastN(fieldName: string, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the last n elements.
// Get the last 3 tags from the 'tags' array field
arrayLastN("tags", 3);
Creates an expression that returns the last n elements of an array.
<b>Signature:</b>
export declare function arrayLastN(fieldName: string, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 tags from the 'tags' array field
arrayLastN("tags", field("count"));
Creates an expression that calculates the length of an array in a specified field.
<b>Signature:</b>
export declare function arrayLength(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing an array to calculate the length of. |
<b>Returns:</b>
A new Expression representing the length of the array.
// Get the number of items in field 'cart'
arrayLength('cart');
Creates an expression that returns the maximum value in an array.
<b>Signature:</b>
export declare function arrayMaximum(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
<b>Returns:</b>
A new Expression representing the maximum value.
// Get the maximum value from the 'scores' array field
arrayMaximum("scores");
Creates an expression that returns the largest n elements of an 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>
export declare function arrayMaximumN(fieldName: string, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the largest n elements.
// Get the top 3 scores from the 'scores' array field
arrayMaximumN("scores", 3);
Creates an expression that returns the largest n elements of an 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>
export declare function arrayMaximumN(fieldName: string, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 top n scores from the 'scores' array field
arrayMaximumN("scores", field("count"));
Creates an expression that returns the minimum value in an array.
<b>Signature:</b>
export declare function arrayMinimum(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
<b>Returns:</b>
A new Expression representing the minimum value.
// Get the minimum value from the 'scores' array field
arrayMinimum("scores");
Creates an expression that returns the smallest n elements of an 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>
export declare function arrayMinimumN(fieldName: string, n: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| n | number | The number of elements to return. |
<b>Returns:</b>
A new Expression representing the smallest n elements.
// Get the bottom 3 scores from the 'scores' array field
arrayMinimumN("scores", 3);
Creates an expression that returns the smallest n elements of an 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>
export declare function arrayMinimumN(fieldName: string, n: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 bottom n scores from the 'scores' array field
arrayMinimumN(field("scores"), field("count"));
Creates an expression that returns a slice of an array from offset with length elements.
<b>Signature:</b>
export declare function arraySlice(fieldName: string, offset: number | Expression, length?: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 field starting from index 2
arraySlice("items", 2, 5);
// Get n elements from the 'items' array field starting from index 2
arraySlice("items", 2, field("length"));
Creates an expression that computes the sum of the elements in an array.
<b>Signature:</b>
export declare function arraySum(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the sum of. |
<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.
arraySum("scores");
Creates an expression that applies a provided transformation to each element in an array.
<b>Signature:</b>
export declare function arrayTransform(fieldName: string, elementAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| elementAlias | string | The variable name to use for each element. |
| transform | Expression | The expression used to transform the elements. |
<b>Returns:</b>
A new Expression representing the transformed array.
// Transform "scores" array by multiplying each score by 10
arrayTransform("scores", "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>
export declare function arrayTransformWithIndex(fieldName: string, elementAlias: string, indexAlias: string, transform: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the array. |
| 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 transformed array.
// Transform "scores" array by adding the index to each score
arrayTransformWithIndex("scores", "score", "i", add(variable("score"), variable("i")));
Creates an Ordering that sorts documents in ascending order based on a field.
<b>Signature:</b>
export declare function ascending(fieldName: string): Ordering;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field to create an ascending ordering for. |
<b>Returns:</b>
A new Ordering for ascending sorting.
// Sort documents by the 'name' field in ascending order
firestore.pipeline().collection("users")
.sort(ascending("name"));
Creates an aggregation that calculates the average (mean) of a field's values across multiple stage inputs.
<b>Signature:</b>
export declare function average(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing numeric values to average. |
<b>Returns:</b>
A new AggregateFunction representing the 'average' aggregation.
// Calculate the average age of users
average("age").as("averageAge");
Creates an expression that calculates the length of a string represented by a field in UTF-8 bytes, or just the length of a Blob.
<b>Signature:</b>
export declare function byteLength(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
<b>Returns:</b>
A new Expression representing the length of the string in bytes.
// Calculate the length of the 'myString' field in bytes.
byteLength("myString");
Creates an expression that computes the ceiling of a numeric value.
<b>Signature:</b>
export declare function ceil(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the ceiling of. |
<b>Returns:</b>
A new Expression representing the ceiling of the numeric value.
// Compute the ceiling of the 'price' field.
ceil("price");
Creates an expression that calculates the character length of a string field in UTF8.
<b>Signature:</b>
export declare function charLength(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
<b>Returns:</b>
A new Expression representing the length of the string.
// Get the character length of the 'name' field in UTF-8.
charLength("name");
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>
export declare function coalesce(fieldName: string, replacement: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the first field to check for null. |
| replacement | Expression | unknown | The fallback expression or value if the first one is null. |
| others | Array<Expression | unknown> | Optional additional expressions to check if previous ones 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.
coalesce("preferredName", field("fullName"), constant("Anonymous"))
Creates an expression that returns the collection ID from a path.
<b>Signature:</b>
export declare function collectionId(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to get the collection ID from. |
<b>Returns:</b>
A new Expression representing the collectionId operation.
// Get the collection ID from a path.
collectionId("__name__");
Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
<b>Signature:</b>
export declare function concat(fieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of a field to concatenate. |
| second | Expression | unknown | The second literal or expression to concatenate. |
| others | Array<Expression | unknown> | Additional literal or expressions to concatenate. |
<b>Returns:</b>
A new Expression representing the concatenation.
// Concatenate a field with a literal string.
concat(field("firstName"), "Doe")
Calculates the Cosine distance between a field's vector value and a literal vector value.
<b>Signature:</b>
export declare function cosineDistance(fieldName: string, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vector | number[] | VectorValue | The other vector (as an array of doubles) or 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
cosineDistance("location", [37.7749, -122.4194]);
Calculates the Cosine distance between a field's vector value and a vector expression.
<b>Signature:</b>
export declare function cosineDistance(fieldName: string, vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vectorExpression | Expression | The other vector (represented as an <code>Expression</code>) 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
cosineDistance("userVector", field("itemVector"));
Creates an aggregation that counts the number of stage inputs where the input field exists.
<b>Signature:</b>
export declare function count(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to count. |
<b>Returns:</b>
A new AggregateFunction representing the 'count' aggregation.
// Count the total number of products
count("productId").as("totalProducts");
Creates an Ordering that sorts documents in descending order based on a field.
<b>Signature:</b>
export declare function descending(fieldName: string): Ordering;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field to create a descending ordering for. |
<b>Returns:</b>
A new Ordering for descending sorting.
// Sort documents by the 'name' field in descending order
firestore.pipeline().collection("users")
.sort(descending("name"));
Creates an expression that divides a field's value by an expression.
<b>Signature:</b>
export declare function divide(fieldName: string, expressions: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to be divided. |
| expressions | Expression | The expression to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'total' field by the 'count' field
divide("total", field("count"));
Creates an expression that divides a field's value by a constant value.
<b>Signature:</b>
export declare function divide(fieldName: string, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to be divided. |
| value | unknown | The constant value to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'value' field by 10
divide("value", 10);
Calculates the dot product between a field's vector value and a double array.
<b>Signature:</b>
export declare function dotProduct(fieldName: string, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vector | number[] | VectorValue | The other vector (as an array of doubles or VectorValue) to calculate with. |
<b>Returns:</b>
A new Expression representing the dot product between the two vectors.
// Calculate the dot product distance between a feature vector and a target vector
dotProduct("features", [0.5, 0.8, 0.2]);
Calculates the dot product between a field's vector value and a vector expression.
<b>Signature:</b>
export declare function dotProduct(fieldName: string, vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vectorExpression | Expression | The other vector (represented as an <code>Expression</code>) to calculate with. |
<b>Returns:</b>
A new Expression representing the dot product between the two vectors.
// Calculate the dot product distance between two document vectors: 'docVector1' and 'docVector2'
dotProduct("docVector1", field("docVector2"));
Creates an expression that checks if a field's value ends with a given postfix.
<b>Signature:</b>
export declare function endsWith(fieldName: string, suffix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| 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"
endsWith("filename", ".txt");
Creates an expression that checks if a field's value ends with a given postfix.
<b>Signature:</b>
export declare function endsWith(fieldName: string, suffix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| suffix | Expression | The expression representing the postfix. |
<b>Returns:</b>
A new Expression representing the 'ends with' comparison.
// Check if the 'url' field ends with the value of the 'extension' field
endsWith("url", field("extension"));
Creates an expression that checks if a field's value is equal to an expression.
<b>Signature:</b>
export declare function equal(fieldName: string, expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| expression | Expression | The expression to compare to. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'age' field is equal to the 'limit' field
equal("age", field("limit"));
Creates an expression that checks if a field's value is equal to a constant value.
<b>Signature:</b>
export declare function equal(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'city' field is equal to string constant "London"
equal("city", "London");
Creates an expression that checks if a field's value is equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function equalAny(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field to compare. |
| values | Array<Expression | unknown> | The 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'
equalAny("category", [constant("Electronics"), field("primaryType")]);
Creates an expression that checks if a field's value is equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function equalAny(fieldName: string, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field to compare. |
| arrayExpression | Expression | An expression that evaluates to an array, whose elements to check for equality to the input field. |
<b>Returns:</b>
A new Expression representing the 'IN' comparison.
// Check if the 'category' field is either "Electronics" or value of field 'primaryType'
equalAny("category", ["Electronics", field("primaryType")]);
Calculates the Euclidean distance between a field's vector value and a double array.
<b>Signature:</b>
export declare function euclideanDistance(fieldName: string, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vector | number[] | VectorValue | The other vector (as an array of doubles or 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
euclideanDistance("location", [37.7749, -122.4194]);
Calculates the Euclidean distance between a field's vector value and a vector expression.
<b>Signature:</b>
export declare function euclideanDistance(fieldName: string, vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the first vector. |
| vectorExpression | Expression | The other vector (represented as an <code>Expression</code>) to compare against. |
<b>Returns:</b>
A new Expression representing the Euclidean distance between the two vectors.
// Calculate the Euclidean distance between two vector fields: 'pointA' and 'pointB'
euclideanDistance("pointA", field("pointB"));
Creates an expression that checks if a field exists.
<b>Signature:</b>
export declare function exists(fieldName: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
<b>Returns:</b>
A new Expression representing the 'exists' check.
// Check if the document has a field named "phoneNumber"
exists("phoneNumber");
Creates an expression that computes e to the power of the expression's result.
<b>Signature:</b>
export declare function exp(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string |
<b>Returns:</b>
A new Expression representing the exp of the numeric value.
// Compute e to the power of the 'value' field.
exp('value');
Creates an aggregation that finds the first value of a field across multiple stage inputs.
<b>Signature:</b>
export declare function first(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to find the first value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'first' aggregation.
// Find the first value of the 'rating' field
first("rating").as("firstRating");
Creates an expression that computes the floor of a numeric value.
<b>Signature:</b>
export declare function floor(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the floor of. |
<b>Returns:</b>
A new Expression representing the floor of the numeric value.
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Evaluates to the distance in meters between the location in the specified field and the query location.
This Expression can only be used within a Search stage.
<b>Signature:</b>
export declare function geoDistance(fieldName: string | Field, location: GeoPoint | Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Field | Specifies the field in the document which contains the first GeoPoint for distance computation. |
| location | GeoPoint | Expression | Compute distance to this GeoPoint. |
<b>Returns:</b>
db.pipeline().collection('restaurants').search({
query: 'waffles',
sort: geoDistance('location', new GeoPoint(37.0, -122.0)).ascending()
})
Creates an expression that checks if a field's value is greater than an expression.
<b>Signature:</b>
export declare function greaterThan(fieldName: string, expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| expression | Expression | The expression to compare to. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the value of field 'age' is greater than the value of field 'limit'
greaterThan("age", field("limit"));
Creates an expression that checks if a field's value is greater than a constant value.
<b>Signature:</b>
export declare function greaterThan(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the 'price' field is greater than 100
greaterThan("price", 100);
Creates an expression that checks if a field's value is greater than or equal to an expression.
<b>Signature:</b>
export declare function greaterThanOrEqual(fieldName: string, value: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | Expression | The expression to compare to. |
<b>Returns:</b>
A new Expression representing the greater than or equal to comparison.
// Check if the value of field 'age' is greater than or equal to the value of field 'limit'
greaterThanOrEqual("age", field("limit"));
Creates an expression that checks if a field's value is greater than or equal to a constant value.
<b>Signature:</b>
export declare function greaterThanOrEqual(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare 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
greaterThanOrEqual("score", 80);
Creates an expression that checks if the value in the specified field 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>
export declare function isType(fieldName: string, type: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to check. |
| type | string | The type to check for. |
<b>Returns:</b>
A new BooleanExpression that evaluates to true if the field's value is of the given type, false otherwise.
// Check if the 'price' field is a floating point number (evaluating to true inside pipeline conditionals)
isType('price', 'float64');
Creates an aggregation that finds the last value of a field across multiple stage inputs.
<b>Signature:</b>
export declare function last(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to find the last value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'last' aggregation.
// Find the last value of the 'rating' field
last("rating").as("lastRating");
Creates an expression that calculates the length of a string, array, map, vector, or bytes.
<b>Signature:</b>
declare function length_2(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to calculate the length of. |
<b>Returns:</b>
A new Expression representing the length of the string, array, map, vector, or bytes.
// Get the length of the 'name' field.
length("name");
// Get the number of items in the 'cart' array.
length("cart");
Creates an expression that checks if a field's value is less than an expression.
<b>Signature:</b>
export declare function lessThan(fieldName: string, expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| expression | Expression | The expression to compare to. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'age' field is less than the 'limit' field
lessThan("age", field("limit"));
Creates an expression that checks if a field's value is less than a constant value.
<b>Signature:</b>
export declare function lessThan(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'price' field is less than 50
lessThan("price", 50);
Creates an expression that checks if a field's value is less than or equal to an expression.
<b>Signature:</b>
export declare function lessThanOrEqual(fieldName: string, expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| expression | Expression | The expression to compare 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 the 'limit' field
lessThan("quantity", field("limit"));
Creates an expression that checks if a field's value is less than or equal to a constant value.
<b>Signature:</b>
export declare function lessThanOrEqual(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare 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
lessThan("score", 70);
Creates an expression that performs a case-sensitive wildcard string comparison against a field.
<b>Signature:</b>
export declare function like(fieldName: string, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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 string "guide"
like("title", "%guide%");
Creates an expression that performs a case-sensitive wildcard string comparison against a field.
<b>Signature:</b>
export declare function like(fieldName: string, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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 string "guide"
like("title", field("pattern"));
Creates an expression that computes the natural logarithm of a numeric value.
<b>Signature:</b>
export declare function ln(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the natural logarithm of. |
<b>Returns:</b>
A new Expression representing the natural logarithm of the numeric value.
// Compute the natural logarithm of the 'value' field.
ln("value");
Creates an expression that computes the logarithm of a field to a given base.
<b>Signature:</b>
export declare function log(fieldName: string, base: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the logarithm of. |
| base | number | The base of the logarithm. |
<b>Returns:</b>
A new Expression representing the logarithm of the numeric value.
// Compute the logarithm of the 'value' field with base 10.
log("value", 10);
Creates an expression that computes the logarithm of a field to a given base.
<b>Signature:</b>
export declare function log(fieldName: string, base: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the logarithm of. |
| base | Expression | The base of the logarithm. |
<b>Returns:</b>
A new Expression representing the logarithm of the numeric value.
// Compute the logarithm of the 'value' field with the base in the 'base' field.
log("value", field("base"));
Creates an expression that computes the base-10 logarithm of a numeric value.
<b>Signature:</b>
export declare function log10(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the base-10 logarithm of. |
<b>Returns:</b>
A new Expression representing the base-10 logarithm of the numeric value.
// Compute the base-10 logarithm of the 'value' field.
log10("value");
Creates an expression that returns the largest value between multiple input expressions or literal values. Based on Firestore's value type ordering.
<b>Signature:</b>
export declare function logicalMaximum(fieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The first operand field name. |
| second | Expression | unknown | The second expression or literal. |
| others | Array<Expression | unknown> | Optional additional expressions or literals. |
<b>Returns:</b>
A new Expression representing the logical maximum operation.
// Returns the largest value between the 'field1' field, the 'field2' field,
// and 1000.
logicalMaximum("field1", field("field2"), 1000);
Creates an expression that returns the smallest value between a field's value and other input expressions or literal values. Based on Firestore's value type ordering.
<b>Signature:</b>
export declare function logicalMinimum(fieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The first operand field name. |
| second | Expression | unknown | The second expression or literal. |
| others | Array<Expression | unknown> | Optional additional expressions or literals. |
<b>Returns:</b>
A new Expression representing the logical minimum operation.
// Returns the smallest value between the 'field1' field, the 'field2' field,
// and 1000.
logicalMinimum("field1", field("field2"), 1000);
Trims whitespace or a specified set of characters/bytes from the beginning of a string or byte array.
<b>Signature:</b>
export declare function ltrim(fieldName: string, valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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 beginning of the 'userInput' field
ltrim(field("userInput"));
// Trim quotes from the beginning of the 'userInput' field
ltrim(field("userInput"), '"');
Accesses a value from a map (object) field using the provided key.
<b>Signature:</b>
export declare function mapGet(fieldName: string, subField: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name of the map field. |
| 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
mapGet("address", "city");
Creates an aggregation that finds the maximum value of a field across multiple stage inputs.
<b>Signature:</b>
export declare function maximum(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to find the maximum value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'maximum' aggregation.
// Find the highest score in a leaderboard
maximum("score").as("highestScore");
Creates an aggregation that finds the minimum value of a field across multiple stage inputs.
<b>Signature:</b>
export declare function minimum(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to find the minimum value of. |
<b>Returns:</b>
A new AggregateFunction representing the 'minimum' aggregation.
// Find the lowest price of all products
minimum("price").as("lowestPrice");
Creates an expression that calculates the modulo (remainder) of dividing a field's value by an expression.
<b>Signature:</b>
export declare function mod(fieldName: string, expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The dividend field name. |
| expression | Expression | The divisor expression. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing 'field1' by 'field2'.
mod("field1", field("field2"));
Creates an expression that calculates the modulo (remainder) of dividing a field's value by a constant.
<b>Signature:</b>
export declare function mod(fieldName: string, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The dividend field name. |
| value | unknown | The divisor constant. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing 'field1' by 5.
mod("field1", 5);
Creates an expression that multiplies a field's value by an expression.
<b>Signature:</b>
export declare function multiply(fieldName: string, second: Expression | unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the value to add. |
| second | Expression | unknown | The second expression or literal to add. |
<b>Returns:</b>
A new Expression representing the multiplication operation.
// Multiply the 'quantity' field by the 'price' field
multiply("quantity", field("price"));
Creates an expression that checks if a field's value is not equal to an expression.
<b>Signature:</b>
export declare function notEqual(fieldName: string, expression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| expression | Expression | The expression to compare to. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'status' field is not equal to the value of 'expectedStatus'
notEqual("status", field("expectedStatus"));
Creates an expression that checks if a field's value is not equal to a constant value.
<b>Signature:</b>
export declare function notEqual(fieldName: string, value: unknown): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| value | unknown | The constant value to compare to. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'country' field is not equal to "USA"
notEqual("country", "USA");
Creates an expression that checks if a field's value is not equal to any of the provided values or expressions.
<b>Signature:</b>
export declare function notEqualAny(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| values | Array<Expression | unknown> | The values to check against. |
<b>Returns:</b>
A new Expression representing the 'NOT IN' comparison.
// Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
notEqualAny("status", [constant("pending"), field("rejectedStatus")]);
Creates an expression that checks if a field's value is not equal to any of the values in the evaluated expression.
<b>Signature:</b>
export declare function notEqualAny(fieldName: string, arrayExpression: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to compare. |
| arrayExpression | Expression | The values to check against. |
<b>Returns:</b>
A new Expression representing the 'NOT IN' comparison.
// Check if the 'status' field is not equal to any value in the field 'rejectedStatuses'
notEqualAny("status", field("rejectedStatuses"));
Creates an expression that checks if a string field contains a specified regular expression as a substring.
<b>Signature:</b>
export declare function regexContains(fieldName: string, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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)
regexContains("description", "(?i)example");
Creates an expression that checks if a string field contains a specified regular expression as a substring.
<b>Signature:</b>
export declare function regexContains(fieldName: string, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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 "example" (case-insensitive)
regexContains("description", field("pattern"));
Creates an expression that returns the first substring of a string field that matches a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFind(fieldName: string, pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string to search. |
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract the domain name from an email field
regexFind("email", "@[A-Za-z0-9.-]+");
Creates an expression that returns the first substring of a string field that matches a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFind(fieldName: string, pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string to search. |
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract a substring from 'email' based on a pattern stored in another field
regexFind("email", field("pattern"));
Creates an expression that evaluates to a list of all substrings in a string field that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFindAll(fieldName: string, pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string to search. |
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new FunctionExpression that evaluates to an array of matched substrings.
// Extract all hashtags from a post content field
regexFindAll("content", "#[A-Za-z0-9_]+");
Creates an expression that evaluates to a list of all substrings in a string field that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFindAll(fieldName: string, pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string to search. |
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new FunctionExpression that evaluates to an array of matched substrings.
// Extract all matches from 'content' based on a pattern stored in another field
regexFindAll("content", field("pattern"));
Creates an expression that checks if a string field matches a specified regular expression.
<b>Signature:</b>
export declare function regexMatch(fieldName: string, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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
regexMatch("email", "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");
Creates an expression that checks if a string field matches a specified regular expression.
<b>Signature:</b>
export declare function regexMatch(fieldName: string, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| 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 valid email pattern
regexMatch("email", field("pattern"));
Creates an expression that rounds a numeric value to the nearest whole number.
<b>Signature:</b>
export declare function round(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to round. |
<b>Returns:</b>
A new Expression representing the rounded value.
// Round the value of the 'price' field.
round("price");
Creates an expression that rounds a numeric value to the specified number of decimal places.
<b>Signature:</b>
export declare function round(fieldName: string, decimalPlaces: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to round. |
| decimalPlaces | number | Expression | A constant or 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.
round("price", 2);
Trims whitespace or a specified set of characters/bytes from the end of a string or byte array.
<b>Signature:</b>
export declare function rtrim(fieldName: string, valueToTrim?: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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
rtrim(field("userInput"));
// Trim quotes from the end of the 'userInput' field
rtrim(field("userInput"), '"');
Creates an expression that splits the value of a field on the provided delimiter.
<b>Signature:</b>
export declare function split(fieldName: string, delimiter: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Split the value in this field. |
| delimiter | string | Split on this delimiter. |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scoresCsv' field on delimiter ','
split('scoresCsv', ',')
Creates an expression that splits the value of a field on the provided delimiter.
<b>Signature:</b>
export declare function split(fieldName: string, delimiter: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Split the value in this field. |
| delimiter | Expression | Split on this delimiter returned by evaluating this expression. |
<b>Returns:</b>
A new Expression representing the split function.
// Split the 'scores' field on delimiter ',' or ':' depending on the stored format
split('scores', conditional(field('format').equal('csv'), constant(','), constant(':')))
Creates an expression that computes the square root of a numeric value.
<b>Signature:</b>
export declare function sqrt(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to compute the square root of. |
<b>Returns:</b>
A new Expression representing the square root of the numeric value.
// Compute the square root of the 'value' field.
sqrt("value");
Creates an expression that checks if a field's value starts with a given prefix.
<b>Signature:</b>
export declare function startsWith(fieldName: string, prefix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| 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."
startsWith("name", "Mr.");
Creates an expression that checks if a field's value starts with a given prefix.
<b>Signature:</b>
export declare function startsWith(fieldName: string, prefix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to check. |
| prefix | Expression | The expression representing the prefix. |
<b>Returns:</b>
A new Expression representing the 'starts with' comparison.
// Check if the 'fullName' field starts with the value of the 'firstName' field
startsWith("fullName", field("firstName"));
Creates an expression that concatenates string functions, fields or constants together.
<b>Signature:</b>
export declare function stringConcat(fieldName: string, secondString: Expression | string, ...otherStrings: Array<Expression | string>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name containing the initial string value. |
| secondString | Expression | string | An expression or string literal to concatenate. |
| otherStrings | Array<Expression | string> | Optional additional expressions or literals (typically strings) to concatenate. |
<b>Returns:</b>
A new Expression representing the concatenated string.
// Combine the 'firstName', " ", and 'lastName' fields into a single string
stringConcat("firstName", " ", field("lastName"));
Creates an expression that checks if a string field contains a specified substring.
<b>Signature:</b>
export declare function stringContains(fieldName: string, substring: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| substring | string | The substring to search for. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains "example".
stringContains("description", "example");
Creates an expression that checks if a string field contains a substring specified by an expression.
<b>Signature:</b>
export declare function stringContains(fieldName: string, substring: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
| substring | 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.
stringContains("description", field("keyword"));
Creates an expression that finds the index of the first occurrence of a substring or byte sequence.
<b>Signature:</b>
export declare function stringIndexOf(fieldName: string, search: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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
stringIndexOf("text", "foo");
Creates an expression that repeats a string or byte array a specified number of times.
<b>Signature:</b>
export declare function stringRepeat(fieldName: string, repetitions: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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
stringRepeat("label", 3);
Creates an expression that replaces all occurrences of a substring or byte sequence with a replacement.
<b>Signature:</b>
export declare function stringReplaceAll(fieldName: string, find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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
stringReplaceAll("text", "foo", "bar");
Creates an expression that replaces the first occurrence of a substring or byte sequence with a replacement.
<b>Signature:</b>
export declare function stringReplaceOne(fieldName: string, find: string | Expression | Bytes, replacement: string | Expression | Bytes): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| 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
stringReplaceOne("text", "foo", "bar");
Creates an expression that subtracts an expression from a field's value.
<b>Signature:</b>
export declare function subtract(fieldName: string, expression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to subtract from. |
| expression | Expression | The expression to subtract. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract the 'discount' field from the 'price' field
subtract("price", field("discount"));
Creates an expression that subtracts a constant value from a field's value.
<b>Signature:</b>
export declare function subtract(fieldName: string, value: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The field name to subtract from. |
| value | unknown | The constant value to subtract. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract 20 from the value of the 'total' field
subtract("total", 20);
Creates an aggregation that calculates the sum of a field's values across multiple stage inputs.
<b>Signature:</b>
export declare function sum(fieldName: string): AggregateFunction;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing numeric values to sum up. |
<b>Returns:</b>
A new AggregateFunction representing the 'sum' aggregation.
// Calculate the total revenue from a set of orders
sum("orderAmount").as("totalRevenue");
Creates an expression that adds a specified amount of time to a timestamp represented by a field.
<b>Signature:</b>
export declare function timestampAdd(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
| 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.
timestampAdd("timestamp", "day", 1);
Creates an expression that extracts a specified part from a timestamp.
<b>Signature:</b>
export declare function timestampExtract(fieldName: string, part: TimePart, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
| 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' timestamp.
timestampExtract('createdAt', 'year')
Creates an expression that extracts a specified part from a timestamp.
<b>Signature:</b>
export declare function timestampExtract(fieldName: string, part: Expression, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
| 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 'part' from 'createdAt'.
timestampExtract('createdAt', field('part'))
Creates an expression that subtracts a specified amount of time from a timestamp represented by a field.
<b>Signature:</b>
export declare function timestampSubtract(fieldName: string, unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
| 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.
timestampSubtract("timestamp", "day", 1);
Creates an expression that converts a timestamp field to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixMicros(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of microseconds since epoch.
// Convert the 'timestamp' field to microseconds since epoch.
timestampToUnixMicros("timestamp");
Creates an expression that converts a timestamp field to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixMillis(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of milliseconds since epoch.
// Convert the 'timestamp' field to milliseconds since epoch.
timestampToUnixMillis("timestamp");
Creates an expression that converts a timestamp field to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
<b>Signature:</b>
export declare function timestampToUnixSeconds(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the timestamp. |
<b>Returns:</b>
A new Expression representing the number of seconds since epoch.
// Convert the 'timestamp' field to seconds since epoch.
timestampToUnixSeconds("timestamp");
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
export declare function timestampTruncate(fieldName: string, granularity: TimeGranularity, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Truncate the timestamp value contained in this field. |
| 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.
timestampTruncate('createdAt', 'day')
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
export declare function timestampTruncate(fieldName: string, granularity: Expression, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | Truncate the timestamp value contained in this field. |
| 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'.
timestampTruncate('createdAt', field('granularity'))
Creates an expression that converts a string field to lowercase.
<b>Signature:</b>
export declare function toLower(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
<b>Returns:</b>
A new Expression representing the lowercase string.
// Convert the 'name' field to lowercase
toLower("name");
Creates an expression that converts a string field to uppercase.
<b>Signature:</b>
export declare function toUpper(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string. |
<b>Returns:</b>
A new Expression representing the uppercase string.
// Convert the 'title' field to uppercase
toUpper("title");
Creates an expression that removes leading and trailing whitespace from a string or byte array.
<b>Signature:</b>
export declare function trim(fieldName: string, valueToTrim?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the string or byte array. |
| valueToTrim | string | Expression | 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.
// Trim whitespace from the 'userInput' field
trim("userInput");
// Trim quotes from the 'userInput' field
trim("userInput", '"');
Creates an expression that truncates the numeric value of a field to an integer.
<b>Signature:</b>
export declare function trunc(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field containing the number to truncate. |
<b>Returns:</b>
A new Expression representing the truncated value.
// Truncate the value of the 'rating' field
trunc("rating");
Creates an expression that truncates a numeric expression to the specified number of decimal places.
<b>Signature:</b>
export declare function trunc(fieldName: string, decimalPlaces: number | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field to truncate. |
| decimalPlaces | number | Expression | A constant or 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.
trunc("rating", 2);
Creates an expression that returns the data type of the data in the specified field.
String inputs passed iteratively to this global function act as field() path lookups. If you wish to pass a string literal value, it must be wrapped: type(constant("my_string"))<!-- -->.
<b>Signature:</b>
export declare function type(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string |
<b>Returns:</b>
A new Expression representing the data type.
// Get the data type of the value in field 'title'
type('title')
Creates an expression that interprets a field's value as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixMicrosToTimestamp(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the number of microseconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'microseconds' field as microseconds since epoch.
unixMicrosToTimestamp("microseconds");
Creates an expression that interprets a field's value as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixMillisToTimestamp(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the number of milliseconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'milliseconds' field as milliseconds since epoch.
unixMillisToTimestamp("milliseconds");
Creates an expression that interprets a field's value as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC) and returns a timestamp.
<b>Signature:</b>
export declare function unixSecondsToTimestamp(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the number of seconds since epoch. |
<b>Returns:</b>
A new Expression representing the timestamp.
// Interpret the 'seconds' field as seconds since epoch.
unixSecondsToTimestamp("seconds");
Creates an expression that calculates the length of a Firestore Vector represented by a field.
<b>Signature:</b>
export declare function vectorLength(fieldName: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| fieldName | string | The name of the field representing the Firestore Vector. |
<b>Returns:</b>
A new Expression representing the length of the array.
// Get the vector length (dimension) of the field 'embedding'.
vectorLength("embedding");
Creates an expression that adds two expressions together.
<b>Signature:</b>
export declare function add(first: Expression, second: Expression | unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| first | Expression | The first expression to add. |
| second | Expression | unknown | The second expression or literal to add. |
<b>Returns:</b>
A new Expression representing the addition operation.
// Add the value of the 'quantity' field and the 'reserve' field.
add(field("quantity"), field("reserve"));
Creates an expression that performs a logical 'AND' operation on multiple filter conditions.
<b>Signature:</b>
export declare function and(first: BooleanExpression, second: BooleanExpression, ...more: BooleanExpression[]): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| first | BooleanExpression | The first filter condition. |
| second | BooleanExpression | The second filter condition. |
| more | BooleanExpression<!-- -->[] | Additional filter conditions to 'AND' together. |
<b>Returns:</b>
A new Expression representing the logical 'AND' operation.
// Check if the 'age' field is greater than 18 AND the 'city' field is "London" AND
// the 'status' field is "active"
const condition = and(greaterThan("age", 18), equal("city", "London"), equal("status", "active"));
Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
<b>Signature:</b>
export declare function concat(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| first | Expression | The first expressions to concatenate. |
| second | Expression | unknown | The second literal or expression to concatenate. |
| others | Array<Expression | unknown> | Additional literals or expressions to concatenate. |
<b>Returns:</b>
A new Expression representing the concatenation.
// Concatenate the 'firstName' and 'lastName' fields with a space in between.
concat(field("firstName"), " ", field("lastName"))
Creates an expression that returns the largest value between multiple input expressions or literal values. Based on Firestore's value type ordering.
<b>Signature:</b>
export declare function logicalMaximum(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| first | Expression | The first operand expression. |
| second | Expression | unknown | The second expression or literal. |
| others | Array<Expression | unknown> | Optional additional expressions or literals. |
<b>Returns:</b>
A new Expression representing the logical maximum operation.
// Returns the largest value between the 'field1' field, the 'field2' field,
// and 1000
logicalMaximum(field("field1"), field("field2"), 1000);
Creates an expression that returns the smallest value between multiple input expressions and literal values. Based on Firestore's value type ordering.
<b>Signature:</b>
export declare function logicalMinimum(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| first | Expression | The first operand expression. |
| second | Expression | unknown | The second expression or literal. |
| others | Array<Expression | unknown> | Optional additional expressions or literals. |
<b>Returns:</b>
A new Expression representing the logical minimum operation.
// Returns the smallest value between the 'field1' field, the 'field2' field,
// and 1000.
logicalMinimum(field("field1"), field("field2"), 1000);
Creates an expression that multiplies two expressions together.
<b>Signature:</b>
export declare function multiply(first: Expression, second: Expression | unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| first | Expression | The first expression to multiply. |
| second | Expression | unknown | The second expression or literal to multiply. |
<b>Returns:</b>
A new Expression representing the multiplication operation.
// Multiply the 'quantity' field by the 'price' field
multiply(field("quantity"), field("price"));
Creates an expression that performs a logical 'NOR' operation on multiple filter conditions.
<b>Signature:</b>
export declare function nor(first: BooleanExpression, second: BooleanExpression, ...more: BooleanExpression[]): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| first | BooleanExpression | The first filter condition. |
| second | BooleanExpression | The second filter condition. |
| more | BooleanExpression<!-- -->[] | Additional filter conditions to 'NOR' together. |
<b>Returns:</b>
A new BooleanExpression representing the logical 'NOR' operation.
// Check if neither the 'age' field is greater than 18 nor the 'city' field is "London"
const condition = nor(
greaterThan("age", 18),
equal("city", "London")
);
Creates an expression that performs a logical 'OR' operation on multiple filter conditions.
<b>Signature:</b>
export declare function or(first: BooleanExpression, second: BooleanExpression, ...more: BooleanExpression[]): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| first | BooleanExpression | The first filter condition. |
| second | BooleanExpression | The second filter condition. |
| more | BooleanExpression<!-- -->[] | Additional filter conditions to 'OR' together. |
<b>Returns:</b>
A new Expression representing the logical 'OR' operation.
// Check if the 'age' field is greater than 18 OR the 'city' field is "London" OR
// the 'status' field is "active"
const condition = or(greaterThan("age", 18), equal("city", "London"), equal("status", "active"));
Creates an expression that performs a logical 'XOR' (exclusive OR) operation on multiple BooleanExpressions.
<b>Signature:</b>
export declare function xor(first: BooleanExpression, second: BooleanExpression, ...additionalConditions: BooleanExpression[]): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| first | BooleanExpression | The first condition. |
| second | BooleanExpression | The second condition. |
| additionalConditions | BooleanExpression<!-- -->[] | Additional conditions to 'XOR' together. |
<b>Returns:</b>
A new Expression representing the logical 'XOR' operation.
// Check if only one of the conditions is true: 'age' greater than 18, 'city' is "London",
// or 'status' is "active".
const condition = xor(
greaterThan("age", 18),
equal("city", "London"),
equal("status", "active"));
Creates an expression that concatenates an array expression with other arrays.
<b>Signature:</b>
export declare function arrayConcat(firstArray: Expression, secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| firstArray | Expression | The first array expression to concatenate to. |
| secondArray | Expression | unknown[] | The second array expression or array literal to concatenate to. |
| 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 two new item arrays
arrayConcat(field("items"), [field("newItems"), field("otherItems")]);
Creates an expression that concatenates a field's array value with other arrays.
<b>Signature:</b>
export declare function arrayConcat(firstArrayField: string, secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| firstArrayField | string | The first array to concatenate to. |
| secondArray | Expression | unknown[] | The second array expression or array literal to concatenate to. |
| 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 two new item arrays
arrayConcat("items", [field("newItems"), field("otherItems")]);
Creates an expression that merges multiple map values.
<b>Signature:</b>
export declare function mapMerge(firstMap: Record<string, unknown> | Expression, secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| firstMap | Record<string, unknown> | Expression | An expression or literal map value that will be merged. |
| 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>
// Merges the map in the settings field with, a map literal, and a map in
// that is conditionally returned by another expression
mapMerge(field('settings'), { enabled: true }, conditional(field('isAdmin'), { admin: true}, {})
Creates an expression that concatenates string expressions together.
<b>Signature:</b>
export declare function stringConcat(firstString: Expression, secondString: Expression | string, ...otherStrings: Array<Expression | string>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| firstString | Expression | The initial string expression to concatenate to. |
| secondString | Expression | string | An expression or string literal to concatenate. |
| otherStrings | Array<Expression | string> | Optional additional expressions or literals (typically strings) to concatenate. |
<b>Returns:</b>
A new Expression representing the concatenated string.
// Combine the 'firstName', " ", and 'lastName' fields into a single string
stringConcat(field("firstName"), " ", field("lastName"));
Creates an expression that returns the elseExpr argument if ifExpr is absent, else return the result of the ifExpr argument evaluation.
<b>Signature:</b>
export declare function ifAbsent(ifExpr: Expression, elseExpr: Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| ifExpr | Expression | The expression to check for absence. |
| elseExpr | Expression | The expression that will be evaluated and returned if [ifExpr] is absent. |
<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.
ifAbsent(field("optional_field"), constant("default_value"))
Creates an expression that returns the elseValue argument if ifExpr is absent, else return the result of the ifExpr argument evaluation.
<b>Signature:</b>
export declare function ifAbsent(ifExpr: Expression, elseValue: unknown): Expression;
| Parameter | Type | Description |
|---|---|---|
| ifExpr | Expression | The expression to check for absence. |
| elseValue | unknown | The value that will be returned if <code>ifExpr</code> 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.
ifAbsent(field("optional_field"), "default_value")
Creates an expression that returns the elseExpr argument if ifExpr is null, else return the result of the ifExpr argument evaluation.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
export declare function ifNull(ifExpr: Expression, elseExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| ifExpr | Expression | The expression to check for null. |
| elseExpr | Expression | The expression that will be evaluated and returned if <code>ifExpr</code> is 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.
ifNull(field("preferredName"), field("fullName"))
Creates an expression that returns the elseValue argument if ifExpr is null, else return the result of the ifExpr argument evaluation.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
export declare function ifNull(ifExpr: Expression, elseValue: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| ifExpr | Expression | The expression to check for null. |
| elseValue | unknown | The value that will be returned if <code>ifExpr</code> 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.
ifNull(field("displayName"), "Anonymous")
Creates an expression that returns the elseExpr argument if ifFieldName is absent, else return the value of the field.
<b>Signature:</b>
export declare function ifAbsent(ifFieldName: string, elseExpr: Expression): Expression;
| Parameter | Type | Description |
|---|---|---|
| ifFieldName | string | The field to check for absence. |
| elseExpr | Expression | The expression that will be evaluated and returned if <code>ifFieldName</code> is absent. |
<b>Returns:</b>
A new Expression representing the ifAbsent operation.
// Returns the value of the optional field 'optional_field', or returns the value of
// 'default_field' if 'optional_field' is absent.
ifAbsent("optional_field", field("default_field"))
Creates an expression that returns the elseValue argument if ifFieldName is absent, else return the value of the field.
<b>Signature:</b>
export declare function ifAbsent(ifFieldName: string | Expression, elseValue: Expression | unknown): Expression;
| Parameter | Type | Description |
|---|---|---|
| ifFieldName | string | Expression | The field to check for absence. |
| elseValue | Expression | unknown | The value that will be returned if [ifFieldName] is absent. |
<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.
ifAbsent("optional_field", "default_value")
Creates an expression that returns the elseExpr argument if ifFieldName field is null, else return the value of the field.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
export declare function ifNull(ifFieldName: string, elseExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| ifFieldName | string | The field to check for null. |
| elseExpr | Expression | The expression that will be evaluated and returned if <code>ifFieldName</code> is 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.
ifNull("preferredName", field("fullName"))
Creates an expression that returns the elseValue argument if ifFieldName field is null, else return the value of the field.
This function provides a fallback for both absent and explicit null values. In contrast, ifAbsent() only triggers for missing fields.
<b>Signature:</b>
export declare function ifNull(ifFieldName: string, elseValue: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| ifFieldName | string | The field to check for null. |
| elseValue | unknown | The value that will be returned if <code>ifFieldName</code> is 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.
ifNull("displayName", "Anonymous")
Creates an expression that returns a substring of a string or byte array.
<b>Signature:</b>
export declare function substring(input: Expression, position: number, length?: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| input | Expression | An expression returning a string or byte array to compute the substring from. |
| position | number | Index of the first character of the substring. |
| length | number | Length of the substring. |
<b>Returns:</b>
Creates an expression that returns a substring of a string or byte array.
<b>Signature:</b>
export declare function substring(input: Expression, position: Expression, length?: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| input | Expression | An expression returning a string or byte array to compute the substring from. |
| position | Expression | An expression that returns the index of the first character of the substring. |
| length | Expression | An expression that returns the length of the substring. |
<b>Returns:</b>
Creates an expression that divides two expressions.
<b>Signature:</b>
export declare function divide(left: Expression, right: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The expression to be divided. |
| right | Expression | The expression to divide by. |
<b>Returns:</b>
A new Expression representing the division operation.
// Divide the 'total' field by the 'count' field
divide(field("total"), field("count"));
Creates an expression that checks if two expressions are equal.
<b>Signature:</b>
export declare function equal(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<b>Returns:</b>
A new Expression representing the equality comparison.
// Check if the 'age' field is equal to an expression
equal(field("age"), field("minAge").add(10));
Creates an expression that checks if the first expression is greater than the second expression.
<b>Signature:</b>
export declare function greaterThan(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<b>Returns:</b>
A new Expression representing the greater than comparison.
// Check if the 'age' field is greater than 18
greaterThan(field("age"), constant(9).add(9));
Creates an expression that checks if the first expression is greater than or equal to the second expression.
<b>Signature:</b>
export declare function greaterThanOrEqual(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<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 the field "threshold"
greaterThanOrEqual(field("quantity"), field("threshold"));
Creates an expression that checks if the first expression is less than the second expression.
<b>Signature:</b>
export declare function lessThan(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<b>Returns:</b>
A new Expression representing the less than comparison.
// Check if the 'age' field is less than 30
lessThan(field("age"), field("limit"));
Creates an expression that checks if the first expression is less than or equal to the second expression.
<b>Signature:</b>
export declare function lessThanOrEqual(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<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
lessThan(field("quantity"), field("limit"));
Creates an expression that calculates the modulo (remainder) of dividing two expressions.
<b>Signature:</b>
export declare function mod(left: Expression, right: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The dividend expression. |
| right | Expression | The divisor expression. |
<b>Returns:</b>
A new Expression representing the modulo operation.
// Calculate the remainder of dividing 'field1' by 'field2'.
mod(field("field1"), field("field2"));
Creates an expression that checks if two expressions are not equal.
<b>Signature:</b>
export declare function notEqual(left: Expression, right: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The first expression to compare. |
| right | Expression | The second expression to compare. |
<b>Returns:</b>
A new Expression representing the inequality comparison.
// Check if the 'status' field is not equal to field 'finalState'
notEqual(field("status"), field("finalState"));
Creates an expression that subtracts two expressions.
<b>Signature:</b>
export declare function subtract(left: Expression, right: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| left | Expression | The expression to subtract from. |
| right | Expression | The expression to subtract. |
<b>Returns:</b>
A new Expression representing the subtraction operation.
// Subtract the 'discount' field from the 'price' field
subtract(field("price"), field("discount"));
Creates an expression that removes a key from the map produced by evaluating an expression.
<b>Signature:</b>
export declare function mapRemove(mapExpr: Expression, key: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpr | Expression | An expression return a map value. |
| key | string | The name of the key to remove from the input map. |
<b>Returns:</b>
// Removes the key 'baz' from the input map.
mapRemove(map({foo: 'bar', baz: true}), 'baz');
@example
Creates an expression that removes a key from the map produced by evaluating an expression.
<b>Signature:</b>
export declare function mapRemove(mapExpr: Expression, keyExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpr | Expression | An expression return a map value. |
| keyExpr | Expression | An expression that produces the name of the key to remove from the input map. |
<b>Returns:</b>
// Removes the key 'baz' from the input map.
mapRemove(map({foo: 'bar', baz: true}), constant('baz'));
@example
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" }, ...]<!-- -->.
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>
export declare function mapEntries(mapExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpression | Expression | The expression representing the map to get the entries of. |
<b>Returns:</b>
A new Expression representing the entries of the map.
// Get the entries of the map expression
mapEntries(map({"city": "San Francisco"}));
Accesses a value from a map (object) expression using the provided key.
<b>Signature:</b>
export declare function mapGet(mapExpression: Expression, subField: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpression | Expression | The expression representing the map. |
| 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
mapGet(field("address"), "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>
export declare function mapKeys(mapExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpression | Expression | The expression representing the map to get the keys of. |
<b>Returns:</b>
A new Expression representing the keys of the map.
// Get the keys of the map expression
mapKeys(map({"city": "San Francisco"}));
Creates an expression that returns a new map with the specified entries added or updated.
This 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>
export declare function mapSet(mapExpression: Expression, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpression | Expression | The expression representing the map. |
| 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"
mapSet(map({"state": "California"}), "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>
export declare function mapValues(mapExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapExpression | Expression | The expression representing the map to get the values of. |
<b>Returns:</b>
A new Expression representing the values of the map.
// Get the values of the map expression
mapValues(map({"city": "San Francisco"}));
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" }, ...]<!-- -->.
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>
export declare function mapEntries(mapField: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The map field to get the entries of. |
<b>Returns:</b>
A new Expression representing the entries of the map.
// Get the entries of the 'address' map field
mapEntries("address");
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>
export declare function mapKeys(mapField: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The map field to get the keys of. |
<b>Returns:</b>
A new Expression representing the keys of the map.
// Get the keys of the 'address' map field
mapKeys("address");
Creates an expression that merges multiple map values.
<b>Signature:</b>
export declare function mapMerge(mapField: string, secondMap: Record<string, unknown> | Expression, ...otherMaps: Array<Record<string, unknown> | Expression>): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | Name of a field containing a map value that will be merged. |
| 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>
// Merges the map in the settings field with, a map literal, and a map in
// that is conditionally returned by another expression
mapMerge('settings', { enabled: true }, conditional(field('isAdmin'), { admin: true}, {})
Creates an expression that removes a key from the map at the specified field name.
<b>Signature:</b>
export declare function mapRemove(mapField: string, key: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The name of a field containing a map value. |
| key | string | The name of the key to remove from the input map. |
<b>Returns:</b>
// Removes the key 'city' field from the map in the address field of the input document.
mapRemove('address', 'city');
Creates an expression that removes a key from the map at the specified field name.
<b>Signature:</b>
export declare function mapRemove(mapField: string, keyExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The name of a field containing a map value. |
| keyExpr | Expression | An expression that produces the name of the key to remove from the input map. |
<b>Returns:</b>
// Removes the key 'city' field from the map in the address field of the input document.
mapRemove('address', constant('city'));
Creates an expression that returns a new map with the specified entries added or updated.
This 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>
export declare function mapSet(mapField: string, key: string | Expression, value: unknown, ...moreKeyValues: unknown[]): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The map field to set entries in. |
| 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
mapSet("address", "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>
export declare function mapValues(mapField: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| mapField | string | The map field to get the values of. |
<b>Returns:</b>
A new Expression representing the values of the map.
// Get the values of the 'address' map field
mapValues("address");
Creates a Field instance representing the field at the given path.
The path can be a simple field name (e.g., "name") or a dot-separated path to a nested field (e.g., "address.city").
<b>Signature:</b>
export declare function field(name: string): Field;
| Parameter | Type | Description |
|---|---|---|
| name | string | The path to the field. |
<b>Returns:</b>
A new Field instance representing the specified field.
// Create a Field instance for the 'title' field
const titleField = field("title");
// Create a Field instance for a nested field 'author.firstName'
const authorFirstNameField = field("author.firstName");
Creates an expression that retrieves the value of a variable bound via define()<!-- -->.
<b>Signature:</b>
export declare function variable(name: string): Expression;
| Parameter | Type | Description |
|---|---|---|
| name | string | The name of the variable to retrieve. |
<b>Returns:</b>
An Expression representing the variable's value.
db.pipeline().collection("products")
.define(
field("price").multiply(0.9).as("discountedPrice"),
field("stock").add(10).as("newStock")
)
.where(variable("discountedPrice").lessThan(100))
.select(field("name"), variable("newStock"));
Creates a new Pipeline targeted at a subcollection relative to the current document context. This creates a pipeline without a database instance, suitable for embedding as a subquery. If executed directly, this pipeline will fail.
<b>Signature:</b>
export declare function subcollection(options: SubcollectionStageOptions): Pipeline;
| Parameter | Type | Description |
|---|---|---|
| options | SubcollectionStageOptions | Options defining how this SubcollectionStage is evaluated. |
<b>Returns:</b>
Creates a Field instance representing the field at the given path.
<b>Signature:</b>
export declare function field(path: FieldPath): Field;
| Parameter | Type | Description |
|---|---|---|
| path | FieldPath | A FieldPath specifying the field. |
<b>Returns:</b>
A new Field instance representing the specified field.
Creates a new Pipeline targeted at a subcollection relative to the current document context. This creates a pipeline without a database instance, suitable for embedding as a subquery. If executed directly, this pipeline will fail.
<b>Signature:</b>
export declare function subcollection(path: string): Pipeline;
| Parameter | Type | Description |
|---|---|---|
| path | string | The relative path to the subcollection. |
<b>Returns:</b>
Executes this pipeline and returns a Promise to represent the asynchronous operation.
The returned Promise can be used to track the progress of the pipeline execution and retrieve the results (or handle any errors) asynchronously.
The pipeline results are returned as a PipelineSnapshot that contains a list of PipelineResult objects. Each PipelineResult typically represents a single key/value map that has passed through all the stages of the pipeline, however this might differ depending on the stages involved in the pipeline. For example:
<ul> <li>If there are no stages or only transformation stages, each [PipelineResult](./firestore_pipelines.pipelineresult.md#pipelineresult_class) represents a single document.</li> <li>If there is an aggregation, only a single [PipelineResult](./firestore_pipelines.pipelineresult.md#pipelineresult_class) is returned, representing the aggregated results over the entire dataset .</li> <li>If there is an aggregation stage with grouping, each [PipelineResult](./firestore_pipelines.pipelineresult.md#pipelineresult_class) represents a distinct group and its associated aggregated values.</li> </ul><b>Signature:</b>
export declare function execute(pipeline: Pipeline): Promise<PipelineSnapshot>;
| Parameter | Type | Description |
|---|---|---|
| pipeline | Pipeline | The pipeline to execute. |
<b>Returns:</b>
Promise<PipelineSnapshot<!-- -->>
A Promise representing the asynchronous pipeline execution.
const snapshot: PipelineSnapshot = await execute(firestore.pipeline().collection("books")
.where(gt(field("rating"), 4.5))
.select("title", "author", "rating"));
const results: PipelineResults = snapshot.results;
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Perform a full-text search on all indexed search fields in the document.
This Expression can only be used within a Search stage.
<b>Signature:</b>
export declare function documentMatches(rquery: string | Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| rquery | string | Expression | Define the search query using the search domain-specific language (DSL). |
<b>Returns:</b>
db.pipeline().collection('restaurants').search({
query: documentMatches('waffles OR pancakes')
})
Creates an expression that calculates the character length of a string expression in UTF-8.
<b>Signature:</b>
export declare function charLength(stringExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to calculate the length of. |
<b>Returns:</b>
A new Expression representing the length of the string.
// Get the character length of the 'name' field in UTF-8.
charLength(field("name"));
Creates an expression that checks if a string expression ends with a given postfix.
<b>Signature:</b>
export declare function endsWith(stringExpression: Expression, suffix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression to check. |
| suffix | string | The postfix to check for. |
<b>Returns:</b>
A new Expression representing the 'ends with' comparison.
// Check if the result of concatenating 'firstName' and 'lastName' fields ends with "Jr."
endsWith(field("fullName"), "Jr.");
Creates an expression that checks if a string expression ends with a given postfix.
<b>Signature:</b>
export declare function endsWith(stringExpression: Expression, suffix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression to check. |
| suffix | Expression | The postfix to check for. |
<b>Returns:</b>
A new Expression representing the 'ends with' comparison.
// Check if the result of concatenating 'firstName' and 'lastName' fields ends with "Jr."
endsWith(field("fullName"), constant("Jr."));
Creates an expression that performs a case-sensitive wildcard string comparison.
<b>Signature:</b>
export declare function like(stringExpression: Expression, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| 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 string "guide"
like(field("title"), "%guide%");
Creates an expression that performs a case-sensitive wildcard string comparison.
<b>Signature:</b>
export declare function like(stringExpression: Expression, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| 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 string "guide"
like(field("title"), field("pattern"));
Creates an expression that checks if a string expression contains a specified regular expression as a substring.
<b>Signature:</b>
export declare function regexContains(stringExpression: Expression, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| 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)
regexContains(field("description"), "(?i)example");
Creates an expression that checks if a string expression contains a specified regular expression as a substring.
<b>Signature:</b>
export declare function regexContains(stringExpression: Expression, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| 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 "example" (case-insensitive)
regexContains(field("description"), field("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.
<b>Signature:</b>
export declare function regexFind(stringExpression: Expression, pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to search. |
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract the domain from a lower-cased email address
regexFind(field("email"), "@[A-Za-z0-9.-]+");
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>
export declare function regexFind(stringExpression: Expression, pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to search. |
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new Expression representing the regular expression find function.
// Extract a substring based on a dynamic pattern field
regexFind(field("email"), field("pattern"));
Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFindAll(stringExpression: Expression, pattern: string): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to search. |
| pattern | string | The regular expression to search for. |
<b>Returns:</b>
A new FunctionExpression that evaluates to an array of matched substrings.
// Extract all mentions from a lower-cased comment
regexFindAll(field("comment"), "@[A-Za-z0-9_]+");
Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression.
This expression uses the RE2 regular expression syntax.
<b>Signature:</b>
export declare function regexFindAll(stringExpression: Expression, pattern: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to search. |
| pattern | Expression | The regular expression to search for. |
<b>Returns:</b>
A new FunctionExpression that evaluates to an array of matched substrings.
// Extract all matches based on a dynamic pattern expression
regexFindAll(field("comment"), field("pattern"));
Creates an expression that checks if a string expression matches a specified regular expression.
<b>Signature:</b>
export declare function regexMatch(stringExpression: Expression, pattern: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to match against. |
| 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
regexMatch(field("email"), "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");
Creates an expression that checks if a string expression matches a specified regular expression.
<b>Signature:</b>
export declare function regexMatch(stringExpression: Expression, pattern: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to match against. |
| 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 valid email pattern
regexMatch(field("email"), field("pattern"));
Creates an expression that reverses a string.
<b>Signature:</b>
export declare function reverse(stringExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | An expression evaluating to a string value, which will be reversed. |
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
reverse(field("myString"));
Creates an expression that checks if a string expression starts with a given prefix.
<b>Signature:</b>
export declare function startsWith(stringExpression: Expression, prefix: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression to check. |
| prefix | string | The prefix to check for. |
<b>Returns:</b>
A new Expression representing the 'starts with' comparison.
// Check if the result of concatenating 'firstName' and 'lastName' fields starts with "Mr."
startsWith(field("fullName"), "Mr.");
Creates an expression that checks if a string expression starts with a given prefix.
<b>Signature:</b>
export declare function startsWith(stringExpression: Expression, prefix: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression to check. |
| prefix | Expression | The prefix to check for. |
<b>Returns:</b>
A new Expression representing the 'starts with' comparison.
// Check if the result of concatenating 'firstName' and 'lastName' fields starts with "Mr."
startsWith(field("fullName"), field("prefix"));
Creates an expression that checks if a string expression contains a specified substring.
<b>Signature:</b>
export declare function stringContains(stringExpression: Expression, substring: string): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| substring | string | The substring to search for. |
<b>Returns:</b>
A new Expression representing the 'contains' comparison.
// Check if the 'description' field contains "example".
stringContains(field("description"), "example");
Creates an expression that checks if a string expression contains a substring specified by another expression.
<b>Signature:</b>
export declare function stringContains(stringExpression: Expression, substring: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to perform the comparison on. |
| substring | 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.
stringContains(field("description"), field("keyword"));
Creates an expression that reverses a string.
<b>Signature:</b>
export declare function stringReverse(stringExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | An expression evaluating to a string value, which will be reversed. |
<b>Returns:</b>
A new Expression representing the reversed string.
// Reverse the value of the 'myString' field.
stringReverse(field("myString"));
Creates an expression that converts a string expression to lowercase.
<b>Signature:</b>
export declare function toLower(stringExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to convert to lowercase. |
<b>Returns:</b>
A new Expression representing the lowercase string.
// Convert the 'name' field to lowercase
toLower(field("name"));
Creates an expression that converts a string expression to uppercase.
<b>Signature:</b>
export declare function toUpper(stringExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string to convert to uppercase. |
<b>Returns:</b>
A new Expression representing the uppercase string.
// Convert the 'title' field to uppercase
toUpper(field("title"));
Creates an expression that removes leading and trailing characters from a string or byte array expression.
<b>Signature:</b>
export declare function trim(stringExpression: Expression, valueToTrim?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| stringExpression | Expression | The expression representing the string or byte array to trim. |
| valueToTrim | string | Expression | 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
trim(field("userInput"));
// Trim quotes from the 'userInput' field
trim(field("userInput"), '"');
Creates an expression that adds a specified amount of time to a timestamp.
<b>Signature:</b>
export declare function timestampAdd(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestamp | Expression | The expression representing the timestamp. |
| 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.
timestampAdd(field("timestamp"), field("unit"), field("amount"));
Creates an expression that adds a specified amount of time to a timestamp.
<b>Signature:</b>
export declare function timestampAdd(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestamp | Expression | The expression representing the timestamp. |
| 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.
timestampAdd(field("timestamp"), "day", 1);
Creates an expression that subtracts a specified amount of time from a timestamp.
<b>Signature:</b>
export declare function timestampSubtract(timestamp: Expression, unit: Expression, amount: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestamp | Expression | The expression representing the timestamp. |
| 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.
timestampSubtract(field("timestamp"), field("unit"), field("amount"));
Creates an expression that subtracts a specified amount of time from a timestamp.
<b>Signature:</b>
export declare function timestampSubtract(timestamp: Expression, unit: TimeUnit, amount: number): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestamp | Expression | The expression representing the timestamp. |
| 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.
timestampSubtract(field("timestamp"), "day", 1);
Creates an expression that extracts a specified part from a timestamp.
<b>Signature:</b>
export declare function timestampExtract(timestampExpression: Expression, part: TimePart, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestampExpression | Expression | The expression evaluating to the timestamp. |
| 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 timestamp returned by the expression.
timestampExtract(field('createdAt'), 'year')
Creates an expression that extracts a specified part from a timestamp.
<b>Signature:</b>
export declare function timestampExtract(timestampExpression: Expression, part: Expression, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestampExpression | Expression | The expression evaluating to the timestamp. |
| 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 'part' from the timestamp.
timestampExtract(field('createdAt'), field('part'))
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
export declare function timestampTruncate(timestampExpression: Expression, granularity: TimeGranularity, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestampExpression | Expression | Truncate the timestamp value that is returned by this expression. |
| 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.
timestampTruncate(field('createdAt'), 'day')
Creates an expression that truncates a timestamp to a specified granularity.
<b>Signature:</b>
export declare function timestampTruncate(timestampExpression: Expression, granularity: Expression, timezone?: string | Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| timestampExpression | Expression | Truncate the timestamp value that is returned by this expression. |
| 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'.
timestampTruncate(field('createdAt'), field('granularity'))
Creates an expression that returns the catch argument if there is an error, else return the result of the try argument evaluation.
This overload is useful when a BooleanExpression is required.
<b>Signature:</b>
export declare function ifError(tryExpr: BooleanExpression, catchExpr: BooleanExpression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| tryExpr | BooleanExpression | The try expression. |
| catchExpr | BooleanExpression | The catch expression that will be evaluated and returned if the tryExpr produces an error. |
<b>Returns:</b>
A new Expression representing the 'ifError' operation.
// Create an expression that protects against a divide by zero error
// but always returns a boolean expression.
ifError(constant(50).divide(field('length')).greaterThan(1), constant(false));
Creates an expression that returns the catch argument if there is an error, else return the result of the try argument evaluation.
<b>Signature:</b>
export declare function ifError(tryExpr: Expression, catchExpr: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| tryExpr | Expression | The try expression. |
| catchExpr | Expression | The catch expression that will be evaluated and returned if the tryExpr 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.
ifError(field("title").arrayGet(0), field("title"));
Creates an expression that returns the catch argument if there is an error, else return the result of the try argument evaluation.
<b>Signature:</b>
export declare function ifError(tryExpr: Expression, catchValue: unknown): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| tryExpr | Expression | The try expression. |
| catchValue | unknown | The value that will be returned if the tryExpr 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"
ifError(field("title").arrayGet(0), "Default Title");
Creates a Constant instance for a number value.
<b>Signature:</b>
export declare function constant(value: number): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | number | The number value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a VectorValue value.
<b>Signature:</b>
export declare function constant(value: VectorValue): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | VectorValue | The VectorValue value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a string value.
<b>Signature:</b>
export declare function constant(value: string): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | string | The string value. |
<b>Returns:</b>
A new Constant instance.
Creates a BooleanExpression instance for a boolean value.
<b>Signature:</b>
export declare function constant(value: boolean): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | boolean | The boolean value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a null value.
<b>Signature:</b>
export declare function constant(value: null): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | null | The null value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a GeoPoint value.
<b>Signature:</b>
export declare function constant(value: GeoPoint): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | GeoPoint | The GeoPoint value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a Timestamp value.
<b>Signature:</b>
export declare function constant(value: Timestamp): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | Timestamp | The Timestamp value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a Date value.
<b>Signature:</b>
export declare function constant(value: Date): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | Date | The Date value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a Bytes value.
<b>Signature:</b>
export declare function constant(value: Bytes): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | Bytes | The Bytes value. |
<b>Returns:</b>
A new Constant instance.
Creates a Constant instance for a DocumentReference value.
<b>Signature:</b>
export declare function constant(value: DocumentReference): Expression;
| Parameter | Type | Description |
|---|---|---|
| value | DocumentReference | The DocumentReference value. |
<b>Returns:</b>
A new Constant instance.
Creates an expression that checks if a field exists.
<b>Signature:</b>
export declare function exists(value: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | Expression | An expression evaluates to the name of the field to check. |
<b>Returns:</b>
A new Expression representing the 'exists' check.
// Check if the document has a field named "phoneNumber"
exists(field("phoneNumber"));
Creates an expression that returns true if a value is absent. Otherwise, returns false even if the value is null<!-- -->.
<b>Signature:</b>
export declare function isAbsent(value: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | Expression | The expression to check. |
<b>Returns:</b>
A new Expression representing the 'isAbsent' check.
// Check if the field `value` is absent.
isAbsent(field("value"));
Creates an expression that checks if a given expression produces an error.
<b>Signature:</b>
export declare function isError(value: Expression): BooleanExpression;
| Parameter | Type | Description |
|---|---|---|
| value | Expression | The expression to check. |
<b>Returns:</b>
A new Expression representing the 'isError' check.
// Check if the result of a calculation is an error
isError(field("title").arrayContains(1));
Calculates the Cosine distance between a vector expression and a vector literal.
<b>Signature:</b>
export declare function cosineDistance(vectorExpression: Expression, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to compare against. |
| vector | number[] | VectorValue | The other vector (as an array of doubles or 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
cosineDistance(field("location"), [37.7749, -122.4194]);
Calculates the Cosine distance between two vector expressions.
<b>Signature:</b>
export declare function cosineDistance(vectorExpression: Expression, otherVectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to compare against. |
| otherVectorExpression | Expression | The other vector (represented as an <code>Expression</code>) 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
cosineDistance(field("userVector"), field("itemVector"));
Calculates the dot product between a vector expression and a double array.
<b>Signature:</b>
export declare function dotProduct(vectorExpression: Expression, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to calculate with. |
| vector | number[] | VectorValue | The other vector (as an array of doubles or VectorValue) 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
dotProduct(field("features"), [0.5, 0.8, 0.2]);
Calculates the dot product between two vector expressions.
<b>Signature:</b>
export declare function dotProduct(vectorExpression: Expression, otherVectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to calculate with. |
| otherVectorExpression | Expression | The other vector (represented as an <code>Expression</code>) to calculate with. |
<b>Returns:</b>
A new Expression representing the dot product between the two vectors.
// Calculate the dot product between two document vectors: 'docVector1' and 'docVector2'
dotProduct(field("docVector1"), field("docVector2"));
Calculates the Euclidean distance between a vector expression and a double array.
<b>Signature:</b>
export declare function euclideanDistance(vectorExpression: Expression, vector: number[] | VectorValue): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to compare against. |
| vector | number[] | VectorValue | The other vector (as an array of doubles or 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
euclideanDistance(field("location"), [37.7749, -122.4194]);
Calculates the Euclidean distance between two vector expressions.
<b>Signature:</b>
export declare function euclideanDistance(vectorExpression: Expression, otherVectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The first vector (represented as an <code>Expression</code>) to compare against. |
| otherVectorExpression | Expression | The other vector (represented as an <code>Expression</code>) to compare against. |
<b>Returns:</b>
A new Expression representing the Euclidean distance between the two vectors.
// Calculate the Euclidean distance between two vector fields: 'pointA' and 'pointB'
euclideanDistance(field("pointA"), field("pointB"));
Creates an expression that calculates the length of a Firestore Vector.
<b>Signature:</b>
export declare function vectorLength(vectorExpression: Expression): FunctionExpression;
| Parameter | Type | Description |
|---|---|---|
| vectorExpression | Expression | The expression representing the Firestore Vector. |
<b>Returns:</b>
A new Expression representing the length of the array.
// Get the vector length (dimension) of the field 'embedding'.
vectorLength(field("embedding"));
Options defining how an AddFieldsStage is evaluated. See Pipeline.addFields()<!-- -->.
<b>Signature:</b>
export declare type AddFieldsStageOptions = StageOptions & {
fields: Selectable[];
};
Options defining how an AggregateStage is evaluated. See Pipeline.aggregate()<!-- -->.
<b>Signature:</b>
export declare type AggregateStageOptions = StageOptions & {
accumulators: AliasedAggregate[];
groups?: Array<string | Selectable>;
};
Defines the configuration options for a CollectionGroupStage within a pipeline. This type extends StageOptions and provides specific settings for how a collection group is identified and processed during pipeline execution.
See PipelineSource.collectionGroup() to create a collection group stage.
<b>Signature:</b>
export declare type CollectionGroupStageOptions = StageOptions & {
collectionId: string;
forceIndex?: string;
};
Options defining how a CollectionStage is evaluated. See PipelineSource.collection()<!-- -->.
<b>Signature:</b>
export declare type CollectionStageOptions = StageOptions & {
collection: string | Query;
forceIndex?: string;
};
Options defining how a DatabaseStage is evaluated. See PipelineSource.database()<!-- -->.
<b>Signature:</b>
export declare type DatabaseStageOptions = StageOptions & {};
Options defining how a DefineStage is evaluated. See Pipeline.define()<!-- -->.
<b>Signature:</b>
export declare type DefineStageOptions = StageOptions & {
variables: AliasedExpression[];
};
Options defining how a DistinctStage is evaluated. See Pipeline.distinct()<!-- -->.
<b>Signature:</b>
export declare type DistinctStageOptions = StageOptions & {
groups: Array<string | Selectable>;
};
Options defining how a DocumentsStage is evaluated. See PipelineSource.documents()<!-- -->.
<b>Signature:</b>
export declare type DocumentsStageOptions = StageOptions & {
docs: Array<string | DocumentReference>;
};
An enumeration of the different types of expressions.
<b>Signature:</b>
export declare type ExpressionType = 'Field' | 'Constant' | 'Function' | 'AggregateFunction' | 'ListOfExpressions' | 'AliasedExpression' | 'Variable' | 'PipelineValue';
Options defining how a FindNearestStage is evaluated. See Pipeline.findNearest()<!-- -->.
<b>Signature:</b>
export declare type FindNearestStageOptions = StageOptions & {
field: Field | string;
vectorValue: VectorValue | number[];
distanceMeasure: 'euclidean' | 'cosine' | 'dot_product';
limit?: number;
distanceField?: string;
};
Options defining how a LimitStage is evaluated. See Pipeline.limit()<!-- -->.
<b>Signature:</b>
export declare type LimitStageOptions = StageOptions & {
limit: number;
};
Options defining how an OffsetStage is evaluated. See Pipeline.offset()<!-- -->.
<b>Signature:</b>
export declare type OffsetStageOptions = StageOptions & {
offset: number;
};
Utility type to create an type that only allows one property of the Type param T to be set.
<b>Signature:</b>
export declare type OneOf<T> = {
[K in keyof T]: Pick<T, K> & {
[P in Exclude<keyof T, K>]?: undefined;
};
}[keyof T];
type XorY = OneOf<{ x: unknown, y: unknown }>
let a = { x: "foo" } // OK
let b = { y: "foo" } // OK
let c = { a: "foo", y: "foo" } // Not OK
Similar to TypeScript's Partial<T><!-- -->, but allows nested fields to be omitted and FieldValues to be passed in as property values.
<b>Signature:</b>
export declare type PartialWithFieldValue<T> = Partial<T> | (T extends Primitive ? T : T extends {} ? {
[K in keyof T]?: PartialWithFieldValue<T[K]> | FieldValue;
} : never);
Primitive types.
<b>Signature:</b>
export declare type Primitive = string | number | boolean | undefined | null;
Options defining how a RemoveFieldsStage is evaluated. See Pipeline.removeFields()<!-- -->.
<b>Signature:</b>
export declare type RemoveFieldsStageOptions = StageOptions & {
fields: Array<Field | string>;
};
Options defining how a ReplaceWithStage is evaluated. See Pipeline.replaceWith()<!-- -->.
<b>Signature:</b>
export declare type ReplaceWithStageOptions = StageOptions & {
map: Expression | string;
};
Defines the options for evaluating a sample stage within a pipeline. This type combines common StageOptions with a specific configuration where only one of the defined sampling methods can be applied.
See Pipeline.sample() to create a sample stage..
<b>Signature:</b>
export declare type SampleStageOptions = StageOptions & OneOf<{
percentage: number;
documents: number;
}>;
This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
Options defining how a SearchStage is evaluated. See .
<b>Signature:</b>
export declare type SearchStageOptions = StageOptions & {
query: BooleanExpression | string;
sort?: Ordering | Ordering[];
addFields?: Selectable[];
};
Options defining how a SelectStage is evaluated. See Pipeline.select()<!-- -->.
<b>Signature:</b>
export declare type SelectStageOptions = StageOptions & {
selections: Array<Selectable | string>;
};
An options object that configures the behavior of setDoc()<!-- -->, and calls. These calls can be configured to perform granular merges instead of overwriting the target documents in their entirety by providing a SetOptions with merge: true<!-- -->.
<b>Signature:</b>
export declare type SetOptions = {
readonly merge?: boolean;
} | {
readonly mergeFields?: Array<string | FieldPath>;
};
Options defining how a SortStage is evaluated. See Pipeline.sort()<!-- -->.
<b>Signature:</b>
export declare type SortStageOptions = StageOptions & {
orderings: Ordering[];
};
Options defining how a Stage is evaluated.
<b>Signature:</b>
export declare type StageOptions = {
rawOptions?: {
[name: string]: unknown;
};
};
Options defining how a SubcollectionStage is evaluated.
<b>Signature:</b>
export declare type SubcollectionStageOptions = StageOptions & {
path: string;
};
Specify time granularity for expressions.
<b>Signature:</b>
export declare type TimeGranularity = TimeUnit | 'week' | 'week(monday)' | 'week(tuesday)' | 'week(wednesday)' | 'week(thursday)' | 'week(friday)' | 'week(saturday)' | 'week(sunday)' | 'isoweek' | 'month' | 'quarter' | 'year' | 'isoyear';
Specify time parts for timestampExtract expressions.
<b>Signature:</b>
export declare type TimePart = TimeGranularity | 'dayofweek' | 'dayofyear';
Specify time units for expressions.
<b>Signature:</b>
export declare type TimeUnit = 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
Options defining how a UnionStage is evaluated. See Pipeline.union()<!-- -->.
<b>Signature:</b>
export declare type UnionStageOptions = StageOptions & {
other: Pipeline;
};
Represents the specific options available for configuring an UnnestStage within a pipeline.
<b>Signature:</b>
export declare type UnnestStageOptions = StageOptions & {
selectable: Selectable;
indexField?: string;
};
Options defining how a WhereStage is evaluated. See Pipeline.where()<!-- -->.
<b>Signature:</b>
export declare type WhereStageOptions = StageOptions & {
condition: BooleanExpression;
};
Allows FieldValues to be passed in as a property value while maintaining type safety.
<b>Signature:</b>
export declare type WithFieldValue<T> = T | (T extends Primitive ? T : T extends {} ? {
[K in keyof T]: WithFieldValue<T[K]> | FieldValue;
} : never);