@firebase/firestore
Version:
The Cloud Firestore component of the Firebase JS SDK.
1,345 lines • 227 kB
TypeScript
/**
* @license
* Copyright 2024 Google LLC
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
import { ParseContext } from '../api/parse_context';
import { FieldPath as InternalFieldPath } from '../model/path';
import { Value as ProtoValue } from '../protos/firestore_proto_api';
import { JsonProtoSerializer, ProtoValueSerializable } from '../remote/serializer';
import { Bytes } from './bytes';
import { FieldPath } from './field_path';
import { GeoPoint } from './geo_point';
import { DocumentReference } from './reference';
import { Timestamp } from './timestamp';
import { UserData } from './user_data_reader';
import { VectorValue } from './vector_value';
/**
* @beta
*
* An enumeration of the different types of expressions.
*/
export type ExpressionType = 'Field' | 'Constant' | 'Function' | 'AggregateFunction' | 'ListOfExpressions' | 'AliasedExpression';
/**
* @beta
*
* Represents an expression that can be evaluated to a value within the execution of a {@link
* @firebase/firestore/pipelines#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 `Expression` class provides a fluent API for building expressions. You can chain together
* method calls to create complex expressions.
*/
export declare abstract class Expression implements ProtoValueSerializable, UserData {
abstract readonly expressionType: ExpressionType;
abstract readonly _methodName?: string;
/**
* @private
* @internal
*/
abstract _toProto(serializer: JsonProtoSerializer): ProtoValue;
_protoValueType: "ProtoValue";
/**
* @private
* @internal
*/
abstract _readUserData(context: ParseContext): void;
/**
* Creates an expression that adds this expression to another expression.
*
* @example
* ```typescript
* // Add the value of the 'quantity' field and the 'reserve' field.
* field("quantity").add(field("reserve"));
* ```
*
* @param second - The expression or literal to add to this expression.
* @param others - Optional additional expressions or literals to add to this expression.
* @returns A new `Expression` representing the addition operation.
*/
add(second: Expression | unknown): FunctionExpression;
/**
* @beta
* Wraps the expression in a [BooleanExpression].
*
* @returns A [BooleanExpression] representing the same expression.
*/
asBoolean(): BooleanExpression;
/**
* @beta
* Creates an expression that subtracts another expression from this expression.
*
* @example
* ```typescript
* // Subtract the 'discount' field from the 'price' field
* field("price").subtract(field("discount"));
* ```
*
* @param subtrahend - The expression to subtract from this expression.
* @returns A new `Expression` representing the subtraction operation.
*/
subtract(subtrahend: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that subtracts a constant value from this expression.
*
* @example
* ```typescript
* // Subtract 20 from the value of the 'total' field
* field("total").subtract(20);
* ```
*
* @param subtrahend - The constant value to subtract.
* @returns A new `Expression` representing the subtraction operation.
*/
subtract(subtrahend: number): FunctionExpression;
/**
* @beta
* Creates an expression that multiplies this expression by another expression.
*
* @example
* ```typescript
* // Multiply the 'quantity' field by the 'price' field
* field("quantity").multiply(field("price"));
* ```
*
* @param second - The second expression or literal to multiply by.
* @param others - Optional additional expressions or literals to multiply by.
* @returns A new `Expression` representing the multiplication operation.
*/
multiply(second: Expression | number): FunctionExpression;
/**
* @beta
* Creates an expression that divides this expression by another expression.
*
* @example
* ```typescript
* // Divide the 'total' field by the 'count' field
* field("total").divide(field("count"));
* ```
*
* @param divisor - The expression to divide by.
* @returns A new `Expression` representing the division operation.
*/
divide(divisor: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that divides this expression by a constant value.
*
* @example
* ```typescript
* // Divide the 'value' field by 10
* field("value").divide(10);
* ```
*
* @param divisor - The constant value to divide by.
* @returns A new `Expression` representing the division operation.
*/
divide(divisor: number): FunctionExpression;
/**
* @beta
* Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression.
*
* @example
* ```typescript
* // Calculate the remainder of dividing the 'value' field by the 'divisor' field
* field("value").mod(field("divisor"));
* ```
*
* @param expression - The expression to divide by.
* @returns A new `Expression` representing the modulo operation.
*/
mod(expression: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that calculates the modulo (remainder) of dividing this expression by a constant value.
*
* @example
* ```typescript
* // Calculate the remainder of dividing the 'value' field by 10
* field("value").mod(10);
* ```
*
* @param value - The constant value to divide by.
* @returns A new `Expression` representing the modulo operation.
*/
mod(value: number): FunctionExpression;
/**
* @beta
* Creates an expression that checks if this expression is equal to another expression.
*
* @example
* ```typescript
* // Check if the 'age' field is equal to 21
* field("age").equal(21);
* ```
*
* @param expression - The expression to compare for equality.
* @returns A new `Expression` representing the equality comparison.
*/
equal(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is equal to a constant value.
*
* @example
* ```typescript
* // Check if the 'city' field is equal to "London"
* field("city").equal("London");
* ```
*
* @param value - The constant value to compare for equality.
* @returns A new `Expression` representing the equality comparison.
*/
equal(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is not equal to another expression.
*
* @example
* ```typescript
* // Check if the 'status' field is not equal to "completed"
* field("status").notEqual("completed");
* ```
*
* @param expression - The expression to compare for inequality.
* @returns A new `Expression` representing the inequality comparison.
*/
notEqual(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is not equal to a constant value.
*
* @example
* ```typescript
* // Check if the 'country' field is not equal to "USA"
* field("country").notEqual("USA");
* ```
*
* @param value - The constant value to compare for inequality.
* @returns A new `Expression` representing the inequality comparison.
*/
notEqual(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is less than another expression.
*
* @example
* ```typescript
* // Check if the 'age' field is less than 'limit'
* field("age").lessThan(field('limit'));
* ```
*
* @param experession - The expression to compare for less than.
* @returns A new `Expression` representing the less than comparison.
*/
lessThan(experession: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is less than a constant value.
*
* @example
* ```typescript
* // Check if the 'price' field is less than 50
* field("price").lessThan(50);
* ```
*
* @param value - The constant value to compare for less than.
* @returns A new `Expression` representing the less than comparison.
*/
lessThan(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is less than or equal to another
* expression.
*
* @example
* ```typescript
* // Check if the 'quantity' field is less than or equal to 20
* field("quantity").lessThan(constant(20));
* ```
*
* @param expression - The expression to compare for less than or equal to.
* @returns A new `Expression` representing the less than or equal to comparison.
*/
lessThanOrEqual(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is less than or equal to a constant value.
*
* @example
* ```typescript
* // Check if the 'score' field is less than or equal to 70
* field("score").lessThan(70);
* ```
*
* @param value - The constant value to compare for less than or equal to.
* @returns A new `Expression` representing the less than or equal to comparison.
*/
lessThanOrEqual(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is greater than another expression.
*
* @example
* ```typescript
* // Check if the 'age' field is greater than the 'limit' field
* field("age").greaterThan(field("limit"));
* ```
*
* @param expression - The expression to compare for greater than.
* @returns A new `Expression` representing the greater than comparison.
*/
greaterThan(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is greater than a constant value.
*
* @example
* ```typescript
* // Check if the 'price' field is greater than 100
* field("price").greaterThan(100);
* ```
*
* @param value - The constant value to compare for greater than.
* @returns A new `Expression` representing the greater than comparison.
*/
greaterThan(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is greater than or equal to another
* expression.
*
* @example
* ```typescript
* // Check if the 'quantity' field is greater than or equal to field 'requirement' plus 1
* field("quantity").greaterThanOrEqual(field('requirement').add(1));
* ```
*
* @param expression - The expression to compare for greater than or equal to.
* @returns A new `Expression` representing the greater than or equal to comparison.
*/
greaterThanOrEqual(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is greater than or equal to a constant
* value.
*
* @example
* ```typescript
* // Check if the 'score' field is greater than or equal to 80
* field("score").greaterThanOrEqual(80);
* ```
*
* @param value - The constant value to compare for greater than or equal to.
* @returns A new `Expression` representing the greater than or equal to comparison.
*/
greaterThanOrEqual(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that concatenates an array expression with one or more other arrays.
*
* @example
* ```typescript
* // Combine the 'items' array with another array field.
* field("items").arrayConcat(field("otherItems"));
* ```
* @param secondArray - Second array expression or array literal to concatenate.
* @param otherArrays - Optional additional array expressions or array literals to concatenate.
* @returns A new `Expression` representing the concatenated array.
*/
arrayConcat(secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
/**
* @beta
* Creates an expression that checks if an array contains a specific element.
*
* @example
* ```typescript
* // Check if the 'sizes' array contains the value from the 'selectedSize' field
* field("sizes").arrayContains(field("selectedSize"));
* ```
*
* @param expression - The element to search for in the array.
* @returns A new `Expression` representing the 'array_contains' comparison.
*/
arrayContains(expression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if an array contains a specific value.
*
* @example
* ```typescript
* // Check if the 'colors' array contains "red"
* field("colors").arrayContains("red");
* ```
*
* @param value - The element to search for in the array.
* @returns A new `Expression` representing the 'array_contains' comparison.
*/
arrayContains(value: unknown): BooleanExpression;
/**
* @beta
* Creates an expression that checks if an array contains all the specified elements.
*
* @example
* ```typescript
* // Check if the 'tags' array contains both the value in field "tag1" and the literal value "tag2"
* field("tags").arrayContainsAll([field("tag1"), "tag2"]);
* ```
*
* @param values - The elements to check for in the array.
* @returns A new `Expression` representing the 'array_contains_all' comparison.
*/
arrayContainsAll(values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
* Creates an expression that checks if an array contains all the specified elements.
*
* @example
* ```typescript
* // Check if the 'tags' array contains both of the values from field "tag1" and the literal value "tag2"
* field("tags").arrayContainsAll(array([field("tag1"), "tag2"]));
* ```
*
* @param arrayExpression - The elements to check for in the array.
* @returns A new `Expression` representing the 'array_contains_all' comparison.
*/
arrayContainsAll(arrayExpression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if an array contains any of the specified elements.
*
* @example
* ```typescript
* // Check if the 'categories' array contains either values from field "cate1" or "cate2"
* field("categories").arrayContainsAny([field("cate1"), field("cate2")]);
* ```
*
* @param values - The elements to check for in the array.
* @returns A new `Expression` representing the 'array_contains_any' comparison.
*/
arrayContainsAny(values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
* Creates an expression that checks if an array contains any of the specified elements.
*
* @example
* ```typescript
* // Check if the 'groups' array contains either the value from the 'userGroup' field
* // or the value "guest"
* field("groups").arrayContainsAny(array([field("userGroup"), "guest"]));
* ```
*
* @param arrayExpression - The elements to check for in the array.
* @returns A new `Expression` representing the 'array_contains_any' comparison.
*/
arrayContainsAny(arrayExpression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that reverses an array.
*
* @example
* ```typescript
* // Reverse the value of the 'myArray' field.
* field("myArray").arrayReverse();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the reversed array.
*/
arrayReverse(): FunctionExpression;
/**
* @beta
* Creates an expression that calculates the length of an array.
*
* @example
* ```typescript
* // Get the number of items in the 'cart' array
* field("cart").arrayLength();
* ```
*
* @returns A new `Expression` representing the length of the array.
*/
arrayLength(): FunctionExpression;
/**
* @beta
* Creates an expression that checks if this expression is equal to any of the provided values or
* expressions.
*
* @example
* ```typescript
* // Check if the 'category' field is either "Electronics" or value of field 'primaryType'
* field("category").equalAny("Electronics", field("primaryType"));
* ```
*
* @param values - The values or expressions to check against.
* @returns A new `Expression` representing the 'IN' comparison.
*/
equalAny(values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is equal to any of the provided values or
* expressions.
*
* @example
* ```typescript
* // Check if the 'category' field is either "Electronics" or value of field 'primaryType'
* field("category").equalAny(array(["Electronics", field("primaryType")]));
* ```
*
* @param arrayExpression - An expression that evaluates to an array of values to check against.
* @returns A new `Expression` representing the 'IN' comparison.
*/
equalAny(arrayExpression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is not equal to any of the provided values or
* expressions.
*
* @example
* ```typescript
* // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
* field("status").notEqualAny(["pending", field("rejectedStatus")]);
* ```
*
* @param values - The values or expressions to check against.
* @returns A new `Expression` representing the 'notEqualAny' comparison.
*/
notEqualAny(values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
* Creates an expression that checks if this expression is not equal to any of the values in the evaluated expression.
*
* @example
* ```typescript
* // Check if the 'status' field is not equal to any value in the field 'rejectedStatuses'
* field("status").notEqualAny(field('rejectedStatuses'));
* ```
*
* @param arrayExpression - The values or expressions to check against.
* @returns A new `Expression` representing the 'notEqualAny' comparison.
*/
notEqualAny(arrayExpression: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a field exists in the document.
*
* @example
* ```typescript
* // Check if the document has a field named "phoneNumber"
* field("phoneNumber").exists();
* ```
*
* @returns A new `Expression` representing the 'exists' check.
*/
exists(): BooleanExpression;
/**
* @beta
* Creates an expression that calculates the character length of a string in UTF-8.
*
* @example
* ```typescript
* // Get the character length of the 'name' field in its UTF-8 form.
* field("name").charLength();
* ```
*
* @returns A new `Expression` representing the length of the string.
*/
charLength(): FunctionExpression;
/**
* @beta
* Creates an expression that performs a case-sensitive string comparison.
*
* @example
* ```typescript
* // Check if the 'title' field contains the word "guide" (case-sensitive)
* field("title").like("%guide%");
* ```
*
* @param pattern - The pattern to search for. You can use "%" as a wildcard character.
* @returns A new `Expression` representing the 'like' comparison.
*/
like(pattern: string): BooleanExpression;
/**
* @beta
* Creates an expression that performs a case-sensitive string comparison.
*
* @example
* ```typescript
* // Check if the 'title' field contains the word "guide" (case-sensitive)
* field("title").like("%guide%");
* ```
*
* @param pattern - The pattern to search for. You can use "%" as a wildcard character.
* @returns A new `Expression` representing the 'like' comparison.
*/
like(pattern: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string contains a specified regular expression as a
* substring.
*
* @example
* ```typescript
* // Check if the 'description' field contains "example" (case-insensitive)
* field("description").regexContains("(?i)example");
* ```
*
* @param pattern - The regular expression to use for the search.
* @returns A new `Expression` representing the 'contains' comparison.
*/
regexContains(pattern: string): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string contains a specified regular expression as a
* substring.
*
* @example
* ```typescript
* // Check if the 'description' field contains the regular expression stored in field 'regex'
* field("description").regexContains(field("regex"));
* ```
*
* @param pattern - The regular expression to use for the search.
* @returns A new `Expression` representing the 'contains' comparison.
*/
regexContains(pattern: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string matches a specified regular expression.
*
* @example
* ```typescript
* // Check if the 'email' field matches a valid email pattern
* field("email").regexMatch("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");
* ```
*
* @param pattern - The regular expression to use for the match.
* @returns A new `Expression` representing the regular expression match.
*/
regexMatch(pattern: string): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string matches a specified regular expression.
*
* @example
* ```typescript
* // Check if the 'email' field matches a regular expression stored in field 'regex'
* field("email").regexMatch(field("regex"));
* ```
*
* @param pattern - The regular expression to use for the match.
* @returns A new `Expression` representing the regular expression match.
*/
regexMatch(pattern: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string contains a specified substring.
*
* @example
* ```typescript
* // Check if the 'description' field contains "example".
* field("description").stringContains("example");
* ```
*
* @param substring - The substring to search for.
* @returns A new `Expression` representing the 'contains' comparison.
*/
stringContains(substring: string): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string contains the string represented by another expression.
*
* @example
* ```typescript
* // Check if the 'description' field contains the value of the 'keyword' field.
* field("description").stringContains(field("keyword"));
* ```
*
* @param expr - The expression representing the substring to search for.
* @returns A new `Expression` representing the 'contains' comparison.
*/
stringContains(expr: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string starts with a given prefix.
*
* @example
* ```typescript
* // Check if the 'name' field starts with "Mr."
* field("name").startsWith("Mr.");
* ```
*
* @param prefix - The prefix to check for.
* @returns A new `Expression` representing the 'starts with' comparison.
*/
startsWith(prefix: string): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string starts with a given prefix (represented as an
* expression).
*
* @example
* ```typescript
* // Check if the 'fullName' field starts with the value of the 'firstName' field
* field("fullName").startsWith(field("firstName"));
* ```
*
* @param prefix - The prefix expression to check for.
* @returns A new `Expression` representing the 'starts with' comparison.
*/
startsWith(prefix: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string ends with a given postfix.
*
* @example
* ```typescript
* // Check if the 'filename' field ends with ".txt"
* field("filename").endsWith(".txt");
* ```
*
* @param suffix - The postfix to check for.
* @returns A new `Expression` representing the 'ends with' comparison.
*/
endsWith(suffix: string): BooleanExpression;
/**
* @beta
* Creates an expression that checks if a string ends with a given postfix (represented as an
* expression).
*
* @example
* ```typescript
* // Check if the 'url' field ends with the value of the 'extension' field
* field("url").endsWith(field("extension"));
* ```
*
* @param suffix - The postfix expression to check for.
* @returns A new `Expression` representing the 'ends with' comparison.
*/
endsWith(suffix: Expression): BooleanExpression;
/**
* @beta
* Creates an expression that converts a string to lowercase.
*
* @example
* ```typescript
* // Convert the 'name' field to lowercase
* field("name").toLower();
* ```
*
* @returns A new `Expression` representing the lowercase string.
*/
toLower(): FunctionExpression;
/**
* @beta
* Creates an expression that converts a string to uppercase.
*
* @example
* ```typescript
* // Convert the 'title' field to uppercase
* field("title").toUpper();
* ```
*
* @returns A new `Expression` representing the uppercase string.
*/
toUpper(): FunctionExpression;
/**
* @beta
* Creates an expression that removes leading and trailing characters from a string or byte array.
*
* @example
* ```typescript
* // Trim whitespace from the 'userInput' field
* field("userInput").trim();
*
* // Trim quotes from the 'userInput' field
* field("userInput").trim('"');
* ```
* @param valueToTrim - Optional This parameter is treated as a set of characters or bytes that will be
* trimmed from the input. If not specified, then whitespace will be trimmed.
* @returns A new `Expression` representing the trimmed string or byte array.
*/
trim(valueToTrim?: string | Expression | Bytes): FunctionExpression;
/**
* @beta
* Creates an expression that concatenates string expressions together.
*
* @example
* ```typescript
* // Combine the 'firstName', " ", and 'lastName' fields into a single string
* field("firstName").stringConcat(constant(" "), field("lastName"));
* ```
*
* @param secondString - The additional expression or string literal to concatenate.
* @param otherStrings - Optional additional expressions or string literals to concatenate.
* @returns A new `Expression` representing the concatenated string.
*/
stringConcat(secondString: Expression | string, ...otherStrings: Array<Expression | string>): FunctionExpression;
/**
* @beta
* Creates an expression that concatenates expression results together.
*
* @example
* ```typescript
* // Combine the 'firstName', ' ', and 'lastName' fields into a single value.
* field("firstName").concat(constant(" "), field("lastName"));
* ```
*
* @param second - The additional expression or literal to concatenate.
* @param others - Optional additional expressions or literals to concatenate.
* @returns A new `Expression` representing the concatenated value.
*/
concat(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
/**
* @beta
* Creates an expression that reverses this string expression.
*
* @example
* ```typescript
* // Reverse the value of the 'myString' field.
* field("myString").reverse();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the reversed string.
*/
reverse(): FunctionExpression;
/**
* @beta
* Creates an expression that calculates the length of this string expression in bytes.
*
* @example
* ```typescript
* // Calculate the length of the 'myString' field in bytes.
* field("myString").byteLength();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the string in bytes.
*/
byteLength(): FunctionExpression;
/**
* @beta
* Creates an expression that computes the ceiling of a numeric value.
*
* @example
* ```typescript
* // Compute the ceiling of the 'price' field.
* field("price").ceil();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the ceiling of the numeric value.
*/
ceil(): FunctionExpression;
/**
* @beta
* Creates an expression that computes the floor of a numeric value.
*
* @example
* ```typescript
* // Compute the floor of the 'price' field.
* field("price").floor();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the floor of the numeric value.
*/
floor(): FunctionExpression;
/**
* @beta
* Creates an expression that computes the absolute value of a numeric value.
*
* @example
* ```typescript
* // Compute the absolute value of the 'price' field.
* field("price").abs();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the absolute value of the numeric value.
*/
abs(): FunctionExpression;
/**
* @beta
* Creates an expression that computes e to the power of this expression.
*
* @example
* ```typescript
* // Compute e to the power of the 'value' field.
* field("value").exp();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the exp of the numeric value.
*/
exp(): FunctionExpression;
/**
* @beta
* Accesses a value from a map (object) field using the provided key.
*
* @example
* ```typescript
* // Get the 'city' value from the 'address' map field
* field("address").mapGet("city");
* ```
*
* @param subfield - The key to access in the map.
* @returns A new `Expression` representing the value associated with the given key in the map.
*/
mapGet(subfield: string): FunctionExpression;
/**
* @beta
* Creates an aggregation that counts the number of stage inputs with valid evaluations of the
* expression or field.
*
* @example
* ```typescript
* // Count the total number of products
* field("productId").count().as("totalProducts");
* ```
*
* @returns A new `AggregateFunction` representing the 'count' aggregation.
*/
count(): AggregateFunction;
/**
* @beta
* Creates an aggregation that calculates the sum of a numeric field across multiple stage inputs.
*
* @example
* ```typescript
* // Calculate the total revenue from a set of orders
* field("orderAmount").sum().as("totalRevenue");
* ```
*
* @returns A new `AggregateFunction` representing the 'sum' aggregation.
*/
sum(): AggregateFunction;
/**
* @beta
* Creates an aggregation that calculates the average (mean) of a numeric field across multiple
* stage inputs.
*
* @example
* ```typescript
* // Calculate the average age of users
* field("age").average().as("averageAge");
* ```
*
* @returns A new `AggregateFunction` representing the 'average' aggregation.
*/
average(): AggregateFunction;
/**
* @beta
* Creates an aggregation that finds the minimum value of a field across multiple stage inputs.
*
* @example
* ```typescript
* // Find the lowest price of all products
* field("price").minimum().as("lowestPrice");
* ```
*
* @returns A new `AggregateFunction` representing the 'minimum' aggregation.
*/
minimum(): AggregateFunction;
/**
* @beta
* Creates an aggregation that finds the maximum value of a field across multiple stage inputs.
*
* @example
* ```typescript
* // Find the highest score in a leaderboard
* field("score").maximum().as("highestScore");
* ```
*
* @returns A new `AggregateFunction` representing the 'maximum' aggregation.
*/
maximum(): AggregateFunction;
/**
* @beta
* Creates an aggregation that counts the number of distinct values of the expression or field.
*
* @example
* ```typescript
* // Count the distinct number of products
* field("productId").countDistinct().as("distinctProducts");
* ```
*
* @returns A new `AggregateFunction` representing the 'count_distinct' aggregation.
*/
countDistinct(): AggregateFunction;
/**
* @beta
* Creates an expression that returns the larger value between this expression and another expression, based on Firestore's value type ordering.
*
* @example
* ```typescript
* // Returns the larger value between the 'timestamp' field and the current timestamp.
* field("timestamp").logicalMaximum(Function.currentTimestamp());
* ```
*
* @param second - The second expression or literal to compare with.
* @param others - Optional additional expressions or literals to compare with.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the logical maximum operation.
*/
logicalMaximum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
/**
* @beta
* Creates an expression that returns the smaller value between this expression and another expression, based on Firestore's value type ordering.
*
* @example
* ```typescript
* // Returns the smaller value between the 'timestamp' field and the current timestamp.
* field("timestamp").logicalMinimum(Function.currentTimestamp());
* ```
*
* @param second - The second expression or literal to compare with.
* @param others - Optional additional expressions or literals to compare with.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the logical minimum operation.
*/
logicalMinimum(second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
/**
* @beta
* Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression.
*
* @example
* ```typescript
* // Get the vector length (dimension) of the field 'embedding'.
* field("embedding").vectorLength();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the vector.
*/
vectorLength(): FunctionExpression;
/**
* @beta
* Calculates the cosine distance between two vectors.
*
* @example
* ```typescript
* // Calculate the cosine distance between the 'userVector' field and the 'itemVector' field
* field("userVector").cosineDistance(field("itemVector"));
* ```
*
* @param vectorExpression - The other vector (represented as an Expression) to compare against.
* @returns A new `Expression` representing the cosine distance between the two vectors.
*/
cosineDistance(vectorExpression: Expression): FunctionExpression;
/**
* @beta
* Calculates the Cosine distance between two vectors.
*
* @example
* ```typescript
* // Calculate the Cosine distance between the 'location' field and a target location
* field("location").cosineDistance(new VectorValue([37.7749, -122.4194]));
* ```
*
* @param vector - The other vector (as a VectorValue) to compare against.
* @returns A new `Expression` representing the Cosine* distance between the two vectors.
*/
cosineDistance(vector: VectorValue | number[]): FunctionExpression;
/**
* @beta
* Calculates the dot product between two vectors.
*
* @example
* ```typescript
* // Calculate the dot product between a feature vector and a target vector
* field("features").dotProduct([0.5, 0.8, 0.2]);
* ```
*
* @param vectorExpression - The other vector (as an array of numbers) to calculate with.
* @returns A new `Expression` representing the dot product between the two vectors.
*/
dotProduct(vectorExpression: Expression): FunctionExpression;
/**
* @beta
* Calculates the dot product between two vectors.
*
* @example
* ```typescript
* // Calculate the dot product between a feature vector and a target vector
* field("features").dotProduct(new VectorValue([0.5, 0.8, 0.2]));
* ```
*
* @param vector - The other vector (as an array of numbers) to calculate with.
* @returns A new `Expression` representing the dot product between the two vectors.
*/
dotProduct(vector: VectorValue | number[]): FunctionExpression;
/**
* @beta
* Calculates the Euclidean distance between two vectors.
*
* @example
* ```typescript
* // Calculate the Euclidean distance between the 'location' field and a target location
* field("location").euclideanDistance([37.7749, -122.4194]);
* ```
*
* @param vectorExpression - The other vector (as an array of numbers) to calculate with.
* @returns A new `Expression` representing the Euclidean distance between the two vectors.
*/
euclideanDistance(vectorExpression: Expression): FunctionExpression;
/**
* @beta
* Calculates the Euclidean distance between two vectors.
*
* @example
* ```typescript
* // Calculate the Euclidean distance between the 'location' field and a target location
* field("location").euclideanDistance(new VectorValue([37.7749, -122.4194]));
* ```
*
* @param vector - The other vector (as a VectorValue) to compare against.
* @returns A new `Expression` representing the Euclidean distance between the two vectors.
*/
euclideanDistance(vector: VectorValue | number[]): FunctionExpression;
/**
* @beta
* Creates an expression that interprets this expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
* and returns a timestamp.
*
* @example
* ```typescript
* // Interpret the 'microseconds' field as microseconds since epoch.
* field("microseconds").unixMicrosToTimestamp();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the timestamp.
*/
unixMicrosToTimestamp(): FunctionExpression;
/**
* @beta
* Creates an expression that converts this timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
*
* @example
* ```typescript
* // Convert the 'timestamp' field to microseconds since epoch.
* field("timestamp").timestampToUnixMicros();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the number of microseconds since epoch.
*/
timestampToUnixMicros(): FunctionExpression;
/**
* @beta
* Creates an expression that interprets this expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
* and returns a timestamp.
*
* @example
* ```typescript
* // Interpret the 'milliseconds' field as milliseconds since epoch.
* field("milliseconds").unixMillisToTimestamp();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the timestamp.
*/
unixMillisToTimestamp(): FunctionExpression;
/**
* @beta
* Creates an expression that converts this timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
*
* @example
* ```typescript
* // Convert the 'timestamp' field to milliseconds since epoch.
* field("timestamp").timestampToUnixMillis();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the number of milliseconds since epoch.
*/
timestampToUnixMillis(): FunctionExpression;
/**
* @beta
* Creates an expression that interprets this expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC)
* and returns a timestamp.
*
* @example
* ```typescript
* // Interpret the 'seconds' field as seconds since epoch.
* field("seconds").unixSecondsToTimestamp();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the timestamp.
*/
unixSecondsToTimestamp(): FunctionExpression;
/**
* @beta
* Creates an expression that converts this timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
*
* @example
* ```typescript
* // Convert the 'timestamp' field to seconds since epoch.
* field("timestamp").timestampToUnixSeconds();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the number of seconds since epoch.
*/
timestampToUnixSeconds(): FunctionExpression;
/**
* @beta
* Creates an expression that adds a specified amount of time to this timestamp expression.
*
* @example
* ```typescript
* // Add some duration determined by field 'unit' and 'amount' to the 'timestamp' field.
* field("timestamp").timestampAdd(field("unit"), field("amount"));
* ```
*
* @param unit - The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
* @param amount - The expression evaluates to amount of the unit.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the resulting timestamp.
*/
timestampAdd(unit: Expression, amount: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that adds a specified amount of time to this timestamp expression.
*
* @example
* ```typescript
* // Add 1 day to the 'timestamp' field.
* field("timestamp").timestampAdd("day", 1);
* ```
*
* @param unit - The unit of time to add (e.g., "day", "hour").
* @param amount - The amount of time to add.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the resulting timestamp.
*/
timestampAdd(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
/**
* @beta
* Creates an expression that subtracts a specified amount of time from this timestamp expression.
*
* @example
* ```typescript
* // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field.
* field("timestamp").timestampSubtract(field("unit"), field("amount"));
* ```
*
* @param unit - The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
* @param amount - The expression evaluates to amount of the unit.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the resulting timestamp.
*/
timestampSubtract(unit: Expression, amount: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that subtracts a specified amount of time from this timestamp expression.
*
* @example
* ```typescript
* // Subtract 1 day from the 'timestamp' field.
* field("timestamp").timestampSubtract("day", 1);
* ```
*
* @param unit - The unit of time to subtract (e.g., "day", "hour").
* @param amount - The amount of time to subtract.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the resulting timestamp.
*/
timestampSubtract(unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day', amount: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the document ID from a path.
*
* @example
* ```typescript
* // Get the document ID from a path.
* field("__path__").documentId();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the documentId operation.
*/
documentId(): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns a substring of the results of this expression.
*
* @param position - Index of the first character of the substring.
* @param length - Length of the substring. If not provided, the substring will
* end at the end of the input.
*/
substring(position: number, length?: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns a substring of the results of this expression.
*
* @param position - An expression returning the index of the first character of the substring.
* @param length - An expression returning the length of the substring. If not provided the
* substring will end at the end of the input.
*/
substring(position: Expression, length?: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that indexes into an array from the beginning or end
* and returns the element. If the offset exceeds the array length, an error is
* returned. A negative offset, starts from the end.
*
* @example
* ```typescript
* // Return the value in the 'tags' field array at index `1`.
* field('tags').arrayGet(1);
* ```
*
* @param offset - The index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
arrayGet(offset: number): FunctionExpression;
/**
* @beta
* Creates an expression that indexes into an array from the beginning or end
* and returns the element. If the offset exceeds the array length, an error is
* returned. A negative offset, starts from the end.
*
* @example
* ```typescript
* // Return the value in the tags field array at index specified by field
* // 'favoriteTag'.
* field('tags').arrayGet(field('favoriteTag'));
* ```
*
* @param offsetExpr - An `Expression` evaluating to the index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
arrayGet(offsetExpr: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that checks if a given expression produces an error.
*
* @example
* ```typescript
* // Check if the result of a calculation is an error
* field("title").arrayContains(1).isError();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#BooleanExpression} representing the 'isError' check.
*/
isError(): BooleanExpression;
/**
* @beta
*
* Creates an expression that returns the result of the `catchExpr` argument
* if there is an error, else return the result of this expression.
*
* @example
* ```typescript
* // Returns the first item in the title field arrays, or returns
* // the entire title field if the array is empty or the field is another type.
* field("title").arrayGet(0).ifError(field("title"));
* ```
*
* @param catchExpr - The catch expression that will be evaluated and
* returned if this expression