@firebase/firestore
Version:
The Cloud Firestore component of the Firebase JS SDK.
1,359 lines • 245 kB
TypeScript
import type { Bytes, DocumentData, DocumentReference, FieldPath, FieldValue, Firestore, FirestoreDataConverter, GeoPoint, PartialWithFieldValue, Primitive, Query, QueryDocumentSnapshot, SetOptions, SnapshotMetadata, SnapshotOptions, Timestamp, VectorValue, WithFieldValue } from './index';
/**
* Cloud Firestore
*
* @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.of('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 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 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 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 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('length').gt(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('length').gt(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('length').gt(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('length').gt(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 expression - An expression evaluating to a numeric value, which the ceiling will be computed for.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the ceiling of the numeric value.
*/
export declare function ceil(expression: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that calculates the character length of a string field in UTF8.
*
* @example
* ```typescript
* // Get the character length of the 'name' field in UTF-8.
* strLength("name");
* ```
*
* @param fieldName - The name of the field containing the string.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the string.
*/
export declare function charLength(fieldName: string): FunctionExpression;
/**
* @beta
*
* Creates an expression that calculates the character length of a string expression in UTF-8.
*
* @example
* ```typescript
* // Get the character length of the 'name' field in UTF-8.
* strLength(field("name"));
* ```
*
* @param stringExpression - The expression representing the string to calculate the length of.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the length of the string.
*/
export declare function charLength(stringExpression: Expression): FunctionExpression;
/**
* @beta
* Defines the configuration options for a CollectionGroupStage within a pipeline.
* This type extends {@link @firebase/firestore/pipelines#StageOptions} and provides specific settings for how a collection group
* is identified and processed during pipeline execution.
*
* See {@link @firebase/firestore/pipelines#PipelineSource.(collectionGroup:1)} to create a collection group stage.
*/
export declare type CollectionGroupStageOptions = StageOptions & {
/**
* @beta
* ID of the collection group to use as the Pipeline source.
*/
collectionId: string;
/**
* @beta
* Specifies the name of an index to be used for a query, overriding the query optimizer's default choice.
* This can be useful for performance tuning in specific scenarios where the default index selection
* does not yield optimal performance.
*
* @remarks This property is optional. When provided, it should be the exact name of the index to force.
*/
forceIndex?: string;
};
/**
* @beta
* Creates an expression that returns the collection ID from a path.
*
* @example
* ```typescript
* // Get the collection ID from a path.
* collectionId("__name__");
* ```
*
* @param fieldName - The name of the field to get the collection ID from.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the collectionId operation.
*/
export declare function collectionId(fieldName: string): FunctionExpression;
/**
* @beta
* Creates an expression that returns the collection ID from a path.
*
* @example
* ```typescript
* // Get the collection ID from a path.
* collectionId(field("__name__"));
* ```
*
* @param expression - An expression evaluating to a path, which the collection ID will be extracted from.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the collectionId operation.
*/
export declare function collectionId(expression: Expression): FunctionExpression;
/**
* @beta
* Options defining how a CollectionStage is evaluated. See {@link @firebase/firestore/pipelines#PipelineSource.(collection:1)}.
*/
export declare type CollectionStageOptions = StageOptions & {
/**
* @beta
* Name or reference to the collection that will be used as the Pipeline source.
*/
collection: string | Query;
/**
* @beta
* Specifies the name of an index to be used for a query, overriding the query optimizer's default choice.
* This can be useful for performance tuning in specific scenarios where the default index selection
* does not yield optimal performance.
*
* @remarks This property is optional. When provided, it should be the exact name of the index to force.
*/
forceIndex?: string;
};
/**
* @beta
* Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
*
* @example
* ```typescript
* // Concatenate the 'firstName' and 'lastName' fields with a space in between.
* concat(field("firstName"), " ", field("lastName"))
* ```
*
* @param first - The first expressions to concatenate.
* @param second - The second literal or expression to concatenate.
* @param others - Additional literals or expressions to concatenate.
* @returns A new `Expression` representing the concatenation.
*/
export declare function concat(first: Expression, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
/**
* @beta
* Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
*
* @example
* ```typescript
* // Concatenate a field with a literal string.
* concat(field("firstName"), "Doe")
* ```
*
* @param fieldName - The name of a field to concatenate.
* @param second - The second literal or expression to concatenate.
* @param others - Additional literal or expressions to concatenate.
* @returns A new `Expression` representing the concatenation.
*/
export declare function concat(fieldName: string, second: Expression | unknown, ...others: Array<Expression | unknown>): FunctionExpression;
/**
* @beta
*
* Creates a conditional expression that evaluates to a 'then' expression if a condition is true
* and an 'else' expression if the condition is false.
*
* @example
* ```typescript
* // If 'age' is greater than 18, return "Adult"; otherwise, return "Minor".
* conditional(
* greaterThan("age", 18), constant("Adult"), constant("Minor"));
* ```
*
* @param condition - The condition to evaluate.
* @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.
*/
export declare function conditional(condition: BooleanExpression, thenExpr: Expression, elseExpr: Expression): FunctionExpression;
/**
* @beta
* Creates a `Constant` instance for a number value.
*
* @param value - The number value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: number): Expression;
/**
* @beta
* Creates a `Constant` instance for a string value.
*
* @param value - The string value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: string): Expression;
/**
* @beta
* Creates a `BooleanExpression` instance for a boolean value.
*
* @param value - The boolean value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: boolean): BooleanExpression;
/**
* @beta
* Creates a `Constant` instance for a null value.
*
* @param value - The null value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: null): Expression;
/**
* @beta
* Creates a `Constant` instance for a GeoPoint value.
*
* @param value - The GeoPoint value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: GeoPoint): Expression;
/**
* @beta
* Creates a `Constant` instance for a Timestamp value.
*
* @param value - The Timestamp value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: Timestamp): Expression;
/**
* @beta
* Creates a `Constant` instance for a Date value.
*
* @param value - The Date value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: Date): Expression;
/**
* @beta
* Creates a `Constant` instance for a Bytes value.
*
* @param value - The Bytes value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: Bytes): Expression;
/**
* @beta
* Creates a `Constant` instance for a DocumentReference value.
*
* @param value - The DocumentReference value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: DocumentReference): Expression;
/* Excluded declaration from this release type: constant */
/**
* @beta
* Creates a `Constant` instance for a VectorValue value.
*
* @param value - The VectorValue value.
* @returns A new `Constant` instance.
*/
export declare function constant(value: VectorValue): Expression;
/**
* @beta
*
* Calculates the Cosine distance between a field's vector value and a literal vector value.
*
* @example
* ```typescript
* // Calculate the Cosine distance between the 'location' field and a target location
* cosineDistance("location", [37.7749, -122.4194]);
* ```
*
* @param fieldName - The name of the field containing the first vector.
* @param vector - The other vector (as an array of doubles) or {@link VectorValue} to compare against.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the Cosine distance between the two vectors.
*/
export declare function cosineDistance(fieldName: string, vector: number[] | VectorValue): FunctionExpression;
/**
* @beta
*
* Calculates the Cosine distance between a field's vector value and a vector expression.
*
* @example
* ```typescript
* // Calculate the cosine distance between the 'userVector' field and the 'itemVector' field
* cosineDistance("userVector", field("itemVector"));
* ```
*
* @param fieldName - The name of the field containing the first vector.
* @param vectorExpression - The other vector (represented as an `Expression`) to compare against.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the cosine distance between the two vectors.
*/
export declare function cosineDistance(fieldName: string, vectorExpression: Expression): FunctionExpression;
/**
* @beta
*
* Calculates the Cosine distance between a vector expression and a vector literal.
*
* @example
* ```typescript
* // Calculate the cosine distance between the 'location' field and a target location
* cosineDistance(field("location"), [37.7749, -122.4194]);
* ```
*
* @param vectorExpression - The first vector (represented as an `Expression`) to compare against.
* @param vector - The other vector (as an array of doubles or VectorValue) to compare against.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the cosine distance between the two vectors.
*/
export declare function cosineDistance(vectorExpression: Expression, vector: number[] | VectorValue): FunctionExpression;
/**
* @beta
*
* Calculates the Cosine distance between two vector expressions.
*
* @example
* ```typescript
* // Calculate the cosine distance between the 'userVector' field and the 'itemVector' field
* cosineDistance(field("userVector"), field("itemVector"));
* ```
*
* @param vectorExpression - The first vector (represented as an `Expression`) to compare against.
* @param otherVectorExpression - The other vector (represented as an `Expression`) to compare against.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the cosine distance between the two vectors.
*/
export declare function cosineDistance(vectorExpression: Expression, otherVectorExpression: Expression): FunctionExpression;
/**
* @beta
*
* Creates an aggregation that counts the number of stage inputs with valid evaluations of the
* provided expression.
*
* @example
* ```typescript
* // Count the number of items where the price is greater than 10
* count(field("price").greaterThan(10)).as("expensiveItemCount");
* ```
*
* @param expression - The expression to count.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'count' aggregation.
*/
export declare function count(expression: Expression): AggregateFunction;
/**
* @beta
* Creates an aggregation that counts the number of stage inputs where the input field exists.
*
* @example
* ```typescript
* // Count the total number of products
* count("productId").as("totalProducts");
* ```
*
* @param fieldName - The name of the field to count.
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'count' aggregation.
*/
export declare function count(fieldName: string): AggregateFunction;
/**
* @beta
*
* Creates an aggregation that counts the total number of stage inputs.
*
* @example
* ```typescript
* // Count the total number of input documents
* countAll().as("totalDocument");
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#AggregateFunction} representing the 'countAll' aggregation.
*/
export declare function countAll(): AggregateFunction;
/**
* @beta
* Creates an aggregation that counts the number of distinct values of a field.
*
* @param expr - The expression or field to count distinct values of.
* @returns A new `AggregateFunction` representing the 'count_distinct' aggregation.
*/
export declare function countDistinct(expr: Expression | string): AggregateFunction;
/**
* @beta
* Creates an aggregation that counts the number of stage inputs where the provided
* boolean expression evaluates to true.
*
* @example
* ```typescript
* // Count the number of documents where 'is_active' field equals true
* countIf(field("is_active").equal(true)).as("numActiveDocuments");
* ```
*
* @param booleanExpr - The boolean expression to evaluate on each input.
* @returns A new `AggregateFunction` representing the 'countIf' aggregation.
*/
export declare function countIf(booleanExpr: BooleanExpression): AggregateFunction;
/**
* @beta
*
* Creates an expression that evaluates to the current server timestamp.
*
* @example
* ```typescript
* // Get the current server timestamp
* currentTimestamp()
* ```
*
* @returns A new Expression representing the current server timestamp.
*/
export declare function currentTimestamp(): FunctionExpression;
/**
* @beta
* Options defining how a DatabaseStage is evaluated. See {@link @firebase/firestore/pipelines#PipelineSource.(database:1)}.
*/
export declare type DatabaseStageOptions = StageOptions & {};
/**
* @beta
*
* Creates an {@link @firebase/firestore/pipelines#Ordering} that sorts documents in descending order based on an expression.
*
* @example
* ```typescript
* // Sort documents by the 'name' field in lowercase in descending order
* firestore.pipeline().collection("users")
* .sort(descending(field("name").toLower()));
* ```
*
* @param expr - The expression to create a descending ordering for.
* @returns A new `Ordering` for descending sorting.
*/
export declare function descending(expr: Expression): Ordering;
/**
* @beta
*
* Creates an {@link @firebase/firestore/pipelines#Ordering} that sorts documents in descending order based on a field.
*
* @example
* ```typescript
* // Sort documents by the 'name' field in descending order
* firestore.pipeline().collection("users")
* .sort(descending("name"));
* ```
*
* @param fieldName - The field to create a descending ordering for.
* @returns A new `Ordering` for descending sorting.
*/
export declare function descending(fieldName: string): Ordering;
/**
* @beta
* Options defining how a DistinctStage is evaluated. See {@link @firebase/firestore/pipelines#Pipeline.(distinct:1)}.
*/
export declare type DistinctStageOptions = StageOptions & {
/**
* @beta
* The {@link @firebase/firestore/pipelines#Selectable} expressions or field names to consider when determining
* distinct value combinations (groups).
*/
groups: Array<string | Selectable>;
};
/**
* @beta
*
* Creates an expression that divides two expressions.
*
* @example
* ```typescript
* // Divide the 'total' field by the 'count' field
* divide(field("total"), field("count"));
* ```
*
* @param left - The expression to be divided.
* @param right - The expression to divide by.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the division operation.
*/
export declare function divide(left: Expression, right: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that divides an expression by a constant value.
*
* @example
* ```typescript
* // Divide the 'value' field by 10
* divide(field("value"), 10);
* ```
*
* @param expression - The expression to be divided.
* @param value - The constant value to divide by.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the division operation.
*/
export declare function divide(expression: Expression, value: unknown): FunctionExpression;
/**
* @beta
*
* Creates an expression that divides a field's value by an expression.
*
* @example
* ```typescript
* // Divide the 'total' field by the 'count' field
* divide("total", field("count"));
* ```
*
* @param fieldName - The field name to be divided.
* @param expressions - The expression to divide by.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the division operation.
*/
export declare function divide(fieldName: string, expressions: Expression): FunctionExpression;
/**
* @beta
*
* Creates an expression that divides a field's value by a constant value.
*
* @example
* ```typescript
* // Divide the 'value' field by 10
* divide("value", 10);
* ```
*
* @param fieldName - The field name to be divided.
* @param value - The constant value to divide by.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the division operation.
*/
export declare function divide(fieldName: string, value: unknown): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the document ID from a path.
*
* @example
* ```typescript
* // Get the document ID from a path.
* documentId(myDocumentReference);
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the documentId operation.
*/
export declare function documentId(documentPath: string | DocumentReference): FunctionExpression;
/**
* @beta
*
* Creates an expression that returns the document ID from a path.
*
* @example
* ```typescript
* // Get the document ID from a path.
* documentId(field("__path__"));
* ```
*
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the documentId operation.
*/
export declare function documentId(documentPathExpr: Expression): FunctionExpression;
/**
* @beta
* Options defining how a DocumentsStage is evaluated. See {@link @firebase/firestore/pipelines#PipelineSource.(documents:1)}.
*/
export declare type DocumentsStageOptions = StageOptions & {
/**
* @beta
* An array of paths and DocumentReferences specifying the individual documents that will be the source of this pipeline.
* The converters for these DocumentReferences will be ignored and not have an effect on this pipeline.
* There must be at least one document specified in the array.
*/
docs: Array<string | DocumentReference>;
};
/**
* @beta
*
* Calculates the dot product between a field's vector value and a double array.
*
* @example
* ```typescript
* // Calculate the dot product distance between a feature vector and a target vector
* dotProduct("features", [0.5, 0.8, 0.2]);
* ```
*
* @param fieldName - The name of the field containing the first vector.
* @param vector - The other vector (as an array of doubles or VectorValue) to calculate with.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the dot product between the two vectors.
*/
export declare function dotProduct(fieldName: string, vector: number[] | VectorValue): FunctionExpression;
/**
* @beta
*
* Calculates the dot product between a field's vector value and a vector expression.
*
* @example
* ```typescript
* // Calculate the dot product distance between two document vectors: 'docVector1' and 'docVector2'
* dotProduct("docVector1", field("docVector2"));
* ```
*
* @param fieldName - The name of the field containing the first vector.
* @param vectorExpression - The other vector (represented as an `Expression`) to calculate with.
* @returns A new {@link @firebase/firestore/pipelines#Expression} representing the dot product between the two vectors.
*/
export declare function dotProduct(fieldName: string, vectorExpression: Expression): FunctionExpression;
/**
* @beta
*
* Calculates the dot product between a vector expression and a double array.
*
* @example
* ```typescript
* // Calculate the dot product between a feature vector and a target vector
* dotProduct(field("features"), [0.5, 0.8, 0.2]);
* ```
*
* @param vectorExpression - The first vector (represented as an `Expression`) to calculate with.
* @param vector - The other vector (as an array of doubles or Vector