@firebase/firestore
Version:
The Cloud Firestore component of the Firebase JS SDK.
1,365 lines • 349 kB
TypeScript
import type { Bytes, DocumentData, DocumentReference, FieldPath, FieldValue, Firestore, FirestoreDataConverter, GeoPoint, PartialWithFieldValue, Primitive, Query, QueryDocumentSnapshot, SetOptions, Timestamp, VectorValue, WithFieldValue } from './index';
/**
* Firestore Lite Pipelines
*
* @remarks Firestore Lite is a small online-only SDK that allows read
* and write access to your Firestore database. All operations connect
* directly to the backend, and `onSnapshot()` APIs are not supported.
* @packageDocumentation
*/
import { DocumentData as DocumentData_2 } from '@firebase/firestore-types';
import { EmulatorMockTokenOptions } from '@firebase/util';
import { FirebaseApp } from '@firebase/app';
import { FirebaseError } from '@firebase/util';
import { SetOptions as SetOptions_2 } from '@firebase/firestore-types';
/**
* @beta
* Creates an expression that computes the absolute value of a numeric value.
*
* @param expr - The expression to compute the absolute value of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the absolute value of the numeric value.
*/
export declare function abs(expr: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that computes the absolute value of a numeric value.
*
* @param fieldName - The field to compute the absolute value of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the absolute value of the numeric value.
*/
export declare function abs(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that adds two expressions together.
*
* @example
* ```typescript
* // Add the value of the 'quantity' field and the 'reserve' field.
* add(field("quantity"), field("reserve"));
* ```
*
* @param first - The first expression to add.
* @param second - The second expression or literal to add.
* @param others - Optional other expressions or literals to add.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the addition operation.
*/
export declare function add(first: Expression, second: Expression | unknown): FunctionExpression;
/**
* @beta
*
* Creates an expression that adds a field's value to an expression.
*
* @example
* ```typescript
* // Add the value of the 'quantity' field and the 'reserve' field.
* add("quantity", field("reserve"));
* ```
*
* @param fieldName - The name of the field containing the value to add.
* @param second - The second expression or literal to add.
* @param others - Optional other expressions or literals to add.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the addition operation.
*/
export declare function add(fieldName: string, second: Expression | unknown): FunctionExpression;
/**
* @beta
* Options defining how an AddFieldsStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(addFields:1)}.
*/
export declare type AddFieldsStageOptions = StageOptions & {
/**
* @beta
* The fields to add to each document, specified as a {@link @firebase/firestore/pipelines#Selectable}.
* At least one field is required.
*/
fields: Selectable[];
};
/**
* @beta
*
* A class that represents an aggregate function.
*/
export declare class AggregateFunction {
private name;
private params;
exprType: ExpressionType;
/* Excluded from this release type: _methodName */
constructor(name: string, params: Expression[]);
/* Excluded from this release type: _create */
/**
* @beta
* Assigns an alias to this AggregateFunction. The alias specifies the name that
* the aggregated value will have in the output document.
*
* @example
* ```typescript
* // Calculate the average price of all items and assign it the alias "averagePrice".
* firestore.pipeline().collection("items")
* .aggregate(field("price").average().as("averagePrice"));
* ```
*
* @param name - The alias to assign to this AggregateFunction.
* @returns A new {@link @firebase/firestore/pipelines#AliasedAggregate} that wraps this
* AggregateFunction and associates it with the provided alias.
*/
as(name: string): AliasedAggregate;
}
/**
* @beta
* Options defining how an AggregateStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(aggregate:1)}.
*/
export declare type AggregateStageOptions = StageOptions & {
/**
* @beta
* The {@link @firebase/firestore/pipelines#AliasedAggregate} values specifying aggregate operations to
* perform on the input documents.
*/
accumulators: AliasedAggregate[];
/**
* @beta
* The {@link @firebase/firestore/pipelines#Selectable} expressions or field names to consider when determining
* distinct value combinations (groups), which will be aggregated over.
*/
groups?: Array<string | Selectable>;
};
/**
* @beta
*
* An AggregateFunction with alias.
*/
export declare class AliasedAggregate {
readonly aggregate: AggregateFunction;
readonly alias: string;
constructor(aggregate: AggregateFunction, alias: string, _methodName: string | undefined);
}
/**
* @beta
*/
export declare class AliasedExpression implements Selectable {
readonly expr: Expression;
readonly alias: string;
exprType: ExpressionType;
selectable: true;
constructor(expr: Expression, alias: string, _methodName: string | undefined);
}
/**
* @beta
*
* Creates an expression that performs a logical 'AND' operation on multiple filter conditions.
*
* @example
* ```typescript
* // 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"));
* ```
*
* @param first - The first filter condition.
* @param second - The second filter condition.
* @param more - Additional filter conditions to 'AND' together.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the logical 'AND' operation.
*/
export declare function and(first: BooleanExpression, second: BooleanExpression, ...more: BooleanExpression[]): BooleanExpression;
/**
* @beta
*
* Creates an expression that creates a Firestore array value from an input array.
*
* @example
* ```typescript
* // Create an array value from the input array and reference the 'baz' field value from the input document.
* array(['bar', field('baz')]).as('foo');
* ```
*
* @param elements - The input array to evaluate in the expression.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the array function.
*/
export declare function array(elements: unknown[]): FunctionExpression;
/**
* @beta
* Creates an aggregation that collects all values of an expression across multiple stage
* inputs into an array.
*
* @remarks
* 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.
*
* @example
* ```typescript
* // Collect all tags from books into an array
* arrayAgg(field("tags")).as("allTags");
* ```
*
* @param expression - The expression to collect values from.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'array_agg' aggregation.
*/
export declare function arrayAgg(expression: Expression): AggregateFunction;
/**
* @beta
* Creates an aggregation that collects all values of a field across multiple stage inputs
* into an array.
*
* @remarks
* 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.
*
* @example
* ```typescript
* // Collect all tags from books into an array
* arrayAgg("tags").as("allTags");
* ```
*
* @param fieldName - The name of the field to collect values from.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'array_agg' aggregation.
*/
export declare function arrayAgg(fieldName: string): AggregateFunction;
/**
* @beta
* Creates an aggregation that collects all distinct values of an expression across multiple stage
* inputs into an array.
*
* @remarks
* 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.
*
* @example
* ```typescript
* // Collect all distinct tags from books into an array
* arrayAggDistinct(field("tags")).as("allDistinctTags");
* ```
*
* @param expression - The expression to collect values from.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'array_agg_distinct' aggregation.
*/
export declare function arrayAggDistinct(expression: Expression): AggregateFunction;
/**
* @beta
* Creates an aggregation that collects all distinct values of a field across multiple stage inputs
* into an array.
*
* @remarks
* 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.
*
* @example
* ```typescript
* // Collect all distinct tags from books into an array
* arrayAggDistinct("tags").as("allDistinctTags");
* ```
*
* @param fieldName - The name of the field to collect values from.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'array_agg_distinct' aggregation.
*/
export declare function arrayAggDistinct(fieldName: string): AggregateFunction;
/**
* @beta
*
* Creates an expression that concatenates an array expression with other arrays.
*
* @example
* ```typescript
* // Combine the 'items' array with two new item arrays
* arrayConcat(field("items"), [field("newItems"), field("otherItems")]);
* ```
*
* @param firstArray - The first array expression to concatenate to.
* @param secondArray - The second array expression or array literal to concatenate to.
* @param otherArrays - Optional additional array expressions or array literals to concatenate.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the concatenated array.
*/
export declare function arrayConcat(firstArray: Expression, secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
/**
* @beta
*
* Creates an expression that concatenates a field's array value with other arrays.
*
* @example
* ```typescript
* // Combine the 'items' array with two new item arrays
* arrayConcat("items", [field("newItems"), field("otherItems")]);
* ```
*
* @param firstArrayField - The first array to concatenate to.
* @param secondArray - The second array expression or array literal to concatenate to.
* @param otherArrays - Optional additional array expressions or array literals to concatenate.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the concatenated array.
*/
export declare function arrayConcat(firstArrayField: string, secondArray: Expression | unknown[], ...otherArrays: Array<Expression | unknown[]>): FunctionExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains a specific element.
*
* @example
* ```typescript
* // Check if the 'colors' array contains the value of field 'selectedColor'
* arrayContains(field("colors"), field("selectedColor"));
* ```
*
* @param array - The array expression to check.
* @param element - The element to search for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains' comparison.
*/
export declare function arrayContains(array: Expression, element: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains a specific element.
*
* @example
* ```typescript
* // Check if the 'colors' array contains "red"
* arrayContains(field("colors"), "red");
* ```
*
* @param array - The array expression to check.
* @param element - The element to search for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains' comparison.
*/
export declare function arrayContains(array: Expression, element: unknown): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value contains a specific element.
*
* @example
* ```typescript
* // Check if the 'colors' array contains the value of field 'selectedColor'
* arrayContains("colors", field("selectedColor"));
* ```
*
* @param fieldName - The field name to check.
* @param element - The element to search for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains' comparison.
*/
export declare function arrayContains(fieldName: string, element: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value contains a specific value.
*
* @example
* ```typescript
* // Check if the 'colors' array contains "red"
* arrayContains("colors", "red");
* ```
*
* @param fieldName - The field name to check.
* @param element - The element to search for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains' comparison.
*/
export declare function arrayContains(fieldName: string, element: unknown): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains all the specified elements.
*
* @example
* ```typescript
* // 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"]);
* ```
*
* @param array - The array expression to check.
* @param values - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_all' comparison.
*/
export declare function arrayContainsAll(array: Expression, values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value contains all the specified values or
* expressions.
*
* @example
* ```typescript
* // Check if the 'tags' array contains both of the values from field 'tag1', the value "SciFi", and "Adventure"
* arrayContainsAll("tags", [field("tag1"), "SciFi", "Adventure"]);
* ```
*
* @param fieldName - The field name to check.
* @param values - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_all' comparison.
*/
export declare function arrayContainsAll(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains all the specified elements.
*
* @example
* ```typescript
* // 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"]);
* ```
*
* @param array - The array expression to check.
* @param arrayExpression - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_all' comparison.
*/
export declare function arrayContainsAll(array: Expression, arrayExpression: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value contains all the specified values or
* expressions.
*
* @example
* ```typescript
* // Check if the 'tags' array contains both of the values from field 'tag1', the value "SciFi", and "Adventure"
* arrayContainsAll("tags", [field("tag1"), "SciFi", "Adventure"]);
* ```
*
* @param fieldName - The field name to check.
* @param arrayExpression - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_all' comparison.
*/
export declare function arrayContainsAll(fieldName: string, arrayExpression: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains any of the specified
* elements.
*
* @example
* ```typescript
* // Check if the 'categories' array contains either values from field "cate1" or "Science"
* arrayContainsAny(field("categories"), [field("cate1"), "Science"]);
* ```
*
* @param array - The array expression to check.
* @param values - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_any' comparison.
*/
export declare function arrayContainsAny(array: Expression, values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value 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"
* arrayContainsAny("categories", [field("cate1"), "Science"]);
* ```
*
* @param fieldName - The field name to check.
* @param values - The elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_any' comparison.
*/
export declare function arrayContainsAny(fieldName: string, values: Array<Expression | unknown>): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if an array expression contains any of the specified
* elements.
*
* @example
* ```typescript
* // Check if the 'categories' array contains either values from field "cate1" or "Science"
* arrayContainsAny(field("categories"), array([field("cate1"), "Science"]));
* ```
*
* @param array - The array expression to check.
* @param values - An expression that evaluates to an array, whose elements to check for in the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_any' comparison.
*/
export declare function arrayContainsAny(array: Expression, values: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that checks if a field's array value 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"
* arrayContainsAny("categories", array([field("cate1"), "Science"]));
* ```
*
* @param fieldName - The field name to check.
* @param values - An expression that evaluates to an array, whose elements to check for in the array field.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'array_contains_any' comparison.
*/
export declare function arrayContainsAny(fieldName: string, values: Expression): BooleanExpression;
/**
* @beta
*
* Creates an expression that returns the first element of an array.
*
* @example
* ```typescript
* // Get the first tag from the 'tags' array field
* arrayFirst("tags");
* ```
*
* @param fieldName - The name of the field containing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first element.
*/
export declare function arrayFirst(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first element of an array.
*
* @example
* ```typescript
* // Get the first tag from the 'tags' array field
* arrayFirst(field("tags"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first element.
*/
export declare function arrayFirst(arrayExpression: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first `n` elements of an array.
*
* @example
* ```typescript
* // Get the first 3 tags from the 'tags' array field
* arrayFirstN("tags", 3);
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first `n` elements.
*/
export declare function arrayFirstN(fieldName: string, n: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first `n` elements of an array.
*
* @example
* ```typescript
* // Get the first n tags from the 'tags' array field
* arrayFirstN("tags", field("count"));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first `n` elements.
*/
export declare function arrayFirstN(fieldName: string, n: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first `n` elements of an array.
*
* @example
* ```typescript
* // Get the first 3 elements from an array expression
* arrayFirstN(field("tags"), 3);
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first `n` elements.
*/
export declare function arrayFirstN(arrayExpression: Expression, n: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first `n` elements of an array.
*
* @example
* ```typescript
* // Get the first n elements from an array expression
* arrayFirstN(field("tags"), field("count"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the first `n` elements.
*/
export declare function arrayFirstN(arrayExpression: Expression, n: Expression): FunctionExpression;
/**
* @beta
* 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.
*
* @example
* ```typescript
* // Return the value in the tags field array at index 1.
* arrayGet('tags', 1);
* ```
*
* @param arrayField - The name of the array field.
* @param offset - The index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
export declare function arrayGet(arrayField: string, offset: number): FunctionExpression;
/**
* @beta
* 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.
*
* @example
* ```typescript
* // Return the value in the tags field array at index specified by field
* // 'favoriteTag'.
* arrayGet('tags', field('favoriteTag'));
* ```
*
* @param arrayField - The name of the array field.
* @param offsetExpr - An `Expression` evaluating to the index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
export declare function arrayGet(arrayField: string, offsetExpr: Expression): FunctionExpression;
/**
* @beta
* 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.
*
* @example
* ```typescript
* // Return the value in the tags field array at index 1.
* arrayGet(field('tags'), 1);
* ```
*
* @param arrayExpression - An `Expression` evaluating to an array.
* @param offset - The index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
export declare function arrayGet(arrayExpression: Expression, offset: number): FunctionExpression;
/**
* @beta
* 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.
*
* @example
* ```typescript
* // Return the value in the tags field array at index specified by field
* // 'favoriteTag'.
* arrayGet(field('tags'), field('favoriteTag'));
* ```
*
* @param arrayExpression - An `Expression` evaluating to an array.
* @param offsetExpr - An `Expression` evaluating to the index of the element to return.
* @returns A new `Expression` representing the 'arrayGet' operation.
*/
export declare function arrayGet(arrayExpression: Expression, offsetExpr: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first index of the search value in an array.
* Returns -1 if the value is not found.
*
* @example
* ```typescript
* // Get the index of "politics" in the 'tags' array field
* arrayIndexOf("tags", "politics");
* ```
*
* @param fieldName - The name of the field containing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the index.
*/
export declare function arrayIndexOf(fieldName: string, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the first index of the search value in an array.
* Returns -1 if the value is not found.
*
* @example
* ```typescript
* // Get the index of "politics" in the 'tags' array field
* arrayIndexOf(field("tags"), "politics");
* ```
*
* @param arrayExpression - The expression representing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the index.
*/
export declare function arrayIndexOf(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns all indices of the search value in an array.
*
* @example
* ```typescript
* // Get all indices of 5 in the 'scores' array field
* arrayIndexOfAll("scores", 5);
* ```
*
* @param fieldName - The name of the field containing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the indices.
*/
export declare function arrayIndexOfAll(fieldName: string, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns all indices of the search value in an array.
*
* @example
* ```typescript
* // Get all indices of 5 in the 'scores' array field
* arrayIndexOfAll(field("scores"), 5);
* ```
*
* @param arrayExpression - The expression representing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the indices.
*/
export declare function arrayIndexOfAll(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last element of an array.
*
* @example
* ```typescript
* // Get the last tag from the 'tags' array field
* arrayLast("tags");
* ```
*
* @param fieldName - The name of the field containing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last element.
*/
export declare function arrayLast(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last element of an array.
*
* @example
* ```typescript
* // Get the last tag from the 'tags' array field
* arrayLast(field("tags"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last element.
*/
export declare function arrayLast(arrayExpression: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last index of the search value in an array.
* Returns -1 if the value is not found.
*
* @example
* ```typescript
* // Get the last index of "politics" in the 'tags' array field
* arrayLastIndexOf("tags", "politics");
* ```
*
* @param fieldName - The name of the field containing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the index.
*/
export declare function arrayLastIndexOf(fieldName: string, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last index of the search value in an array.
* Returns -1 if the value is not found.
*
* @example
* ```typescript
* // Get the last index of "politics" in the 'tags' array field
* arrayLastIndexOf(field("tags"), "politics");
* ```
*
* @param arrayExpression - The expression representing the array to search.
* @param search - The value to search for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the index.
*/
export declare function arrayLastIndexOf(arrayExpression: Expression, search: unknown | Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last `n` elements of an array.
*
* @example
* ```typescript
* // Get the last 3 tags from the 'tags' array field
* arrayLastN("tags", 3);
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last `n` elements.
*/
export declare function arrayLastN(fieldName: string, n: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last `n` elements of an array.
*
* @example
* ```typescript
* // Get the last n tags from the 'tags' array field
* arrayLastN("tags", field("count"));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last `n` elements.
*/
export declare function arrayLastN(fieldName: string, n: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last `n` elements of an array.
*
* @example
* ```typescript
* // Get the last 3 elements from an array expression
* arrayLastN(field("tags"), 3);
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last `n` elements.
*/
export declare function arrayLastN(arrayExpression: Expression, n: number): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the last `n` elements of an array.
*
* @example
* ```typescript
* // Get the last n elements from an array expression
* arrayLastN(field("tags"), field("count"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the last `n` elements.
*/
export declare function arrayLastN(arrayExpression: Expression, n: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that calculates the length of an array in a specified field.
*
* @example
* ```typescript
* // Get the number of items in field 'cart'
* arrayLength('cart');
* ```
*
* @param fieldName - The name of the field containing an array to calculate the length of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the array.
*/
export declare function arrayLength(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that calculates the length of an array expression.
*
* @example
* ```typescript
* // Get the number of items in the 'cart' array
* arrayLength(field("cart"));
* ```
*
* @param array - The array expression to calculate the length of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the array.
*/
export declare function arrayLength(array: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the maximum value in an array.
*
* @example
* ```typescript
* // Get the maximum value from the 'scores' array field
* arrayMaximum("scores");
* ```
*
* @param fieldName - The name of the field containing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the maximum value.
*/
export declare function arrayMaximum(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the maximum value in an array.
*
* @example
* ```typescript
* // Get the maximum value from the 'scores' array field
* arrayMaximum(field("scores"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the maximum value.
*/
export declare function arrayMaximum(arrayExpression: Expression): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the top 3 scores from the 'scores' array field
* arrayMaximumN("scores", 3);
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the largest `n` elements.
*/
export declare function arrayMaximumN(fieldName: string, n: number): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the top n scores from the 'scores' array field
* arrayMaximumN("scores", field("count"));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the largest `n` elements.
*/
export declare function arrayMaximumN(fieldName: string, n: Expression): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the top 3 elements from an array expression
* arrayMaximumN(field("scores"), 3);
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the largest `n` elements.
*/
export declare function arrayMaximumN(arrayExpression: Expression, n: number): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the top n elements from an array expression
* arrayMaximumN(field("scores"), field("count"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the largest `n` elements.
*/
export declare function arrayMaximumN(arrayExpression: Expression, n: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the minimum value in an array.
*
* @example
* ```typescript
* // Get the minimum value from the 'scores' array field
* arrayMinimum("scores");
* ```
*
* @param fieldName - The name of the field containing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the minimum value.
*/
export declare function arrayMinimum(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the minimum value in an array.
*
* @example
* ```typescript
* // Get the minimum value from the 'scores' array field
* arrayMinimum(field("scores"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the minimum value.
*/
export declare function arrayMinimum(arrayExpression: Expression): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the bottom 3 scores from the 'scores' array field
* arrayMinimumN("scores", 3);
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the smallest `n` elements.
*/
export declare function arrayMinimumN(fieldName: string, n: number): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the bottom n scores from the 'scores' array field
* arrayMinimumN(field("scores"), field("count"));
* ```
*
* @param fieldName - The name of the field containing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the smallest `n` elements.
*/
export declare function arrayMinimumN(fieldName: string, n: Expression): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the bottom 3 scores from the 'scores' array field
* arrayMinimumN(field("scores"), 3);
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - The number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the smallest `n` elements.
*/
export declare function arrayMinimumN(arrayExpression: Expression, n: number): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Get the bottom n scores from the 'scores' array field
* arrayMinimumN(field("scores"), field("count"));
* ```
*
* @param arrayExpression - The expression representing the array.
* @param n - An expression evaluating to the number of elements to return.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the smallest `n` elements.
*/
export declare function arrayMinimumN(arrayExpression: Expression, n: Expression): FunctionExpression;
/**
* @beta
* Creates an expression that computes the sum of the elements in an array.
*
* @example
* ```typescript
* // Compute the sum of the elements in the 'scores' field.
* arraySum("scores");
* ```
*
* @param fieldName - The name of the field to compute the sum of.
* @returns A new `Expression` representing the sum of the elements in the array.
*/
export declare function arraySum(fieldName: string): FunctionExpression;
/**
* @beta
* Creates an expression that computes the sum of the elements in an array.
*
* @example
* ```typescript
* // Compute the sum of the elements in the 'scores' field.
* arraySum(field("scores"));
* ```
*
* @param expression - An expression evaluating to a numeric array, which the sum will be computed for.
* @returns A new `Expression` representing the sum of the elements in the array.
*/
export declare function arraySum(expression: Expression): FunctionExpression;
/**
* @beta
*
* Creates an {@link @firebase/firestore/pipelines#Ordering} that sorts documents in ascending order based on an expression.
*
* @example
* ```typescript
* // Sort documents by the 'name' field in lowercase in ascending order
* firestore.pipeline().collection("users")
* .sort(ascending(field("name").toLower()));
* ```
*
* @param expr - The expression to create an ascending ordering for.
* @returns A new `Ordering` for ascending sorting.
*/
export declare function ascending(expr: Expression): Ordering;
/**
* @beta
*
* Creates an {@link @firebase/firestore/pipelines#Ordering} that sorts documents in ascending order based on a field.
*
* @example
* ```typescript
* // Sort documents by the 'name' field in ascending order
* firestore.pipeline().collection("users")
* .sort(ascending("name"));
* ```
*
* @param fieldName - The field to create an ascending ordering for.
* @returns A new `Ordering` for ascending sorting.
*/
export declare function ascending(fieldName: string): Ordering;
/* Excluded from this release type: AuthTokenFactory */
/**
* @beta
*
* Creates an aggregation that calculates the average (mean) of values from an expression across
* multiple stage inputs.
*
* @example
* ```typescript
* // Calculate the average age of users
* average(field("age")).as("averageAge");
* ```
*
* @param expression - The expression representing the values to average.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'average' aggregation.
*/
export declare function average(expression: Expression): AggregateFunction;
/**
* @beta
*
* Creates an aggregation that calculates the average (mean) of a field's values across multiple
* stage inputs.
*
* @example
* ```typescript
* // Calculate the average age of users
* average("age").as("averageAge");
* ```
*
* @param fieldName - The name of the field containing numeric values to average.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'average' aggregation.
*/
export declare function average(fieldName: string): AggregateFunction;
/**
* @beta
*
* An interface that represents a filter condition.
*/
export declare abstract class BooleanExpression extends Expression {
/**
* @beta
* Creates an aggregation that finds the count of input documents satisfying
* this boolean expression.
*
* @example
* ```typescript
* // Find the count of documents with a score greater than 90
* field("score").greaterThan(90).countIf().as("highestScore");
* ```
*
* @returns A new `AggregateFunction` representing the 'countIf' aggregation.
*/
countIf(): AggregateFunction;
/**
* @beta
* Creates an expression that negates this boolean expression.
*
* @example
* ```typescript
* // Find documents where the 'tags' field does not contain 'completed'
* field("tags").arrayContains("completed").not();
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the negated filter condition.
*/
not(): BooleanExpression;
/**
* @beta
* Creates a conditional expression that evaluates to the 'then' expression
* if `this` expression evaluates to `true`,
* or evaluates to the 'else' expression if `this` expressions evaluates `false`.
*
* @example
* ```typescript
* // If 'age' is greater than 18, return "Adult"; otherwise, return "Minor".
* field("age").greaterThanOrEqual(18).conditional(constant("Adult"), constant("Minor"));
* ```
*
* @param thenExpr - The expression to evaluate if the condition is true.
* @param elseExpr - The expression to evaluate if the condition is false.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the conditional expression.
*/
conditional(thenExpr: Expression, elseExpr: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the `catch` argument if there is an
* error, else return the result of this expression.
*
* @example
* ```typescript
* // Create an expression that protects against a divide by zero error
* // but always returns a boolean expression.
* constant(50).divide(field('length')).greaterThan(1).ifError(constant(false));
* ```
*
* @param catchValue - The value that will be returned if this expression
* produces an error.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'ifError' operation.
*/
ifError(catchValue: BooleanExpression): BooleanExpression;
/**
* @beta
*
* Creates an expression that returns the `catch` argument if there is an
* error, else return the result of this expression.
*
* @example
* ```typescript
* // Create an expression that protects against a divide by zero error
* // but always returns a boolean expression.
* constant(50).divide(field('length')).greaterThan(1).ifError(false);
* ```
*
* @param catchValue - The value that will be returned if this expression
* produces an error.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'ifError' operation.
*/
ifError(catchValue: boolean): BooleanExpression;
/**
* @beta
*
* Creates an expression that returns the `catch` argument if there is an
* error, else return the result of this expression.
*
* @example
* ```typescript
* // Create an expression that protects against a divide by zero error.
* constant(50).divide(field('length')).greaterThan(1).ifError(constant(0));
* ```
*
* @param catchValue - The value that will be returned if this expression
* produces an error.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'ifError' operation.
*/
ifError(catchValue: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the `catch` argument if there is an
* error, else return the result of this expression.
*
* @example
* ```typescript
* // Create an expression that protects against a divide by zero error.
* constant(50).divide(field('length')).greaterThan(1).ifError(0);
* ```
*
* @param catchValue - The value that will be returned if this expression
* produces an error.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the 'ifError' operation.
*/
ifError(catchValue: unknown): FunctionExpression;
}
/**
* @beta
*
* Creates an expression that calculates the byte length of a string in UTF-8, or just the length of a Blob.
*
* @example
* ```typescript
* // Calculate the length of the 'myString' field in bytes.
* byteLength(field("myString"));
* ```
*
* @param expr - The expression representing the string.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the string in bytes.
*/
export declare function byteLength(expr: Expression): FunctionExpression;
/**
* @beta
*
* 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.
*
* @example
* ```typescript
* // Calculate the length of the 'myString' field in bytes.
* byteLength("myString");
* ```
*
* @param fieldName - The name of the field containing the string.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the string in bytes.
*/
export declare function byteLength(fieldName: string): FunctionExpression;
/* Excluded from this release type: ByteString */
/**
* @beta
* Creates an expression that computes the ceiling of a numeric value.
*
* @example
* ```typescript
* // Compute the ceiling of the 'price' field.
* ceil("price");
* ```
*
* @param fieldName - The name of the field to compute the ceiling of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the ceiling of the numeric value.
*/
export declare function ceil(fieldName: string): FunctionExpression;
/**
* @beta
* Creates an expression that computes the ceiling of a numeric value.
*
* @example
* ```typescript
* // Compute the ceiling of the 'price' field.
* ceil(field("price"));
* ```
*
* @param express