| Expression>
+ ): FunctionExpression {
+ const secondMapExpr = valueToDefaultExpr(secondMap);
+ const otherMapExprs = otherMaps.map(valueToDefaultExpr);
+ return new FunctionExpression('map_merge', [
+ this,
+ secondMapExpr,
+ ...otherMapExprs,
+ ]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that returns the value of this expression raised to the power of another expression.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of the 'exponent' field.
+ * field("base").pow(field("exponent"));
+ * ```
+ *
+ * @param exponent The expression to raise this expression to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+ pow(exponent: Expression): FunctionExpression;
+
+ /**
+ * @beta
+ * Creates an expression that returns the value of this expression raised to the power of a constant value.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of 2.
+ * field("base").pow(2);
+ * ```
+ *
+ * @param exponent The constant value to raise this expression to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+ pow(exponent: number): FunctionExpression;
+ pow(exponent: number | Expression): FunctionExpression {
+ return new FunctionExpression('pow', [this, valueToDefaultExpr(exponent)]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that rounds a numeric value to the nearest whole number.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field.
+ * field("price").round();
+ * ```
+ *
+ * @return A new `Expression` representing the rounded value.
+ */
+ round(): FunctionExpression;
+ /**
+ * @beta
+ * Creates an expression that rounds a numeric value to the specified number of decimal places.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field to two decimal places.
+ * field("price").round(2);
+ * ```
+ *
+ * @param decimalPlaces A constant specifying the rounding precision in decimal places.
+ *
+ * @return A new `Expr` representing the rounded value.
+ */
+ round(decimalPlaces: number): FunctionExpression;
+ /**
+ * @beta
+ * Creates an expression that rounds a numeric value to the specified number of decimal places.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field to two decimal places.
+ * field("price").round(constant(2));
+ * ```
+ *
+ * @param decimalPlaces An expression specifying the rounding precision in decimal places.
+ *
+ * @return A new `Expr` representing the rounded value.
+ */
+ round(decimalPlaces: Expression): FunctionExpression;
+ round(decimalPlaces?: number | Expression): FunctionExpression {
+ if (decimalPlaces === undefined) {
+ return new FunctionExpression('round', [this]);
+ } else {
+ return new FunctionExpression('round', [
+ this,
+ valueToDefaultExpr(decimalPlaces),
+ ]);
+ }
+ }
+
+ /**
+ * @beta
+ * Creates an expression that returns the collection ID from a path.
+ *
+ * ```typescript
+ * // Get the collection ID from a path.
+ * field("__path__").collectionId();
+ * ```
+ *
+ * @return A new {@code Expression} representing the collectionId operation.
+ */
+ collectionId(): FunctionExpression {
+ return new FunctionExpression('collection_id', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that calculates the length of a string, array, map, vector, or bytes.
+ *
+ * ```typescript
+ * // Get the length of the 'name' field.
+ * field("name").length();
+ *
+ * // Get the number of items in the 'cart' array.
+ * field("cart").length();
+ * ```
+ *
+ * @return A new `Expression` representing the length of the string, array, map, vector, or bytes.
+ */
+ length(): FunctionExpression {
+ return new FunctionExpression('length', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that computes the natural logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the natural logarithm of the 'value' field.
+ * field("value").ln();
+ * ```
+ *
+ * @return A new {@code Expression} representing the natural logarithm of the numeric value.
+ */
+ ln(): FunctionExpression {
+ return new FunctionExpression('ln', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that computes the square root of a numeric value.
+ *
+ * ```typescript
+ * // Compute the square root of the 'value' field.
+ * field("value").sqrt();
+ * ```
+ *
+ * @return A new {@code Expression} representing the square root of the numeric value.
+ */
+ sqrt(): FunctionExpression {
+ return new FunctionExpression('sqrt', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that reverses a string.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myString' field.
+ * field("myString").stringReverse();
+ * ```
+ *
+ * @return A new {@code Expression} representing the reversed string.
+ */
+ stringReverse(): FunctionExpression {
+ return new FunctionExpression('string_reverse', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else
+ * return the result of the this expression evaluation.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or returns 'default_value'
+ * // if the field is absent.
+ * field("optional_field").ifAbsent("default_value")
+ * ```
+ *
+ * @param elseValue The value that will be returned if this Expression evaluates to an absent value.
+ * @return A new [Expression] representing the ifAbsent operation.
+ */
+ ifAbsent(elseValue: unknown): Expression;
+
+ /**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if this expression results in an absent value, else
+ * return the result of this expression evaluation.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or if that is
+ * // absent, then returns the value of the field `
+ * field("optional_field").ifAbsent(field('default_field'))
+ * ```
+ *
+ * @param elseExpression The Expression that will be evaluated if this Expression evaluates to an absent value.
+ * @return A new [Expression] representing the ifAbsent operation.
+ */
+ ifAbsent(elseExpression: unknown): Expression;
+
+ ifAbsent(elseValueOrExpression: Expression | unknown): Expression {
+ return new FunctionExpression('if_absent', [
+ this,
+ valueToDefaultExpr(elseValueOrExpression),
+ ]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that joins the elements of an array into a string.
+ *
+ * ```typescript
+ * // Join the elements of the 'tags' field with the delimiter from the 'separator' field.
+ * field("tags").join(field("separator"))
+ * ```
+ *
+ * @param delimiterExpression The expression that evaluates to the delimiter string.
+ * @return A new Expression representing the join operation.
+ */
+ join(delimiterExpression: Expression): Expression;
+
+ /**
+ * @beta
+ * Creates an expression that joins the elements of an array field into a string.
+ *
+ * ```typescript
+ * // Join the elements of the 'tags' field with a comma and space.
+ * field("tags").join(", ")
+ * ```
+ *
+ * @param delimiter The string to use as a delimiter.
+ * @return A new Expression representing the join operation.
+ */
+ join(delimiter: string): Expression;
+
+ join(delimeterValueOrExpression: string | Expression): Expression {
+ return new FunctionExpression('join', [
+ this,
+ valueToDefaultExpr(delimeterValueOrExpression),
+ ]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that computes the base-10 logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the base-10 logarithm of the 'value' field.
+ * field("value").log10();
+ * ```
+ *
+ * @return A new {@code Expr} representing the base-10 logarithm of the numeric value.
+ */
+ log10(): FunctionExpression {
+ return new FunctionExpression('log10', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that computes the sum of the elements in an array.
+ *
+ * ```typescript
+ * // Compute the sum of the elements in the 'scores' field.
+ * field("scores").arraySum();
+ * ```
+ *
+ * @return A new {@code Expr} representing the sum of the elements in the array.
+ */
+ arraySum(): FunctionExpression {
+ return new FunctionExpression('sum', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that splits the result of this expression into an
+ * array of substrings based on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scoresCsv' field on delimiter ','
+ * field('scoresCsv').split(',')
+ * ```
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+ split(delimiter: string): FunctionExpression;
+
+ /**
+ * @beta
+ * Creates an expression that splits the result of this expression into an
+ * array of substrings based on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scores' field on delimiter ',' or ':' depending on the stored format
+ * field('scores').split(conditional(field('format').equal('csv'), constant(','), constant(':'))
+ * ```
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+ split(delimiter: Expression): FunctionExpression;
+ split(delimiter: string | Expression): FunctionExpression {
+ return new FunctionExpression('split', [
+ this,
+ valueToDefaultExpr(delimiter),
+ ]);
+ }
+
+ /**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the beginning of the day.
+ * field('createdAt').timestampTruncate('day')
+ * ```
+ *
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+ timestampTruncate(
+ granularity: firestore.Pipelines.TimeGranularity,
+ timezone?: string | Expression,
+ ): FunctionExpression;
+
+ /**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'.
+ * field('createdAt').timestampTruncate(field('granularity'))
+ * ```
+ *
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+ timestampTruncate(
+ granularity: Expression,
+ timezone?: string | Expression,
+ ): FunctionExpression;
+ timestampTruncate(
+ granularity: firestore.Pipelines.TimeGranularity | Expression,
+ timezone?: string | Expression,
+ ): FunctionExpression {
+ const internalGranularity = isString(granularity)
+ ? granularity.toLowerCase()
+ : granularity;
+
+ const args = [this, valueToDefaultExpr(internalGranularity)];
+ if (timezone) {
+ args.push(valueToDefaultExpr(timezone));
+ }
+ return new FunctionExpression('timestamp_trunc', args);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that returns the data type of this expression's result, as a string.
+ *
+ * @example
+ * ```typescript
+ * // Get the data type of the value in field 'title'
+ * field('title').type()
+ * ```
+ *
+ * @return A new {Expression} representing the data type.
+ */
+ type(): FunctionExpression {
+ return new FunctionExpression('type', [this]);
+ }
+
+ // TODO(new-expression): Add new expression method definitions above this line
+
+ /**
+ * @beta
+ * Creates an {@link Ordering} that sorts documents in ascending order based on this expression.
+ *
+ * ```typescript
+ * // Sort documents by the 'name' field in ascending order
+ * pipeline().collection("users")
+ * .sort(field("name").ascending());
+ * ```
+ *
+ * @return A new `Ordering` for ascending sorting.
+ */
+ ascending(): Ordering {
+ return ascending(this);
+ }
+
+ /**
+ * @beta
+ * Creates an {@link Ordering} that sorts documents in descending order based on this expression.
+ *
+ * ```typescript
+ * // Sort documents by the 'createdAt' field in descending order
+ * firestore.pipeline().collection("users")
+ * .sort(field("createdAt").descending());
+ * ```
+ *
+ * @return A new `Ordering` for descending sorting.
+ */
+ descending(): Ordering {
+ return descending(this);
+ }
+
+ /**
+ * @beta
+ * Assigns an alias to this expression.
+ *
+ * Aliases are useful for renaming fields in the output of a stage or for giving meaningful
+ * names to calculated values.
+ *
+ * ```typescript
+ * // Calculate the total price and assign it the alias "totalPrice" and add it to the output.
+ * firestore.pipeline().collection("items")
+ * .addFields(field("price").multiply(field("quantity")).as("totalPrice"));
+ * ```
+ *
+ * @param name The alias to assign to this expression.
+ * @return A new {@link AliasedExpression} that wraps this
+ * expression and associates it with the provided alias.
+ */
+ as(name: string): AliasedExpression {
+ return new AliasedExpression(this, name);
+ }
+}
+
+/**
+ * @beta
+ * A class that represents an aggregate function.
+ */
+export class AggregateFunction implements AggregateFunction, HasUserData {
+ expressionType: firestore.Pipelines.ExpressionType = 'AggregateFunction';
+
+ /**
+ * @beta
+ * @internal
+ * @private
+ * Indicates if this expression was created from a literal value passed
+ * by the caller.
+ */
+ _createdFromLiteral = false;
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this.params.forEach(expr => {
+ return expr._validateUserData(ignoreUndefinedProperties);
+ });
+ }
+
+ constructor(
+ private name: string,
+ private params: Expression[],
+ ) {}
+
+ /**
+ * @beta
+ * Assigns an alias to this AggregateFunction. The alias specifies the name that
+ * the aggregated value will have in the output document.
+ *
+ * ```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.
+ * @return A new {@link AliasedAggregate} that wraps this
+ * AggregateFunction and associates it with the provided alias.
+ */
+ as(name: string): AliasedAggregate {
+ return new AliasedAggregate(this, name);
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ return {
+ functionValue: {
+ name: this.name,
+ args: this.params.map(p => p._toProto(serializer)),
+ },
+ };
+ }
+
+ _protoValueType = 'ProtoValue' as const;
+}
+
+/**
+ * @beta
+ * An AggregateFunction with alias.
+ */
+export class AliasedAggregate implements AliasedAggregate, HasUserData {
+ constructor(
+ readonly _aggregate: AggregateFunction,
+ readonly _alias: string,
+ ) {}
+
+ /**
+ * @beta
+ * @internal
+ * @private
+ * Indicates if this expression was created from a literal value passed
+ * by the caller.
+ */
+ _createdFromLiteral = false;
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this._aggregate._validateUserData(ignoreUndefinedProperties);
+ }
+}
+
+/**
+ * @beta
+ * Represents an expression that has been assigned an alias using the `.as()` method.
+ *
+ * This class wraps an existing {@link Expression} and associates it with a user-defined alias,
+ * allowing the expression's result to be referred to by name in the output
+ * of a Firestore pipeline query.
+ */
+export class AliasedExpression
+ implements firestore.Pipelines.Selectable, HasUserData
+{
+ expressionType: firestore.Pipelines.ExpressionType = 'AliasedExpression';
+ selectable = true as const;
+
+ /**
+ * @beta
+ * @internal
+ * @private
+ * Indicates if this expression was created from a literal value passed
+ * by the caller.
+ */
+ _createdFromLiteral = false;
+
+ constructor(
+ readonly _expr: Expression,
+ readonly _alias: string,
+ ) {}
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this._expr._validateUserData(ignoreUndefinedProperties);
+ }
+}
+
+/**
+ * @beta
+ * @internal
+ */
+class ListOfExprs extends Expression {
+ expressionType: firestore.Pipelines.ExpressionType = 'ListOfExprs';
+
+ constructor(private exprs: Expression[]) {
+ super();
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ return {
+ arrayValue: {
+ values: this.exprs.map(p => p._toProto(serializer)!),
+ },
+ };
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this.exprs.forEach(expr => {
+ return expr._validateUserData(ignoreUndefinedProperties);
+ });
+ }
+}
+
+/**
+ * @beta
+ * Represents a reference to a field in a Firestore document, or outputs of a {@link Pipeline} stage.
+ *
+ * Field references are used to access document field values in expressions and to specify fields
+ * for sorting, filtering, and projecting data in Firestore pipelines.
+ *
+ *
You can create a `Field` instance using the static {@link #of} method:
+ *
+ * ```typescript
+ * // Create a Field instance for the 'name' field
+ * const nameField = field("name");
+ *
+ * // Create a Field instance for a nested field 'address.city'
+ * const cityField = field("address.city");
+ * ```
+ */
+export class Field
+ extends Expression
+ implements firestore.Pipelines.Selectable
+{
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Field';
+ selectable = true as const;
+
+ /**
+ * @beta
+ * @internal
+ * @private
+ * @hideconstructor
+ * @param fieldPath
+ */
+ constructor(private fieldPath: FieldPath) {
+ super();
+ }
+
+ get fieldName(): string {
+ return this.fieldPath.formattedName;
+ }
+
+ get _alias(): string {
+ return this.fieldName;
+ }
+
+ get _expr(): Expression {
+ return this;
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(_: Serializer): api.IValue {
+ return {
+ fieldReferenceValue: this.fieldPath.formattedName,
+ };
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(_: boolean): void {}
+}
+
+/**
+ * @beta
+ * Creates a {@code Field} instance representing the field at the given path.
+ *
+ * The path can be a simple field name (e.g., "name") or a dot-separated path to a nested field
+ * (e.g., "address.city").
+ *
+ * ```typescript
+ * // Create a Field instance for the 'title' field
+ * const titleField = field("title");
+ *
+ * // Create a Field instance for a nested field 'author.firstName'
+ * const authorFirstNameField = field("author.firstName");
+ * ```
+ *
+ * @param field The path to the field.
+ * @return A new {@code Field} instance representing the specified field.
+ */
+export function field(field: string | firestore.FieldPath): Field {
+ if (typeof field === 'string') {
+ if ('__name__' === field) {
+ return new Field(FieldPath.documentId());
+ }
+ return new Field(FieldPath.fromArgument(field));
+ } else {
+ return new Field(field as unknown as FieldPath);
+ }
+}
+
+/**
+ * @beta
+ * @internal
+ * Represents a constant value that can be used in a Firestore pipeline expression.
+ *
+ * You can create a `Constant` instance using the static {@link #of} method:
+ *
+ * ```typescript
+ * // Create a Constant instance for the number 10
+ * const ten = constant(10);
+ *
+ * // Create a Constant instance for the string "hello"
+ * const hello = constant("hello");
+ * ```
+ */
+export class Constant extends Expression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Constant';
+
+ private protoValue?: api.IValue;
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ * @hideconstructor
+ * @param value The value of the constant.
+ */
+ constructor(private value: unknown) {
+ super();
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ static _fromProto(value: api.IValue): Constant {
+ const result = new Constant(value);
+ result.protoValue = value;
+ return result;
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ if (isFirestoreValue(this.value)) {
+ return this.value;
+ }
+
+ return serializer.encodeValue(this.value)!;
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ validateUserInput('value', this.value, 'constant value', {
+ allowUndefined: ignoreUndefinedProperties,
+ allowDeletes: 'none',
+ allowTransforms: false,
+ });
+ }
+}
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a number value.
+ *
+ * @param value The number value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: number): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a string value.
+ *
+ * @param value The string value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: string): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a boolean value.
+ *
+ * @param value The boolean value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: boolean): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a null value.
+ *
+ * @param value The null value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: null): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a GeoPoint value.
+ *
+ * @param value The GeoPoint value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: firestore.GeoPoint): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a Timestamp value.
+ *
+ * @param value The Timestamp value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: firestore.Timestamp): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a Date value.
+ *
+ * @param value The Date value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: Date): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a Buffer | Uint8Array value.
+ *
+ * @param value The Buffer | Uint8Array value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: Buffer | Uint8Array): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a DocumentReference value.
+ *
+ * @param value The DocumentReference value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: firestore.DocumentReference): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a Firestore proto value.
+ * For internal use only.
+ * @private
+ * @internal
+ * @param value The Firestore proto value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: api.IValue): Expression;
+
+/**
+ * @beta
+ * Creates an 'Expression' instance for a VectorValue value.
+ *
+ * @param value The VectorValue value.
+ * @return A new `Expression` instance.
+ */
+export function constant(value: firestore.VectorValue): Expression;
+
+/**
+ * @beta
+ * @internal
+ * @private
+ * @param value
+ */
+export function constant(value: unknown): Expression;
+
+export function constant(value: unknown): Expression {
+ return _constant(value);
+}
+
+export function _constant(value: unknown): Constant | BooleanExpression {
+ const c = new Constant(value);
+ if (typeof value === 'boolean') {
+ return new BooleanConstant(c);
+ } else {
+ return c;
+ }
+}
+
+/**
+ * @beta
+ * Internal only
+ * @internal
+ * @private
+ */
+export class MapValue extends Expression {
+ constructor(private plainObject: Map) {
+ super();
+ }
+
+ expressionType: firestore.Pipelines.ExpressionType = 'Constant';
+
+ _toProto(serializer: Serializer): api.IValue {
+ return serializer.encodeValue(this.plainObject);
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this.plainObject.forEach(expr => {
+ return expr._validateUserData(ignoreUndefinedProperties);
+ });
+ }
+}
+
+/**
+ * @beta
+ * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline
+ * execution.
+ *
+ * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal},
+ * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances.
+ */
+export class FunctionExpression extends Expression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Function';
+
+ constructor(
+ public _methodName: string,
+ private params: Expression[],
+ ) {
+ super();
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ return {
+ functionValue: {
+ name: this._methodName,
+ args: this.params.map(p => cast(p)._toProto(serializer)),
+ },
+ };
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this.params.forEach(expr => {
+ return expr._validateUserData(ignoreUndefinedProperties);
+ });
+ }
+}
+
+/**
+ * @beta
+ * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline
+ * execution.
+ *
+ * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal},
+ * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances.
+ */
+class MapFunctionExpr extends FunctionExpression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Function';
+
+ constructor(private map: Record) {
+ super('map', []);
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ const args: api.IValue[] = [];
+ for (const key in this.map) {
+ if (Object.prototype.hasOwnProperty.call(this.map, key)) {
+ if (this.map[key]) {
+ args.push(constant(key)._toProto(serializer));
+ args.push(this.map[key]!._toProto(serializer));
+ }
+ }
+ }
+ return {
+ functionValue: {
+ name: this._methodName,
+ args: args,
+ },
+ };
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ validateUserInput('value', this.map, 'map value', {
+ allowUndefined: ignoreUndefinedProperties,
+ allowTransforms: false,
+ allowDeletes: 'none',
+ });
+ }
+}
+
+/**
+ * @beta
+ * This class defines the base class for Firestore {@link Pipeline} functions, which can be evaluated within pipeline
+ * execution.
+ *
+ * Typically, you would not use this class or its children directly. Use either the functions like {@link and}, {@link equal},
+ * or the methods on {@link Expression} ({@link Expression#equal}, {@link Expression#lessThan}, etc.) to construct new Function instances.
+ */
+class ArrayFunctionExpr extends FunctionExpression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Function';
+
+ constructor(private values: Array) {
+ super('array', []);
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ return {
+ functionValue: {
+ name: this._methodName,
+ args: this.values
+ .filter(v => !!v)
+ .map(value => value!._toProto(serializer)),
+ },
+ };
+ }
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ validateUserInput('value', this.values, 'array value', {
+ allowUndefined: ignoreUndefinedProperties,
+ allowTransforms: false,
+ allowDeletes: 'none',
+ });
+ }
+}
+
+/**
+ * @beta
+ * An expression that evaluates to a boolean value.
+ *
+ * This expression type is useful for filter conditions.
+ *
+ */
+export abstract class BooleanExpression
+ extends Expression
+ implements firestore.Pipelines.BooleanExpression
+{
+ abstract get _expr(): Expression;
+
+ /**
+ * @beta
+ * Creates an aggregation that finds the count of input documents satisfying
+ * this boolean expression.
+ *
+ * ```typescript
+ * // Find the count of documents with a score greater than 90
+ * field("score").greaterThan(90).countIf().as("highestScore");
+ * ```
+ *
+ * @return A new `AggregateFunction` representing the 'countIf' aggregation.
+ */
+ countIf(): AggregateFunction {
+ return new AggregateFunction('count_if', [this]);
+ }
+
+ /**
+ * @beta
+ * Creates an expression that negates this boolean expression.
+ *
+ * ```typescript
+ * // Find documents where the 'tags' field does not contain 'completed'
+ * field("tags").arrayContains("completed").not();
+ * ```
+ *
+ * @return A new {@code Expression} representing the negated filter condition.
+ */
+ not(): BooleanExpression {
+ return new FunctionExpression('not', [this]).asBoolean();
+ }
+
+ /**
+ * @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`.
+ *
+ * ```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.
+ * @return A new {@code Expr} representing the conditional expression.
+ */
+ conditional(thenExpr: Expression, elseExpr: Expression): FunctionExpression {
+ return new FunctionExpression('conditional', [this, thenExpr, elseExpr]);
+ }
+
+ /**
+ * @beta
+ *
+ * Creates an expression that returns the `catch` argument if there is an
+ * error, else return the result of this expression.
+ *
+ * ```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.
+ * @return A new {@code Expr} 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.
+ *
+ * ```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.
+ * @return A new {@code Expr} 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.
+ *
+ * ```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.
+ * @return A new {@code Expr} 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.
+ *
+ * ```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.
+ * @return A new {@code Expr} representing the 'ifError' operation.
+ */
+ ifError(catchValue: unknown): FunctionExpression;
+ ifError(catchValue: unknown): unknown {
+ const normalizedCatchValue = valueToDefaultExpr(catchValue);
+ const expr = new FunctionExpression('if_error', [
+ this,
+ normalizedCatchValue,
+ ]);
+
+ return normalizedCatchValue instanceof BooleanExpression
+ ? expr.asBoolean()
+ : expr;
+ }
+
+ _toProto(serializer: Serializer): api.IValue {
+ return this._expr._toProto(serializer);
+ }
+
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ this._expr._validateUserData(ignoreUndefinedProperties);
+ }
+}
+
+export class BooleanFunctionExpression extends BooleanExpression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Function';
+ constructor(readonly _expr: FunctionExpression) {
+ super();
+ }
+}
+
+export class BooleanConstant extends BooleanExpression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Constant';
+ constructor(readonly _expr: Constant) {
+ super();
+ }
+}
+
+export class BooleanField extends BooleanExpression {
+ readonly expressionType: firestore.Pipelines.ExpressionType = 'Field';
+ constructor(readonly _expr: Field) {
+ super();
+ }
+}
+
+/**
+ * @beta
+ * Creates an aggregation that counts the number of stage inputs where the provided
+ * boolean expression evaluates to true.
+ *
+ * ```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 function countIf(booleanExpr: BooleanExpression): AggregateFunction {
+ return new AggregateFunction('count_if', [cast(booleanExpr)]);
+}
+
+/**
+ * @beta
+ * Creates an expression that indexes into an array from the beginning or end
+ * and return the element. If the index exceeds the array length, an error is
+ * returned. A negative index, starts from the end.
+ *
+ * ```typescript
+ * // Return the value in the tags field array at index 1.
+ * arrayGet('tags', 1);
+ * ```
+ *
+ * @param arrayField The name of the array field.
+ * @param index The index of the element to return.
+ * @return A new Expression representing the 'arrayGet' operation.
+ */
+export function arrayGet(arrayField: string, index: number): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that indexes into an array from the beginning or end
+ * and return the element. If the index exceeds the array length, an error is
+ * returned. A negative index, starts from the end.
+ *
+ * ```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 indexExpr An Expression evaluating to the index of the element to return.
+ * @return A new Expression representing the 'arrayGet' operation.
+ */
+export function arrayGet(
+ arrayField: string,
+ indexExpr: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that indexes into an array from the beginning or end
+ * and return the element. If the index exceeds the array length, an error is
+ * returned. A negative index, starts from the end.
+ *
+ * ```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 index The index of the element to return.
+ * @return A new Expression representing the 'arrayGet' operation.
+ */
+export function arrayGet(
+ arrayExpression: Expression,
+ index: number,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that indexes into an array from the beginning or end
+ * and return the element. If the index exceeds the array length, an error is
+ * returned. A negative index, starts from the end.
+ *
+ * ```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 indexExpr An Expression evaluating to the index of the element to return.
+ * @return A new Expression representing the 'arrayGet' operation.
+ */
+export function arrayGet(
+ arrayExpression: Expression,
+ indexExpr: Expression,
+): FunctionExpression;
+export function arrayGet(
+ array: Expression | string,
+ index: Expression | number,
+): FunctionExpression {
+ return fieldOrExpression(array).arrayGet(valueToDefaultExpr(index));
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a given expression produces an error.
+ *
+ * ```typescript
+ * // Check if the result of a calculation is an error
+ * isError(field("title").arrayContains(1));
+ * ```
+ *
+ * @param value The expression to check.
+ * @return A new {@code Expression} representing the 'isError' check.
+ */
+export function isError(value: Expression): BooleanExpression {
+ const expr: Expression = cast(value);
+ return expr.isError();
+}
+
+/**
+ * @beta
+ *
+ * Creates an expression that returns the `catch` argument if there is an
+ * error, else return the result of the `try` argument evaluation.
+ *
+ * This overload is useful when a BooleanExpression is required.
+ *
+ * ```typescript
+ * // Create an expression that protects against a divide by zero error
+ * // but always returns a boolean expression.
+ * ifError(constant(50).divide('length').gt(1), constant(false));
+ * ```
+ *
+ * @param tryExpr The try expression.
+ * @param catchExpr The catch expression that will be evaluated and
+ * returned if the tryExpr produces an error.
+ * @return A new {@code Expr} representing the 'ifError' operation.
+ */
+export function ifError(
+ tryExpr: BooleanExpression,
+ catchExpr: BooleanExpression,
+): BooleanExpression;
+
+/**
+ * @beta
+ *
+ * Creates an expression that returns the `catch` argument if there is an
+ * error, else return the result of the `try` argument evaluation.
+ *
+ * ```typescript
+ * // Returns the first item in the title field arrays, or returns
+ * // the entire title field if the array is empty or the field is another type.
+ * ifError(field("title").arrayGet(0), field("title"));
+ * ```
+ *
+ * @param tryExpr The try expression.
+ * @param catchExpr The catch expression that will be evaluated and
+ * returned if the tryExpr produces an error.
+ * @return A new {@code Expression} representing the 'ifError' operation.
+ */
+export function ifError(
+ tryExpr: Expression,
+ catchExpr: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ *
+ * Creates an expression that returns the `catch` argument if there is an
+ * error, else return the result of the `try` argument evaluation.
+ *
+ * ```typescript
+ * // Returns the first item in the title field arrays, or returns
+ * // "Default Title"
+ * ifError(field("title").arrayGet(0), "Default Title");
+ * ```
+ *
+ * @param tryExpr The try expression.
+ * @param catchValue The value that will be returned if the tryExpr produces an
+ * error.
+ * @return A new {@code Expression} representing the 'ifError' operation.
+ */
+export function ifError(
+ tryExpr: Expression,
+ catchValue: unknown,
+): FunctionExpression;
+
+export function ifError(
+ tryExpr: Expression,
+ catchValue: unknown,
+): FunctionExpression | BooleanExpression {
+ if (
+ tryExpr instanceof BooleanExpression &&
+ catchValue instanceof BooleanExpression
+ ) {
+ return tryExpr.ifError(catchValue).asBoolean();
+ } else {
+ return tryExpr.ifError(valueToDefaultExpr(catchValue));
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that returns `true` if a value is absent. Otherwise,
+ * returns `false` even if the value is `null`.
+ *
+ * ```typescript
+ * // Check if the field `value` is absent.
+ * isAbsent(field("value"));
+ * ```
+ *
+ * @param value The expression to check.
+ * @return A new {@code Expression} representing the 'isAbsent' check.
+ */
+export function isAbsent(value: Expression): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns `true` if a field is absent. Otherwise,
+ * returns `false` even if the field value is `null`.
+ *
+ * ```typescript
+ * // Check if the field `value` is absent.
+ * isAbsent("value");
+ * ```
+ *
+ * @param field The field to check.
+ * @return A new {@code Expression} representing the 'isAbsent' check.
+ */
+export function isAbsent(field: string): BooleanExpression;
+export function isAbsent(value: Expression | string): BooleanExpression {
+ return fieldOrExpression(value).isAbsent();
+}
+
+/**
+ * @beta
+ * Creates an expression that removes a key from the map at the specified field name.
+ *
+ * ```
+ * // Removes the key 'city' field from the map in the address field of the input document.
+ * mapRemove('address', 'city');
+ * ```
+ *
+ * @param mapField The name of a field containing a map value.
+ * @param key The name of the key to remove from the input map.
+ */
+export function mapRemove(mapField: string, key: string): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that removes a key from the map produced by evaluating an expression.
+ *
+ * ```
+ * // Removes the key 'baz' from the input map.
+ * mapRemove(map({foo: 'bar', baz: true}), 'baz');
+ * ```
+ *
+ * @param mapExpr An expression return a map value.
+ * @param key The name of the key to remove from the input map.
+ */
+export function mapRemove(mapExpr: Expression, key: string): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that removes a key from the map at the specified field name.
+ *
+ * ```
+ * // Removes the key 'city' field from the map in the address field of the input document.
+ * mapRemove('address', constant('city'));
+ * ```
+ *
+ * @param mapField The name of a field containing a map value.
+ * @param keyExpr An expression that produces the name of the key to remove from the input map.
+ */
+export function mapRemove(
+ mapField: string,
+ keyExpr: Expression,
+): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that removes a key from the map produced by evaluating an expression.
+ *
+ * ```
+ * // Removes the key 'baz' from the input map.
+ * mapRemove(map({foo: 'bar', baz: true}), constant('baz'));
+ * ```
+ *
+ * @param mapExpr An expression return a map value.
+ * @param keyExpr An expression that produces the name of the key to remove from the input map.
+ */
+export function mapRemove(
+ mapExpr: Expression,
+ keyExpr: Expression,
+): FunctionExpression;
+
+export function mapRemove(
+ mapExpr: Expression | string,
+ stringExpr: Expression | string,
+): FunctionExpression {
+ return fieldOrExpression(mapExpr).mapRemove(valueToDefaultExpr(stringExpr));
+}
+
+/**
+ * @beta
+ * Creates an expression that merges multiple map values.
+ *
+ * ```
+ * // Merges the map in the settings field with, a map literal, and a map in
+ * // that is conditionally returned by another expression
+ * mapMerge('settings', { enabled: true }, conditional(field('isAdmin'), { admin: true}, {})
+ * ```
+ *
+ * @param mapField Name of a field containing a map value that will be merged.
+ * @param secondMap A required second map to merge. Represented as a literal or
+ * an expression that returns a map.
+ * @param otherMaps Optional additional maps to merge. Each map is represented
+ * as a literal or an expression that returns a map.
+ */
+export function mapMerge(
+ mapField: string,
+ secondMap: Record | Expression,
+ ...otherMaps: Array | Expression>
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that merges multiple map values.
+ *
+ * ```
+ * // Merges the map in the settings field with, a map literal, and a map in
+ * // that is conditionally returned by another expression
+ * mapMerge(field('settings'), { enabled: true }, conditional(field('isAdmin'), { admin: true}, {})
+ * ```
+ *
+ * @param firstMap An expression or literal map value that will be merged.
+ * @param secondMap A required second map to merge. Represented as a literal or
+ * an expression that returns a map.
+ * @param otherMaps Optional additional maps to merge. Each map is represented
+ * as a literal or an expression that returns a map.
+ */
+export function mapMerge(
+ firstMap: Record | Expression,
+ secondMap: Record | Expression,
+ ...otherMaps: Array | Expression>
+): FunctionExpression;
+
+export function mapMerge(
+ firstMap: string | Record | Expression,
+ secondMap: Record | Expression,
+ ...otherMaps: Array | Expression>
+): FunctionExpression {
+ const secondMapExpr = valueToDefaultExpr(secondMap);
+ const otherMapExprs = otherMaps.map(valueToDefaultExpr);
+ return fieldOrExpression(firstMap).mapMerge(secondMapExpr, ...otherMapExprs);
+}
+
+/**
+ * @beta
+ *
+ * Creates an expression that returns the document ID from a path.
+ *
+ * ```typescript
+ * // Get the document ID from a path.
+ * documentId(myDocumentReference);
+ * ```
+ *
+ * @return A new {@code Expr} representing the documentId operation.
+ */
+export function documentId(
+ documentPath: string | firestore.DocumentReference,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the document ID from a path.
+ *
+ * ```typescript
+ * // Get the document ID from a path.
+ * documentId(field("__path__"));
+ * ```
+ *
+ * @return A new {@code Expression} representing the documentId operation.
+ */
+export function documentId(documentPathExpr: Expression): FunctionExpression;
+export function documentId(
+ documentPath: Expression | string | firestore.DocumentReference,
+): FunctionExpression {
+ const documentPathExpr = valueToDefaultExpr(documentPath);
+ return documentPathExpr.documentId();
+}
+
+/**
+ * @beta
+ * Creates an expression that returns a substring of a string or byte array.
+ *
+ * @param field The name of a field containing a string or byte array to compute the substring from.
+ * @param position Index of the first character of the substring.
+ * @param length Length of the substring.
+ */
+export function substring(
+ field: string,
+ position: number,
+ length?: number,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns a substring of a string or byte array.
+ *
+ * @param input An expression returning a string or byte array to compute the substring from.
+ * @param position Index of the first character of the substring.
+ * @param length Length of the substring.
+ */
+export function substring(
+ input: Expression,
+ position: number,
+ length?: number,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns a substring of a string or byte array.
+ *
+ * @param field The name of a field containing a string or byte array to compute the substring from.
+ * @param position An expression that returns the index of the first character of the substring.
+ * @param length An expression that returns the length of the substring.
+ */
+export function substring(
+ field: string,
+ position: Expression,
+ length?: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns a substring of a string or byte array.
+ *
+ * @param input An expression returning a string or byte array to compute the substring from.
+ * @param position An expression that returns the index of the first character of the substring.
+ * @param length An expression that returns the length of the substring.
+ */
+export function substring(
+ input: Expression,
+ position: Expression,
+ length?: Expression,
+): FunctionExpression;
+
+export function substring(
+ field: Expression | string,
+ position: Expression | number,
+ length?: Expression | number,
+): FunctionExpression {
+ const fieldExpr = fieldOrExpression(field);
+ const positionExpr = valueToDefaultExpr(position);
+ const lengthExpr =
+ length === undefined ? undefined : valueToDefaultExpr(length);
+ return fieldExpr.substring(positionExpr, lengthExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that adds the result of two expressions together.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the addition operation.
+ */
+export function add(
+ first: Expression,
+ second: Expression | unknown,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that adds a field's value to the result of an expression.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the addition operation.
+ */
+export function add(
+ fieldName: string,
+ second: Expression | unknown,
+): FunctionExpression;
+
+export function add(
+ first: Expression | string,
+ second: Expression | unknown,
+): FunctionExpression {
+ return fieldOrExpression(first).add(valueToDefaultExpr(second));
+}
+
+/**
+ * @beta
+ * Creates an expression that subtracts two expressions.
+ *
+ * ```typescript
+ * // Subtract the 'discount' field from the 'price' field
+ * subtract(field("price"), field("discount"));
+ * ```
+ *
+ * @param minuend The expression to subtract from.
+ * @param subtrahend The expression to subtract.
+ * @return A new {@code Expression} representing the subtraction operation.
+ */
+export function subtract(
+ minuend: Expression,
+ subtrahend: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that subtracts a constant value from an expression.
+ *
+ * ```typescript
+ * // Subtract the constant value 2 from the 'value' field
+ * subtract(field("value"), 2);
+ * ```
+ *
+ * @param minuend The expression to subtract from.
+ * @param subtrahend The constant value to subtract.
+ * @return A new {@code Expression} representing the subtraction operation.
+ */
+export function subtract(
+ minuend: Expression,
+ subtrahend: unknown,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that subtracts an expression from a field's value.
+ *
+ * ```typescript
+ * // Subtract the 'discount' field from the 'price' field
+ * subtract("price", field("discount"));
+ * ```
+ *
+ * @param minuendFieldName The field name to subtract from.
+ * @param subtrahend The expression to subtract.
+ * @return A new {@code Expression} representing the subtraction operation.
+ */
+export function subtract(
+ minuendFieldName: string,
+ subtrahend: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that subtracts a constant value from a field's value.
+ *
+ * ```typescript
+ * // Subtract 20 from the value of the 'total' field
+ * subtract("total", 20);
+ * ```
+ *
+ * @param minuendFieldName The field name to subtract from.
+ * @param subtrahend The constant value to subtract.
+ * @return A new {@code Expression} representing the subtraction operation.
+ */
+export function subtract(
+ minuendFieldName: string,
+ subtrahend: unknown,
+): FunctionExpression;
+export function subtract(
+ left: Expression | string,
+ right: Expression | unknown,
+): FunctionExpression {
+ const normalizedLeft = fieldOrExpression(left);
+ const normalizedRight = valueToDefaultExpr(right);
+ return normalizedLeft.subtract(normalizedRight);
+}
+
+/**
+ * @beta
+ * Creates an expression that multiplies the result of two expressions together.
+ *
+ * ```typescript
+ * // Multiply the 'quantity' field by the 'price' field
+ * multiply(field("quantity"), field("price"));
+ * ```
+ *
+ * @param first The first expression to multiply.
+ * @param second The second expression or literal to multiply.
+ * @return A new {@code Expression} representing the multiplication operation.
+ */
+export function multiply(
+ first: Expression,
+ second: Expression | unknown,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that multiplies a field's value by the result of an expression.
+ *
+ * ```typescript
+ * // Multiply the 'quantity' field by the 'price' field
+ * multiply("quantity", field("price"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the value to multiply.
+ * @param second The second expression or literal to multiply.
+ * @return A new {@code Expression} representing the multiplication operation.
+ */
+export function multiply(
+ fieldName: string,
+ second: Expression | unknown,
+): FunctionExpression;
+
+export function multiply(
+ first: Expression | string,
+ second: Expression | unknown,
+): FunctionExpression {
+ return fieldOrExpression(first).multiply(valueToDefaultExpr(second));
+}
+
+/**
+ * @beta
+ * Creates an expression that divides two expressions.
+ *
+ * ```typescript
+ * // Divide the 'total' field by the 'count' field
+ * divide(field("total"), field("count"));
+ * ```
+ *
+ * @param dividend The expression to be divided.
+ * @param divisort The expression to divide by.
+ * @return A new {@code Expression} representing the division operation.
+ */
+export function divide(
+ dividend: Expression,
+ divisort: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that divides an expression by a constant value.
+ *
+ * ```typescript
+ * // Divide the 'value' field by 10
+ * divide(field("value"), 10);
+ * ```
+ *
+ * @param dividend The expression to be divided.
+ * @param divisor The constant value to divide by.
+ * @return A new {@code Expression} representing the division operation.
+ */
+export function divide(
+ dividend: Expression,
+ divisor: unknown,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that divides a field's value by an expression.
+ *
+ * ```typescript
+ * // Divide the 'total' field by the 'count' field
+ * divide("total", field("count"));
+ * ```
+ *
+ * @param dividend The field name to be divided.
+ * @param divisor The expression to divide by.
+ * @return A new {@code Expression} representing the division operation.
+ */
+export function divide(
+ dividend: string,
+ divisor: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that divides a field's value by a constant value.
+ *
+ * ```typescript
+ * // Divide the 'value' field by 10
+ * divide("value", 10);
+ * ```
+ *
+ * @param dividend The field name to be divided.
+ * @param divisor The constant value to divide by.
+ * @return A new {@code Expression} representing the division operation.
+ */
+export function divide(dividend: string, divisor: unknown): FunctionExpression;
+export function divide(
+ dividend: Expression | string,
+ divisor: Expression | unknown,
+): FunctionExpression {
+ const normalizedLeft = fieldOrExpression(dividend);
+ const normalizedRight = valueToDefaultExpr(divisor);
+ return normalizedLeft.divide(normalizedRight);
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the modulo (remainder) of dividing two expressions.
+ *
+ * ```typescript
+ * // Calculate the remainder of dividing 'field1' by 'field2'.
+ * mod(field("field1"), field("field2"));
+ * ```
+ *
+ * @param left The dividend expression.
+ * @param right The divisor expression.
+ * @return A new {@code Expression} representing the modulo operation.
+ */
+export function mod(left: Expression, right: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the modulo (remainder) of dividing an expression by a constant.
+ *
+ * ```typescript
+ * // Calculate the remainder of dividing 'field1' by 5.
+ * mod(field("field1"), 5);
+ * ```
+ *
+ * @param expression The dividend expression.
+ * @param value The divisor constant.
+ * @return A new {@code Expression} representing the modulo operation.
+ */
+export function mod(expression: Expression, value: unknown): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the modulo (remainder) of dividing a field's value by an expression.
+ *
+ * ```typescript
+ * // Calculate the remainder of dividing 'field1' by 'field2'.
+ * mod("field1", field("field2"));
+ * ```
+ *
+ * @param fieldName The dividend field name.
+ * @param expression The divisor expression.
+ * @return A new {@code Expression} representing the modulo operation.
+ */
+export function mod(
+ fieldName: string,
+ expression: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the modulo (remainder) of dividing a field's value by a constant.
+ *
+ * ```typescript
+ * // Calculate the remainder of dividing 'field1' by 5.
+ * mod("field1", 5);
+ * ```
+ *
+ * @param fieldName The dividend field name.
+ * @param value The divisor constant.
+ * @return A new {@code Expression} representing the modulo operation.
+ */
+export function mod(fieldName: string, value: unknown): FunctionExpression;
+export function mod(
+ left: Expression | string,
+ right: Expression | unknown,
+): FunctionExpression {
+ const normalizedLeft = fieldOrExpression(left);
+ const normalizedRight = valueToDefaultExpr(right);
+ return normalizedLeft.mod(normalizedRight);
+}
+
+/**
+ * @beta
+ * Creates an expression that creates a Firestore map value from an input object.
+ *
+ * ```typescript
+ * // Create a map from the input object and reference the 'baz' field value from the input document.
+ * map({foo: 'bar', baz: field('baz')}).as('data');
+ * ```
+ *
+ * @param elements The input map to evaluate in the expression.
+ * @return A new {@code Expression} representing the map function.
+ */
+export function map(elements: Record): FunctionExpression {
+ const result: Record = {};
+
+ for (const key in elements) {
+ if (Object.prototype.hasOwnProperty.call(elements, key)) {
+ result[key] =
+ elements[key] !== undefined
+ ? valueToDefaultExpr(elements[key])
+ : undefined;
+ }
+ }
+ return new MapFunctionExpr(result);
+}
+
+/**
+ * @beta
+ * Internal use only
+ * Converts a plainObject to a mapValue in the proto representation,
+ * rather than a functionValue+map that is the result of the map(...) function.
+ * This behaves different from constant(plainObject) because it
+ * traverses the input object, converts values in the object to expressions,
+ * and calls _readUserData on each of these expressions.
+ * @private
+ * @internal
+ * @param plainObject
+ */
+export function _mapValue(plainObject: Record): MapValue {
+ const result: Map = new Map();
+ for (const key in plainObject) {
+ if (Object.prototype.hasOwnProperty.call(plainObject, key)) {
+ const value = plainObject[key];
+ result.set(key, valueToDefaultExpr(value));
+ }
+ }
+ return new MapValue(result);
+}
+
+/**
+ * @beta
+ * Creates an expression that creates a Firestore array value from an input array.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the array function.
+ */
+export function array(elements: unknown[]): FunctionExpression {
+ return new ArrayFunctionExpr(
+ elements.map(element => {
+ return element !== undefined ? valueToDefaultExpr(element) : undefined;
+ }),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if two expressions are equal.
+ *
+ * ```typescript
+ * // Check if the 'age' field is equal to an expression
+ * equal(field("age"), field("minAge").add(10));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the equality comparison.
+ */
+export function equal(left: Expression, right: Expression): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'age' field is equal to 21
+ * equal(field("age"), 21);
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the equality comparison.
+ */
+export function equal(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is equal to an expression.
+ *
+ * ```typescript
+ * // Check if the 'age' field is equal to the 'limit' field
+ * equal("age", field("limit"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param expression The expression to compare to.
+ * @return A new `Expression` representing the equality comparison.
+ */
+export function equal(
+ fieldName: string,
+ expression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'city' field is equal to string constant "London"
+ * equal("city", "London");
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the equality comparison.
+ */
+export function equal(fieldName: string, value: unknown): BooleanExpression;
+export function equal(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.equal(rightExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if two expressions are not equal.
+ *
+ * ```typescript
+ * // Check if the 'status' field is not equal to field 'finalState'
+ * notEqual(field("status"), field("finalState"));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the inequality comparison.
+ */
+export function notEqual(
+ left: Expression,
+ right: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is not equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'status' field is not equal to "completed"
+ * notEqual(field("status"), "completed");
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the inequality comparison.
+ */
+export function notEqual(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is not equal to an expression.
+ *
+ * ```typescript
+ * // Check if the 'status' field is not equal to the value of 'expectedStatus'
+ * notEqual("status", field("expectedStatus"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param expression The expression to compare to.
+ * @return A new `Expression` representing the inequality comparison.
+ */
+export function notEqual(
+ fieldName: string,
+ expression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is not equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'country' field is not equal to "USA"
+ * notEqual("country", "USA");
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the inequality comparison.
+ */
+export function notEqual(fieldName: string, value: unknown): BooleanExpression;
+export function notEqual(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.notEqual(rightExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if the first expression is less than the second expression.
+ *
+ * ```typescript
+ * // Check if the 'age' field is less than 30
+ * lessThan(field("age"), field("limit"));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the less than comparison.
+ */
+export function lessThan(
+ left: Expression,
+ right: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is less than a constant value.
+ *
+ * ```typescript
+ * // Check if the 'age' field is less than 30
+ * lessThan(field("age"), 30);
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the less than comparison.
+ */
+export function lessThan(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is less than an expression.
+ *
+ * ```typescript
+ * // Check if the 'age' field is less than the 'limit' field
+ * lessThan("age", field("limit"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param expression The expression to compare to.
+ * @return A new `Expression` representing the less than comparison.
+ */
+export function lessThan(
+ fieldName: string,
+ expression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is less than a constant value.
+ *
+ * ```typescript
+ * // Check if the 'price' field is less than 50
+ * lessThan("price", 50);
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the less than comparison.
+ */
+export function lessThan(fieldName: string, value: unknown): BooleanExpression;
+export function lessThan(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.lessThan(rightExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if the first expression is less than or equal to the second
+ * expression.
+ *
+ * ```typescript
+ * // Check if the 'quantity' field is less than or equal to 20
+ * lessThanOrEqual(field("quantity"), field("limit"));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the less than or equal to comparison.
+ */
+export function lessThanOrEqual(
+ left: Expression,
+ right: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is less than or equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'quantity' field is less than or equal to 20
+ * lessThanOrEqual(field("quantity"), 20);
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the less than or equal to comparison.
+ */
+export function lessThanOrEqual(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is less than or equal to an expression.
+ *
+ * ```typescript
+ * // Check if the 'quantity' field is less than or equal to the 'limit' field
+ * lessThanOrEqual("quantity", field("limit"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param expression The expression to compare to.
+ * @return A new `Expression` representing the less than or equal to comparison.
+ */
+export function lessThanOrEqual(
+ fieldName: string,
+ expression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is less than or equal to a constant value.
+ *
+ * ```typescript
+ * // Check if the 'score' field is less than or equal to 70
+ * lessThanOrEqual("score", 70);
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the less than or equal to comparison.
+ */
+export function lessThanOrEqual(
+ fieldName: string,
+ value: unknown,
+): BooleanExpression;
+export function lessThanOrEqual(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.lessThanOrEqual(rightExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if the first expression is greater than the second
+ * expression.
+ *
+ * ```typescript
+ * // Check if the 'age' field is greater than 18
+ * greaterThan(field("age"), Constant(9).add(9));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the greater than comparison.
+ */
+export function greaterThan(
+ left: Expression,
+ right: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is greater than a constant value.
+ *
+ * ```typescript
+ * // Check if the 'age' field is greater than 18
+ * greaterThan(field("age"), 18);
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the greater than comparison.
+ */
+export function greaterThan(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is greater than an expression.
+ *
+ * ```typescript
+ * // Check if the value of field 'age' is greater than the value of field 'limit'
+ * greaterThan("age", field("limit"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param expression The expression to compare to.
+ * @return A new `Expression` representing the greater than comparison.
+ */
+export function greaterThan(
+ fieldName: string,
+ expression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is greater than a constant value.
+ *
+ * ```typescript
+ * // Check if the 'price' field is greater than 100
+ * greaterThan("price", 100);
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the greater than comparison.
+ */
+export function greaterThan(
+ fieldName: string,
+ value: unknown,
+): BooleanExpression;
+export function greaterThan(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.greaterThan(rightExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if the first expression is greater than or equal to the
+ * second expression.
+ *
+ * ```typescript
+ * // Check if the 'quantity' field is greater than or equal to the field "threshold"
+ * greaterThanOrEqual(field("quantity"), field("threshold"));
+ * ```
+ *
+ * @param left The first expression to compare.
+ * @param right The second expression to compare.
+ * @return A new `Expression` representing the greater than or equal to comparison.
+ */
+export function greaterThanOrEqual(
+ left: Expression,
+ right: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is greater than or equal to a constant
+ * value.
+ *
+ * ```typescript
+ * // Check if the 'quantity' field is greater than or equal to 10
+ * greaterThanOrEqual(field("quantity"), 10);
+ * ```
+ *
+ * @param expression The expression to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the greater than or equal to comparison.
+ */
+export function greaterThanOrEqual(
+ expression: Expression,
+ value: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is greater than or equal to an expression.
+ *
+ * ```typescript
+ * // Check if the value of field 'age' is greater than or equal to the value of field 'limit'
+ * greaterThanOrEqual("age", field("limit"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The expression to compare to.
+ * @return A new `Expression` representing the greater than or equal to comparison.
+ */
+export function greaterThanOrEqual(
+ fieldName: string,
+ value: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is greater than or equal to a constant
+ * value.
+ *
+ * ```typescript
+ * // Check if the 'score' field is greater than or equal to 80
+ * greaterThanOrEqual("score", 80);
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param value The constant value to compare to.
+ * @return A new `Expression` representing the greater than or equal to comparison.
+ */
+export function greaterThanOrEqual(
+ fieldName: string,
+ value: unknown,
+): BooleanExpression;
+export function greaterThanOrEqual(
+ left: Expression | string,
+ right: unknown,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const rightExpr = valueToDefaultExpr(right);
+ return leftExpr.greaterThanOrEqual(rightExpr);
+}
+
+/**
+ * @beta
+ *
+ * Creates an expression that concatenates an array expression with other arrays.
+ *
+ * ```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.
+ * @return A new {@code Expr} representing the concatenated array.
+ */
+export function arrayConcat(
+ firstArray: Expression,
+ secondArray: Expression | unknown[],
+ ...otherArrays: Array
+): FunctionExpression;
+
+/**
+ * @beta
+ *
+ * Creates an expression that concatenates a field's array value with other arrays.
+ *
+ * ```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.
+ * @return A new {@code Expr} representing the concatenated array.
+ */
+export function arrayConcat(
+ firstArrayField: string,
+ secondArray: Expression | unknown[],
+ ...otherArrays: Array
+): FunctionExpression;
+
+export function arrayConcat(
+ firstArray: Expression | string,
+ secondArray: Expression | unknown[],
+ ...otherArrays: Array
+): FunctionExpression {
+ const exprValues = otherArrays.map(element => valueToDefaultExpr(element));
+ return fieldOrExpression(firstArray).arrayConcat(
+ fieldOrExpression(secondArray),
+ ...exprValues,
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains a specific element.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains' comparison.
+ */
+export function arrayContains(
+ array: Expression,
+ element: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains a specific element.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains' comparison.
+ */
+export function arrayContains(
+ array: Expression,
+ element: unknown,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's array value contains a specific element.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains' comparison.
+ */
+export function arrayContains(
+ fieldName: string,
+ element: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's array value contains a specific value.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains' comparison.
+ */
+export function arrayContains(
+ fieldName: string,
+ element: unknown,
+): BooleanExpression;
+export function arrayContains(
+ array: Expression | string,
+ element: unknown,
+): BooleanExpression {
+ const arrayExpr = fieldOrExpression(array);
+ const elementExpr = valueToDefaultExpr(element);
+ return arrayExpr.arrayContains(elementExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains any of the specified
+ * elements.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_any' comparison.
+ */
+export function arrayContainsAny(
+ array: Expression,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's array value contains any of the specified
+ * elements.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_any' comparison.
+ */
+export function arrayContainsAny(
+ fieldName: string,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains any of the specified
+ * elements.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_any' comparison.
+ */
+export 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.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_any' comparison.
+ */
+export function arrayContainsAny(
+ fieldName: string,
+ values: Expression,
+): BooleanExpression;
+export function arrayContainsAny(
+ array: Expression | string,
+ values: unknown[] | Expression,
+): BooleanExpression {
+ if (Array.isArray(values)) {
+ return fieldOrExpression(array).arrayContainsAny(values);
+ } else {
+ return fieldOrExpression(array).arrayContainsAny(values);
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains all the specified elements.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_all' comparison.
+ */
+export function arrayContainsAll(
+ array: Expression,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's array value contains all the specified values or
+ * expressions.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_all' comparison.
+ */
+export function arrayContainsAll(
+ fieldName: string,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an array expression contains all the specified elements.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_all' comparison.
+ */
+export 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.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the 'array_contains_all' comparison.
+ */
+export function arrayContainsAll(
+ fieldName: string,
+ arrayExpression: Expression,
+): BooleanExpression;
+export function arrayContainsAll(
+ array: Expression | string,
+ values: unknown[] | Expression,
+): BooleanExpression {
+ if (Array.isArray(values)) {
+ return fieldOrExpression(array).arrayContainsAll(values);
+ } else {
+ return fieldOrExpression(array).arrayContainsAll(values);
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of an array in a specified field.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the length of the array.
+ */
+export function arrayLength(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of an array expression.
+ *
+ * ```typescript
+ * // Get the number of items in the 'cart' array
+ * arrayLength(field("cart"));
+ * ```
+ *
+ * @param array The array expression to calculate the length of.
+ * @return A new {@code Expression} representing the length of the array.
+ */
+export function arrayLength(array: Expression): FunctionExpression;
+export function arrayLength(array: Expression | string): FunctionExpression {
+ return fieldOrExpression(array).arrayLength();
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression, when evaluated, is equal to any of the provided values or
+ * expressions.
+ *
+ * ```typescript
+ * // Check if the 'category' field is either "Electronics" or value of field 'primaryType'
+ * equalAny(field("category"), [constant("Electronics"), field("primaryType")]);
+ * ```
+ *
+ * @param expression The expression whose results to compare.
+ * @param values The values to check against.
+ * @return A new {@code Expression} representing the 'IN' comparison.
+ */
+export function equalAny(
+ expression: Expression,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is equal to any of the provided values.
+ *
+ * ```typescript
+ * // Check if the 'category' field is set to a value in the disabledCategories field
+ * equalAny(field("category"), field('disabledCategories'));
+ * ```
+ *
+ * @param expression The expression whose results to compare.
+ * @param arrayExpression An expression that evaluates to an array, whose elements to check for equality to the input.
+ * @return A new {@code Expression} representing the 'IN' comparison.
+ */
+export function equalAny(
+ expression: Expression,
+ arrayExpression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is equal to any of the provided values or
+ * expressions.
+ *
+ * ```typescript
+ * // Check if the 'category' field is either "Electronics" or value of field 'primaryType'
+ * equalAny("category", [constant("Electronics"), field("primaryType")]);
+ * ```
+ *
+ * @param fieldName The field to compare.
+ * @param values The values to check against.
+ * @return A new {@code Expression} representing the 'IN' comparison.
+ */
+export function equalAny(
+ fieldName: string,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is equal to any of the provided values or
+ * expressions.
+ *
+ * ```typescript
+ * // Check if the 'category' field is either "Electronics" or value of field 'primaryType'
+ * equalAny("category", ["Electronics", field("primaryType")]);
+ * ```
+ *
+ * @param fieldName The field to compare.
+ * @param arrayExpression An expression that evaluates to an array, whose elements to check for equality to the input field.
+ * @return A new {@code Expression} representing the 'IN' comparison.
+ */
+export function equalAny(
+ fieldName: string,
+ arrayExpression: Expression,
+): BooleanExpression;
+export function equalAny(
+ element: Expression | string,
+ values: unknown[] | Expression,
+): BooleanExpression {
+ if (Array.isArray(values)) {
+ return fieldOrExpression(element).equalAny(values);
+ } else {
+ return fieldOrExpression(element).equalAny(values);
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is not equal to any of the provided values
+ * or expressions.
+ *
+ * ```typescript
+ * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
+ * notEqualAny(field("status"), ["pending", field("rejectedStatus")]);
+ * ```
+ *
+ * @param element The expression to compare.
+ * @param values The values to check against.
+ * @return A new {@code Expression} representing the 'NOT IN' comparison.
+ */
+export function notEqualAny(
+ element: Expression,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is not equal to any of the provided values
+ * or expressions.
+ *
+ * ```typescript
+ * // Check if the 'status' field is neither "pending" nor the value of 'rejectedStatus'
+ * notEqualAny("status", [constant("pending"), field("rejectedStatus")]);
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param values The values to check against.
+ * @return A new {@code Expression} representing the 'NOT IN' comparison.
+ */
+export function notEqualAny(
+ fieldName: string,
+ values: Array,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if an expression is not equal to any of the provided values
+ * or expressions.
+ *
+ * ```typescript
+ * // Check if the 'status' field is neither "pending" nor the value of the field 'rejectedStatus'
+ * notEqualAny(field("status"), ["pending", field("rejectedStatus")]);
+ * ```
+ *
+ * @param element The expression to compare.
+ * @param arrayExpression The values to check against.
+ * @return A new {@code Expression} representing the 'NOT IN' comparison.
+ */
+export function notEqualAny(
+ element: Expression,
+ arrayExpression: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value is not equal to any of the values in the evaluated expression.
+ *
+ * ```typescript
+ * // Check if the 'status' field is not equal to any value in the field 'rejectedStatuses'
+ * notEqualAny("status", field("rejectedStatuses"));
+ * ```
+ *
+ * @param fieldName The field name to compare.
+ * @param arrayExpression The values to check against.
+ * @return A new {@code Expression} representing the 'NOT IN' comparison.
+ */
+export function notEqualAny(
+ fieldName: string,
+ arrayExpression: Expression,
+): BooleanExpression;
+
+export function notEqualAny(
+ element: Expression | string,
+ values: unknown[] | Expression,
+): BooleanExpression {
+ if (Array.isArray(values)) {
+ return fieldOrExpression(element).notEqualAny(values);
+ } else {
+ return fieldOrExpression(element).notEqualAny(values);
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that performs a logical 'XOR' (exclusive OR) operation on multiple BooleanExprs.
+ *
+ * ```typescript
+ * // Check if only one of the conditions is true: 'age' greater than 18, 'city' is "London",
+ * // or 'status' is "active".
+ * const condition = xor(
+ * greaterThan("age", 18),
+ * equal("city", "London"),
+ * equal("status", "active"));
+ * ```
+ *
+ * @param first The first condition.
+ * @param second The second condition.
+ * @param additionalConditions Additional conditions to 'XOR' together.
+ * @return A new {@code Expression} representing the logical 'XOR' operation.
+ */
+export function xor(
+ first: BooleanExpression,
+ second: BooleanExpression,
+ ...additionalConditions: BooleanExpression[]
+): BooleanExpression {
+ return new FunctionExpression('xor', [
+ first,
+ second,
+ ...additionalConditions,
+ ]).asBoolean();
+}
+
+/**
+ * @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.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the conditional expression.
+ */
+export function conditional(
+ condition: BooleanExpression,
+ thenExpr: Expression,
+ elseExpr: Expression,
+): FunctionExpression {
+ return new FunctionExpression('conditional', [
+ condition,
+ cast(thenExpr),
+ cast(elseExpr),
+ ]);
+}
+
+/**
+ * @beta
+ * Creates an expression that negates a filter condition.
+ *
+ * ```typescript
+ * // Find documents where the 'completed' field is NOT true
+ * not(equal("completed", true));
+ * ```
+ *
+ * @param booleanExpr The filter condition to negate.
+ * @return A new {@code Expression} representing the negated filter condition.
+ */
+export function not(booleanExpr: BooleanExpression): BooleanExpression {
+ return booleanExpr.not();
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the largest value between multiple input
+ * expressions or literal values. Based on Firestore's value type ordering.
+ *
+ * ```typescript
+ * // Returns the largest value between the 'field1' field, the 'field2' field,
+ * // and 1000
+ * logicalMaximum(field("field1"), field("field2"), 1000);
+ * ```
+ *
+ * @param first The first operand expression.
+ * @param second The second expression or literal.
+ * @param others Optional additional expressions or literals.
+ * @return A new {@code Expression} representing the logical max operation.
+ */
+export function logicalMaximum(
+ first: Expression,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the largest value between multiple input
+ * expressions or literal values. Based on Firestore's value type ordering.
+ *
+ * ```typescript
+ * // Returns the largest value between the 'field1' field, the 'field2' field,
+ * // and 1000.
+ * logicalMaximum("field1", field("field2"), 1000);
+ * ```
+ *
+ * @param fieldName The first operand field name.
+ * @param second The second expression or literal.
+ * @param others Optional additional expressions or literals.
+ * @return A new {@code Expression} representing the logical max operation.
+ */
+export function logicalMaximum(
+ fieldName: string,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+export function logicalMaximum(
+ first: Expression | string,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression {
+ return fieldOrExpression(first).logicalMaximum(
+ valueToDefaultExpr(second),
+ ...others.map(value => valueToDefaultExpr(value)),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the smallest value between multiple input
+ * expressions and literal values. Based on Firestore's value type ordering.
+ *
+ * ```typescript
+ * // Returns the smallest value between the 'field1' field, the 'field2' field,
+ * // and 1000.
+ * logicalMinimum(field("field1"), field("field2"), 1000);
+ * ```
+ *
+ * @param first The first operand expression.
+ * @param second The second expression or literal.
+ * @param others Optional additional expressions or literals.
+ * @return A new {@code Expression} representing the logical min operation.
+ */
+export function logicalMinimum(
+ first: Expression,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the smallest value between a field's value
+ * and other input expressions or literal values.
+ * Based on Firestore's value type ordering.
+ *
+ * ```typescript
+ * // Returns the smallest value between the 'field1' field, the 'field2' field,
+ * // and 1000.
+ * logicalMinimum("field1", field("field2"), 1000);
+ * ```
+ *
+ * @param fieldName The first operand field name.
+ * @param second The second expression or literal.
+ * @param others Optional additional expressions or literals.
+ * @return A new {@code Expression} representing the logical min operation.
+ */
+export function logicalMinimum(
+ fieldName: string,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+export function logicalMinimum(
+ first: Expression | string,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression {
+ return fieldOrExpression(first).logicalMinimum(
+ valueToDefaultExpr(second),
+ ...others.map(value => valueToDefaultExpr(value)),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a field exists.
+ *
+ * ```typescript
+ * // Check if the document has a field named "phoneNumber"
+ * exists(field("phoneNumber"));
+ * ```
+ *
+ * @param value An expression evaluates to the name of the field to check.
+ * @return A new {@code Expression} representing the 'exists' check.
+ */
+export function exists(value: Expression): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field exists.
+ *
+ * ```typescript
+ * // Check if the document has a field named "phoneNumber"
+ * exists("phoneNumber");
+ * ```
+ *
+ * @param fieldName The field name to check.
+ * @return A new {@code Expression} representing the 'exists' check.
+ */
+export function exists(fieldName: string): BooleanExpression;
+export function exists(valueOrField: Expression | string): BooleanExpression {
+ return fieldOrExpression(valueOrField).exists();
+}
+
+/**
+ * @beta
+ * Creates an expression that reverses a string.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myString' field.
+ * reverse(field("myString"));
+ * ```
+ *
+ * @param stringExpression An expression evaluating to a string value, which will be reversed.
+ * @return A new {@code Expression} representing the reversed string.
+ */
+export function reverse(stringExpression: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that reverses a string value in the specified field.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myString' field.
+ * reverse("myString");
+ * ```
+ *
+ * @param field The name of the field representing the string to reverse.
+ * @return A new {@code Expression} representing the reversed string.
+ */
+export function reverse(field: string): FunctionExpression;
+export function reverse(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).reverse();
+}
+
+/**
+ * @beta
+ * Creates an expression that reverses an array.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myArray' field.
+ * arrayReverse("myArray");
+ * ```
+ *
+ * @param fieldName The name of the field to reverse.
+ * @return A new {@code Expression} representing the reversed array.
+ */
+export function arrayReverse(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that reverses an array.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myArray' field.
+ * arrayReverse(field("myArray"));
+ * ```
+ *
+ * @param arrayExpression An expression evaluating to an array value, which will be reversed.
+ * @return A new {@code Expression} representing the reversed array.
+ */
+export function arrayReverse(arrayExpression: Expression): FunctionExpression;
+export function arrayReverse(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).arrayReverse();
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the byte length of a string in UTF-8, or just the length of a Blob.
+ *
+ * ```typescript
+ * // Calculate the length of the 'myString' field in bytes.
+ * byteLength(field("myString"));
+ * ```
+ *
+ * @param expr The expression representing the string.
+ * @return A new {@code Expression} representing the length of the string in bytes.
+ */
+export 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.
+ *
+ * ```typescript
+ * // Calculate the length of the 'myString' field in bytes.
+ * byteLength("myString");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @return A new {@code Expression} representing the length of the string in bytes.
+ */
+export function byteLength(fieldName: string): FunctionExpression;
+export function byteLength(expr: Expression | string): FunctionExpression {
+ const normalizedExpr = fieldOrExpression(expr);
+ return normalizedExpr.byteLength();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes e to the power of the expression's result.
+ *
+ * ```typescript
+ * // Compute e to the power of 2.
+ * exp(constant(2));
+ * ```
+ *
+ * @return A new {@code Expression} representing the exp of the numeric value.
+ */
+export function exp(expression: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes e to the power of the expression's result.
+ *
+ * ```typescript
+ * // Compute e to the power of the 'value' field.
+ * exp('value');
+ * ```
+ *
+ * @return A new {@code Expression} representing the exp of the numeric value.
+ */
+export function exp(fieldName: string): FunctionExpression;
+
+export function exp(
+ expressionOrFieldName: Expression | string,
+): FunctionExpression {
+ return fieldOrExpression(expressionOrFieldName).exp();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the ceiling of a numeric value.
+ *
+ * ```typescript
+ * // Compute the ceiling of the 'price' field.
+ * ceil("price");
+ * ```
+ *
+ * @param fieldName The name of the field to compute the ceiling of.
+ * @return A new {@code Expression} representing the ceiling of the numeric value.
+ */
+export function ceil(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes the ceiling of a numeric value.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the ceiling of the numeric value.
+ */
+export function ceil(expression: Expression): FunctionExpression;
+export function ceil(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).ceil();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the floor of a numeric value.
+ *
+ * @param expr The expression to compute the floor of.
+ * @return A new {@code Expression} representing the floor of the numeric value.
+ */
+export function floor(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes the floor of a numeric value.
+ *
+ * @param fieldName The name of the field to compute the floor of.
+ * @return A new {@code Expression} representing the floor of the numeric value.
+ */
+export function floor(fieldName: string): FunctionExpression;
+export function floor(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).floor();
+}
+
+/**
+ * @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.
+ * @return A new `AggregateFunction` representing the 'count_distinct' aggregation.
+ */
+export function countDistinct(expr: Expression | string): AggregateFunction {
+ return fieldOrExpression(expr).countDistinct();
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the character length of a string field in UTF8.
+ *
+ * ```typescript
+ * // Get the character length of the 'name' field in UTF-8.
+ * strLength("name");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @return A new {@code Expression} representing the length of the string.
+ */
+export function charLength(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the character length of a string expression in UTF-8.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the length of the string.
+ */
+export function charLength(stringExpression: Expression): FunctionExpression;
+export function charLength(value: Expression | string): FunctionExpression {
+ const valueExpr = fieldOrExpression(value);
+ return valueExpr.charLength();
+}
+
+/**
+ * @beta
+ * Creates an expression that performs a case-sensitive wildcard string comparison against a
+ * field.
+ *
+ * ```typescript
+ * // Check if the 'title' field contains the string "guide"
+ * like("title", "%guide%");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The pattern to search for. You can use "%" as a wildcard character.
+ * @return A new {@code Expression} representing the 'like' comparison.
+ */
+export function like(fieldName: string, pattern: string): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that performs a case-sensitive wildcard string comparison against a
+ * field.
+ *
+ * ```typescript
+ * // Check if the 'title' field contains the string "guide"
+ * like("title", field("pattern"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The pattern to search for. You can use "%" as a wildcard character.
+ * @return A new {@code Expression} representing the 'like' comparison.
+ */
+export function like(fieldName: string, pattern: Expression): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that performs a case-sensitive wildcard string comparison.
+ *
+ * ```typescript
+ * // Check if the 'title' field contains the string "guide"
+ * like(field("title"), "%guide%");
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param pattern The pattern to search for. You can use "%" as a wildcard character.
+ * @return A new {@code Expression} representing the 'like' comparison.
+ */
+export function like(
+ stringExpression: Expression,
+ pattern: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that performs a case-sensitive wildcard string comparison.
+ *
+ * ```typescript
+ * // Check if the 'title' field contains the string "guide"
+ * like(field("title"), field("pattern"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param pattern The pattern to search for. You can use "%" as a wildcard character.
+ * @return A new {@code Expression} representing the 'like' comparison.
+ */
+export function like(
+ stringExpression: Expression,
+ pattern: Expression,
+): BooleanExpression;
+export function like(
+ left: Expression | string,
+ pattern: Expression | string,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const patternExpr = valueToDefaultExpr(pattern);
+ return leftExpr.like(patternExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field contains a specified regular expression as
+ * a substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example" (case-insensitive)
+ * regexContains("description", "(?i)example");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The regular expression to use for the search.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function regexContains(
+ fieldName: string,
+ pattern: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field contains a specified regular expression as
+ * a substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example" (case-insensitive)
+ * regexContains("description", field("pattern"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The regular expression to use for the search.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function regexContains(
+ fieldName: string,
+ pattern: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression contains a specified regular
+ * expression as a substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example" (case-insensitive)
+ * regexContains(field("description"), "(?i)example");
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param pattern The regular expression to use for the search.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function regexContains(
+ stringExpression: Expression,
+ pattern: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression contains a specified regular
+ * expression as a substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example" (case-insensitive)
+ * regexContains(field("description"), field("pattern"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param pattern The regular expression to use for the search.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function regexContains(
+ stringExpression: Expression,
+ pattern: Expression,
+): BooleanExpression;
+export function regexContains(
+ left: Expression | string,
+ pattern: Expression | string,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const patternExpr = valueToDefaultExpr(pattern);
+ return leftExpr.regexContains(patternExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field matches a specified regular expression.
+ *
+ * ```typescript
+ * // Check if the 'email' field matches a valid email pattern
+ * regexMatch("email", "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The regular expression to use for the match.
+ * @return A new {@code Expression} representing the regular expression match.
+ */
+export function regexMatch(
+ fieldName: string,
+ pattern: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field matches a specified regular expression.
+ *
+ * ```typescript
+ * // Check if the 'email' field matches a valid email pattern
+ * regexMatch("email", field("pattern"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param pattern The regular expression to use for the match.
+ * @return A new {@code Expression} representing the regular expression match.
+ */
+export function regexMatch(
+ fieldName: string,
+ pattern: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression matches a specified regular
+ * expression.
+ *
+ * ```typescript
+ * // Check if the 'email' field matches a valid email pattern
+ * regexMatch(field("email"), "[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}");
+ * ```
+ *
+ * @param stringExpression The expression representing the string to match against.
+ * @param pattern The regular expression to use for the match.
+ * @return A new {@code Expression} representing the regular expression match.
+ */
+export function regexMatch(
+ stringExpression: Expression,
+ pattern: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression matches a specified regular
+ * expression.
+ *
+ * ```typescript
+ * // Check if the 'email' field matches a valid email pattern
+ * regexMatch(field("email"), field("pattern"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to match against.
+ * @param pattern The regular expression to use for the match.
+ * @return A new {@code Expression} representing the regular expression match.
+ */
+export function regexMatch(
+ stringExpression: Expression,
+ pattern: Expression,
+): BooleanExpression;
+export function regexMatch(
+ left: Expression | string,
+ pattern: Expression | string,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const patternExpr = valueToDefaultExpr(pattern);
+ return leftExpr.regexMatch(patternExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field contains a specified substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example".
+ * stringContains("description", "example");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param substring The substring to search for.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function stringContains(
+ fieldName: string,
+ substring: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string field contains a substring specified by an expression.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains the value of the 'keyword' field.
+ * stringContains("description", field("keyword"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @param substring The expression representing the substring to search for.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function stringContains(
+ fieldName: string,
+ substring: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression contains a specified substring.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains "example".
+ * stringContains(field("description"), "example");
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param substring The substring to search for.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function stringContains(
+ stringExpression: Expression,
+ substring: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression contains a substring specified by another expression.
+ *
+ * ```typescript
+ * // Check if the 'description' field contains the value of the 'keyword' field.
+ * stringContains(field("description"), field("keyword"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to perform the comparison on.
+ * @param substring The expression representing the substring to search for.
+ * @return A new {@code Expression} representing the 'contains' comparison.
+ */
+export function stringContains(
+ stringExpression: Expression,
+ substring: Expression,
+): BooleanExpression;
+export function stringContains(
+ left: Expression | string,
+ substring: Expression | string,
+): BooleanExpression {
+ const leftExpr = fieldOrExpression(left);
+ const substringExpr = valueToDefaultExpr(substring);
+ return leftExpr.stringContains(substringExpr);
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value starts with a given prefix.
+ *
+ * ```typescript
+ * // Check if the 'name' field starts with "Mr."
+ * startsWith("name", "Mr.");
+ * ```
+ *
+ * @param fieldName The field name to check.
+ * @param prefix The prefix to check for.
+ * @return A new {@code Expression} representing the 'starts with' comparison.
+ */
+export function startsWith(
+ fieldName: string,
+ prefix: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value starts with a given prefix.
+ *
+ * ```typescript
+ * // Check if the 'fullName' field starts with the value of the 'firstName' field
+ * startsWith("fullName", field("firstName"));
+ * ```
+ *
+ * @param fieldName The field name to check.
+ * @param prefix The expression representing the prefix.
+ * @return A new {@code Expression} representing the 'starts with' comparison.
+ */
+export function startsWith(
+ fieldName: string,
+ prefix: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression starts with a given prefix.
+ *
+ * ```typescript
+ * // Check if the result of concatenating 'firstName' and 'lastName' fields starts with "Mr."
+ * startsWith(field("fullName"), "Mr.");
+ * ```
+ *
+ * @param stringExpression The expression to check.
+ * @param prefix The prefix to check for.
+ * @return A new {@code Expression} representing the 'starts with' comparison.
+ */
+export function startsWith(
+ stringExpression: Expression,
+ prefix: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression starts with a given prefix.
+ *
+ * ```typescript
+ * // Check if the result of concatenating 'firstName' and 'lastName' fields starts with "Mr."
+ * startsWith(field("fullName"), field("prefix"));
+ * ```
+ *
+ * @param stringExpression The expression to check.
+ * @param prefix The prefix to check for.
+ * @return A new {@code Expression} representing the 'starts with' comparison.
+ */
+export function startsWith(
+ stringExpression: Expression,
+ prefix: Expression,
+): BooleanExpression;
+export function startsWith(
+ expr: Expression | string,
+ prefix: Expression | string,
+): BooleanExpression {
+ return fieldOrExpression(expr).startsWith(valueToDefaultExpr(prefix));
+}
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value ends with a given postfix.
+ *
+ * ```typescript
+ * // Check if the 'filename' field ends with ".txt"
+ * endsWith("filename", ".txt");
+ * ```
+ *
+ * @param fieldName The field name to check.
+ * @param suffix The postfix to check for.
+ * @return A new {@code Expression} representing the 'ends with' comparison.
+ */
+export function endsWith(fieldName: string, suffix: string): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a field's value ends with a given postfix.
+ *
+ * ```typescript
+ * // Check if the 'url' field ends with the value of the 'extension' field
+ * endsWith("url", field("extension"));
+ * ```
+ *
+ * @param fieldName The field name to check.
+ * @param suffix The expression representing the postfix.
+ * @return A new {@code Expression} representing the 'ends with' comparison.
+ */
+export function endsWith(
+ fieldName: string,
+ suffix: Expression,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression ends with a given postfix.
+ *
+ * ```typescript
+ * // Check if the result of concatenating 'firstName' and 'lastName' fields ends with "Jr."
+ * endsWith(field("fullName"), "Jr.");
+ * ```
+ *
+ * @param stringExpression The expression to check.
+ * @param suffix The postfix to check for.
+ * @return A new {@code Expression} representing the 'ends with' comparison.
+ */
+export function endsWith(
+ stringExpression: Expression,
+ suffix: string,
+): BooleanExpression;
+
+/**
+ * @beta
+ * Creates an expression that checks if a string expression ends with a given postfix.
+ *
+ * ```typescript
+ * // Check if the result of concatenating 'firstName' and 'lastName' fields ends with "Jr."
+ * endsWith(field("fullName"), constant("Jr."));
+ * ```
+ *
+ * @param stringExpression The expression to check.
+ * @param suffix The postfix to check for.
+ * @return A new {@code Expression} representing the 'ends with' comparison.
+ */
+export function endsWith(
+ stringExpression: Expression,
+ suffix: Expression,
+): BooleanExpression;
+export function endsWith(
+ expr: Expression | string,
+ suffix: Expression | string,
+): BooleanExpression {
+ return fieldOrExpression(expr).endsWith(valueToDefaultExpr(suffix));
+}
+
+/**
+ * @beta
+ * Creates an expression that converts a string field to lowercase.
+ *
+ * ```typescript
+ * // Convert the 'name' field to lowercase
+ * toLower("name");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @return A new {@code Expression} representing the lowercase string.
+ */
+export function toLower(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that converts a string expression to lowercase.
+ *
+ * ```typescript
+ * // Convert the 'name' field to lowercase
+ * toLower(field("name"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to convert to lowercase.
+ * @return A new {@code Expression} representing the lowercase string.
+ */
+export function toLower(stringExpression: Expression): FunctionExpression;
+export function toLower(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).toLower();
+}
+
+/**
+ * @beta
+ * Creates an expression that converts a string field to uppercase.
+ *
+ * ```typescript
+ * // Convert the 'title' field to uppercase
+ * toUpper("title");
+ * ```
+ *
+ * @param fieldName The name of the field containing the string.
+ * @return A new {@code Expression} representing the uppercase string.
+ */
+export function toUpper(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that converts a string expression to uppercase.
+ *
+ * ```typescript
+ * // Convert the 'title' field to uppercase
+ * toUppercase(field("title"));
+ * ```
+ *
+ * @param stringExpression The expression representing the string to convert to uppercase.
+ * @return A new {@code Expression} representing the uppercase string.
+ */
+export function toUpper(stringExpression: Expression): FunctionExpression;
+export function toUpper(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).toUpper();
+}
+
+/**
+ * @beta
+ *
+ * Creates an expression that removes leading and trailing whitespace from a string or byte array.
+ *
+ * ```typescript
+ * // Trim whitespace from the 'userInput' field
+ * trim("userInput");
+ *
+ * // Trim quotes from the 'userInput' field
+ * trim("userInput", '"');
+ * ```
+ *
+ * @param fieldName The name of the field containing the string or byte array.
+ * @param valueToTrim Optional This parameter is treated as a set of characters or bytes that will be
+ * trimmed from the input. If not specified, then whitespace will be trimmed.
+ * @return A new {@code Expr} representing the trimmed string.
+ */
+export function trim(
+ fieldName: string,
+ valueToTrim?: string | Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ *
+ * Creates an expression that removes leading and trailing characters from a string or byte array expression.
+ *
+ * ```typescript
+ * // Trim whitespace from the 'userInput' field
+ * trim(field("userInput"));
+ *
+ * // Trim quotes from the 'userInput' field
+ * trim(field("userInput"), '"');
+ * ```
+ *
+ * @param stringExpression The expression representing the string or byte array to trim.
+ * @param valueToTrim Optional This parameter is treated as a set of characters or bytes that will be
+ * trimmed from the input. If not specified, then whitespace will be trimmed.
+ * @return A new {@code Expr} representing the trimmed string or byte array.
+ */
+export function trim(
+ stringExpression: Expression,
+ valueToTrim?: string | Expression,
+): FunctionExpression;
+export function trim(
+ expr: Expression | string,
+ valueToTrim?: string | Expression,
+): FunctionExpression {
+ return fieldOrExpression(expr).trim(valueToTrim);
+}
+
+/**
+ * @beta
+ * Creates an expression that concatenates string functions, fields or constants together.
+ *
+ * ```typescript
+ * // Combine the 'firstName', " ", and 'lastName' fields into a single string
+ * stringConcat("firstName", " ", field("lastName"));
+ * ```
+ *
+ * @param fieldName The field name containing the initial string value.
+ * @param secondString An expression or string literal to concatenate.
+ * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate.
+ * @return A new {@code Expression} representing the concatenated string.
+ */
+export function stringConcat(
+ fieldName: string,
+ secondString: Expression | string,
+ ...otherStrings: Array
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that concatenates string expressions together.
+ *
+ * ```typescript
+ * // Combine the 'firstName', " ", and 'lastName' fields into a single string
+ * stringConcat(field("firstName"), " ", field("lastName"));
+ * ```
+ *
+ * @param firstString The initial string expression to concatenate to.
+ * @param secondString An expression or string literal to concatenate.
+ * @param otherStrings Optional additional expressions or literals (typically strings) to concatenate.
+ * @return A new {@code Expression} representing the concatenated string.
+ */
+export function stringConcat(
+ firstString: Expression,
+ secondString: Expression | string,
+ ...otherStrings: Array
+): FunctionExpression;
+export function stringConcat(
+ first: string | Expression,
+ second: string | Expression,
+ ...elements: Array
+): FunctionExpression {
+ return fieldOrExpression(first).stringConcat(
+ valueToDefaultExpr(second),
+ ...elements.map(valueToDefaultExpr),
+ );
+}
+
+/**
+ * @beta
+ * Accesses a value from a map (object) field using the provided key.
+ *
+ * ```typescript
+ * // Get the 'city' value from the 'address' map field
+ * mapGet("address", "city");
+ * ```
+ *
+ * @param fieldName The field name of the map field.
+ * @param subField The key to access in the map.
+ * @return A new {@code Expression} representing the value associated with the given key in the map.
+ */
+export function mapGet(fieldName: string, subField: string): FunctionExpression;
+
+/**
+ * @beta
+ * Accesses a value from a map (object) expression using the provided key.
+ *
+ * ```typescript
+ * // Get the 'city' value from the 'address' map field
+ * mapGet(field("address"), "city");
+ * ```
+ *
+ * @param mapExpression The expression representing the map.
+ * @param subField The key to access in the map.
+ * @return A new {@code Expression} representing the value associated with the given key in the map.
+ */
+export function mapGet(
+ mapExpression: Expression,
+ subField: string,
+): FunctionExpression;
+export function mapGet(
+ fieldOrExpr: string | Expression,
+ subField: string,
+): FunctionExpression {
+ return fieldOrExpression(fieldOrExpr).mapGet(subField);
+}
+
+/**
+ * @beta
+ * Creates an aggregation that counts the total number of stage inputs.
+ *
+ * ```typescript
+ * // Count the total number of input documents
+ * countAll().as("totalDocument");
+ * ```
+ *
+ * @return A new {@code AggregateFunction} representing the 'countAll' aggregation.
+ */
+export function countAll(): AggregateFunction {
+ return new AggregateFunction('count', []);
+}
+
+/**
+ * @beta
+ * Creates an aggregation that counts the number of stage inputs with valid evaluations of the
+ * provided expression.
+ *
+ * ```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.
+ * @return A new {@code AggregateFunction} representing the 'count' aggregation.
+ */
+export function count(expression: Expression): AggregateFunction;
+
+/**
+ * @beta
+ * Creates an aggregation that counts the number of stage inputs where the input field exists.
+ *
+ * ```typescript
+ * // Count the total number of products
+ * count("productId").as("totalProducts");
+ * ```
+ *
+ * @param fieldName The name of the field to count.
+ * @return A new {@code AggregateFunction} representing the 'count' aggregation.
+ */
+export function count(fieldName: string): AggregateFunction;
+export function count(value: Expression | string): AggregateFunction {
+ return fieldOrExpression(value).count();
+}
+
+/**
+ * @beta
+ * Creates an aggregation that calculates the sum of values from an expression across multiple
+ * stage inputs.
+ *
+ * ```typescript
+ * // Calculate the total revenue from a set of orders
+ * sum(field("orderAmount")).as("totalRevenue");
+ * ```
+ *
+ * @param expression The expression to sum up.
+ * @return A new {@code AggregateFunction} representing the 'sum' aggregation.
+ */
+export function sum(expression: Expression): AggregateFunction;
+
+/**
+ * @beta
+ * Creates an aggregation that calculates the sum of a field's values across multiple stage
+ * inputs.
+ *
+ * ```typescript
+ * // Calculate the total revenue from a set of orders
+ * sum("orderAmount").as("totalRevenue");
+ * ```
+ *
+ * @param fieldName The name of the field containing numeric values to sum up.
+ * @return A new {@code AggregateFunction} representing the 'sum' aggregation.
+ */
+export function sum(fieldName: string): AggregateFunction;
+export function sum(value: Expression | string): AggregateFunction {
+ return fieldOrExpression(value).sum();
+}
+
+/**
+ * @beta
+ * Creates an aggregation that calculates the average (mean) of values from an expression across
+ * multiple stage inputs.
+ *
+ * ```typescript
+ * // Calculate the average age of users
+ * average(field("age")).as("averageAge");
+ * ```
+ *
+ * @param expression The expression representing the values to average.
+ * @return A new {@code AggregateFunction} representing the 'average' aggregation.
+ */
+export function average(expression: Expression): AggregateFunction;
+
+/**
+ * @beta
+ * Creates an aggregation that calculates the average (mean) of a field's values across multiple
+ * stage inputs.
+ *
+ * ```typescript
+ * // Calculate the average age of users
+ * average("age").as("averageAge");
+ * ```
+ *
+ * @param fieldName The name of the field containing numeric values to average.
+ * @return A new {@code AggregateFunction} representing the 'average' aggregation.
+ */
+export function average(fieldName: string): AggregateFunction;
+export function average(value: Expression | string): AggregateFunction {
+ return fieldOrExpression(value).average();
+}
+
+/**
+ * @beta
+ * Creates an aggregation that finds the minimum value of an expression across multiple stage
+ * inputs.
+ *
+ * ```typescript
+ * // Find the lowest price of all products
+ * minimum(field("price")).as("lowestPrice");
+ * ```
+ *
+ * @param expression The expression to find the minimum value of.
+ * @return A new {@code AggregateFunction} representing the 'min' aggregation.
+ */
+export function minimum(expression: Expression): AggregateFunction;
+
+/**
+ * @beta
+ * Creates an aggregation that finds the minimum value of a field across multiple stage inputs.
+ *
+ * ```typescript
+ * // Find the lowest price of all products
+ * minimum("price").as("lowestPrice");
+ * ```
+ *
+ * @param fieldName The name of the field to find the minimum value of.
+ * @return A new {@code AggregateFunction} representing the 'min' aggregation.
+ */
+export function minimum(fieldName: string): AggregateFunction;
+export function minimum(value: Expression | string): AggregateFunction {
+ return fieldOrExpression(value).minimum();
+}
+
+/**
+ * @beta
+ * Creates an aggregation that finds the maximum value of an expression across multiple stage
+ * inputs.
+ *
+ * ```typescript
+ * // Find the highest score in a leaderboard
+ * maximum(field("score")).as("highestScore");
+ * ```
+ *
+ * @param expression The expression to find the maximum value of.
+ * @return A new {@code AggregateFunction} representing the 'max' aggregation.
+ */
+export function maximum(expression: Expression): AggregateFunction;
+
+/**
+ * @beta
+ * Creates an aggregation that finds the maximum value of a field across multiple stage inputs.
+ *
+ * ```typescript
+ * // Find the highest score in a leaderboard
+ * maximum("score").as("highestScore");
+ * ```
+ *
+ * @param fieldName The name of the field to find the maximum value of.
+ * @return A new {@code AggregateFunction} representing the 'max' aggregation.
+ */
+export function maximum(fieldName: string): AggregateFunction;
+export function maximum(value: Expression | string): AggregateFunction {
+ return fieldOrExpression(value).maximum();
+}
+
+/**
+ * @beta
+ * Calculates the Cosine distance between a field's vector value and a literal vector value.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the Cosine distance between the two vectors.
+ */
+export function cosineDistance(
+ fieldName: string,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Cosine distance between a field's vector value and a vector expression.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the cosine distance between the two vectors.
+ */
+export function cosineDistance(
+ fieldName: string,
+ vectorExpression: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Cosine distance between a vector expression and a vector literal.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the cosine distance between the two vectors.
+ */
+export function cosineDistance(
+ vectorExpression: Expression,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Cosine distance between two vector expressions.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the cosine distance between the two vectors.
+ */
+export function cosineDistance(
+ vectorExpression: Expression,
+ otherVectorExpression: Expression,
+): FunctionExpression;
+export function cosineDistance(
+ expr: Expression | string,
+ other: Expression | number[] | firestore.VectorValue,
+): FunctionExpression {
+ const expr1 = fieldOrExpression(expr);
+ const expr2 = vectorToExpr(other);
+ return expr1.cosineDistance(expr2);
+}
+
+/**
+ * @beta
+ * Calculates the dot product between a field's vector value and a double array.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the dot product between the two vectors.
+ */
+export function dotProduct(
+ fieldName: string,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the dot product between a field's vector value and a vector expression.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the dot product between the two vectors.
+ */
+export function dotProduct(
+ fieldName: string,
+ vectorExpression: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the dot product between a vector expression and a double array.
+ *
+ * ```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 VectorValue) to calculate with.
+ * @return A new {@code Expression} representing the dot product between the two vectors.
+ */
+export function dotProduct(
+ vectorExpression: Expression,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the dot product between two vector expressions.
+ *
+ * ```typescript
+ * // Calculate the dot product between two document vectors: 'docVector1' and 'docVector2'
+ * dotProduct(field("docVector1"), field("docVector2"));
+ * ```
+ *
+ * @param vectorExpression The first vector (represented as an Expression) to calculate with.
+ * @param otherVectorExpression The other vector (represented as an Expression) to calculate with.
+ * @return A new {@code Expression} representing the dot product between the two vectors.
+ */
+export function dotProduct(
+ vectorExpression: Expression,
+ otherVectorExpression: Expression,
+): FunctionExpression;
+export function dotProduct(
+ expr: Expression | string,
+ other: Expression | number[] | VectorValue,
+): FunctionExpression {
+ const expr1 = fieldOrExpression(expr);
+ const expr2 = vectorToExpr(other);
+ return expr1.dotProduct(expr2);
+}
+
+/**
+ * @beta
+ * Calculates the Euclidean distance between a field's vector value and a double array.
+ *
+ * ```typescript
+ * // Calculate the Euclidean distance between the 'location' field and a target location
+ * euclideanDistance("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 VectorValue) to compare against.
+ * @return A new {@code Expression} representing the Euclidean distance between the two vectors.
+ */
+export function euclideanDistance(
+ fieldName: string,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Euclidean distance between a field's vector value and a vector expression.
+ *
+ * ```typescript
+ * // Calculate the Euclidean distance between two vector fields: 'pointA' and 'pointB'
+ * euclideanDistance("pointA", field("pointB"));
+ * ```
+ *
+ * @param fieldName The name of the field containing the first vector.
+ * @param vectorExpression The other vector (represented as an Expression) to compare against.
+ * @return A new {@code Expression} representing the Euclidean distance between the two vectors.
+ */
+export function euclideanDistance(
+ fieldName: string,
+ vectorExpression: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Euclidean distance between a vector expression and a double array.
+ *
+ * ```typescript
+ * // Calculate the Euclidean distance between the 'location' field and a target location
+ *
+ * euclideanDistance(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.
+ * @return A new {@code Expression} representing the Euclidean distance between the two vectors.
+ */
+export function euclideanDistance(
+ vectorExpression: Expression,
+ vector: number[] | VectorValue,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Calculates the Euclidean distance between two vector expressions.
+ *
+ * ```typescript
+ * // Calculate the Euclidean distance between two vector fields: 'pointA' and 'pointB'
+ * euclideanDistance(field("pointA"), field("pointB"));
+ * ```
+ *
+ * @param vectorExpression The first vector (represented as an Expression) to compare against.
+ * @param otherVectorExpression The other vector (represented as an Expression) to compare against.
+ * @return A new {@code Expression} representing the Euclidean distance between the two vectors.
+ */
+export function euclideanDistance(
+ vectorExpression: Expression,
+ otherVectorExpression: Expression,
+): FunctionExpression;
+export function euclideanDistance(
+ expr: Expression | string,
+ other: Expression | number[] | VectorValue,
+): FunctionExpression {
+ const expr1 = fieldOrExpression(expr);
+ const expr2 = vectorToExpr(other);
+ return expr1.euclideanDistance(expr2);
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of a Firestore Vector.
+ *
+ * ```typescript
+ * // Get the vector length (dimension) of the field 'embedding'.
+ * vectorLength(field("embedding"));
+ * ```
+ *
+ * @param vectorExpression The expression representing the Firestore Vector.
+ * @return A new {@code Expression} representing the length of the array.
+ */
+export function vectorLength(vectorExpression: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of a Firestore Vector represented by a field.
+ *
+ * ```typescript
+ * // Get the vector length (dimension) of the field 'embedding'.
+ * vectorLength("embedding");
+ * ```
+ *
+ * @param fieldName The name of the field representing the Firestore Vector.
+ * @return A new {@code Expression} representing the length of the array.
+ */
+export function vectorLength(fieldName: string): FunctionExpression;
+export function vectorLength(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).vectorLength();
+}
+
+/**
+ * @beta
+ * Creates an expression that interprets an expression as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'microseconds' field as microseconds since epoch.
+ * unixMicrosToTimestamp(field("microseconds"));
+ * ```
+ *
+ * @param expr The expression representing the number of microseconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixMicrosToTimestamp(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that interprets a field's value as the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'microseconds' field as microseconds since epoch.
+ * unixMicrosToTimestamp("microseconds");
+ * ```
+ *
+ * @param fieldName The name of the field representing the number of microseconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixMicrosToTimestamp(fieldName: string): FunctionExpression;
+export function unixMicrosToTimestamp(
+ expr: Expression | string,
+): FunctionExpression {
+ return fieldOrExpression(expr).unixMicrosToTimestamp();
+}
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp expression to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to microseconds since epoch.
+ * timestampToUnixMicros(field("timestamp"));
+ * ```
+ *
+ * @param expr The expression representing the timestamp.
+ * @return A new {@code Expression} representing the number of microseconds since epoch.
+ */
+export function timestampToUnixMicros(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp field to the number of microseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to microseconds since epoch.
+ * timestampToUnixMicros("timestamp");
+ * ```
+ *
+ * @param fieldName The name of the field representing the timestamp.
+ * @return A new {@code Expression} representing the number of microseconds since epoch.
+ */
+export function timestampToUnixMicros(fieldName: string): FunctionExpression;
+export function timestampToUnixMicros(
+ expr: Expression | string,
+): FunctionExpression {
+ return fieldOrExpression(expr).timestampToUnixMicros();
+}
+
+/**
+ * @beta
+ * Creates an expression that interprets an expression as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'milliseconds' field as milliseconds since epoch.
+ * unixMillisToTimestamp(field("milliseconds"));
+ * ```
+ *
+ * @param expr The expression representing the number of milliseconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixMillisToTimestamp(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that interprets a field's value as the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'milliseconds' field as milliseconds since epoch.
+ * unixMillisToTimestamp("milliseconds");
+ * ```
+ *
+ * @param fieldName The name of the field representing the number of milliseconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixMillisToTimestamp(fieldName: string): FunctionExpression;
+export function unixMillisToTimestamp(
+ expr: Expression | string,
+): FunctionExpression {
+ const normalizedExpr = fieldOrExpression(expr);
+ return normalizedExpr.unixMillisToTimestamp();
+}
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp expression to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to milliseconds since epoch.
+ * timestampToUnixMillis(field("timestamp"));
+ * ```
+ *
+ * @param expr The expression representing the timestamp.
+ * @return A new {@code Expression} representing the number of milliseconds since epoch.
+ */
+export function timestampToUnixMillis(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp field to the number of milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to milliseconds since epoch.
+ * timestampToUnixMillis("timestamp");
+ * ```
+ *
+ * @param fieldName The name of the field representing the timestamp.
+ * @return A new {@code Expression} representing the number of milliseconds since epoch.
+ */
+export function timestampToUnixMillis(fieldName: string): FunctionExpression;
+export function timestampToUnixMillis(
+ expr: Expression | string,
+): FunctionExpression {
+ const normalizedExpr = fieldOrExpression(expr);
+ return normalizedExpr.timestampToUnixMillis();
+}
+
+/**
+ * @beta
+ * Creates an expression that interprets an expression as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'seconds' field as seconds since epoch.
+ * unixSecondsToTimestamp(field("seconds"));
+ * ```
+ *
+ * @param expr The expression representing the number of seconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixSecondsToTimestamp(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that interprets a field's value as the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC)
+ * and returns a timestamp.
+ *
+ * ```typescript
+ * // Interpret the 'seconds' field as seconds since epoch.
+ * unixSecondsToTimestamp("seconds");
+ * ```
+ *
+ * @param fieldName The name of the field representing the number of seconds since epoch.
+ * @return A new {@code Expression} representing the timestamp.
+ */
+export function unixSecondsToTimestamp(fieldName: string): FunctionExpression;
+export function unixSecondsToTimestamp(
+ expr: Expression | string,
+): FunctionExpression {
+ const normalizedExpr = fieldOrExpression(expr);
+ return normalizedExpr.unixSecondsToTimestamp();
+}
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp expression to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to seconds since epoch.
+ * timestampToUnixSeconds(field("timestamp"));
+ * ```
+ *
+ * @param expr The expression representing the timestamp.
+ * @return A new {@code Expression} representing the number of seconds since epoch.
+ */
+export function timestampToUnixSeconds(expr: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that converts a timestamp field to the number of seconds since the Unix epoch (1970-01-01 00:00:00 UTC).
+ *
+ * ```typescript
+ * // Convert the 'timestamp' field to seconds since epoch.
+ * timestampToUnixSeconds("timestamp");
+ * ```
+ *
+ * @param fieldName The name of the field representing the timestamp.
+ * @return A new {@code Expression} representing the number of seconds since epoch.
+ */
+export function timestampToUnixSeconds(fieldName: string): FunctionExpression;
+export function timestampToUnixSeconds(
+ expr: Expression | string,
+): FunctionExpression {
+ const normalizedExpr = fieldOrExpression(expr);
+ return normalizedExpr.timestampToUnixSeconds();
+}
+
+/**
+ * @beta
+ * Creates an expression that adds a specified amount of time to a timestamp.
+ *
+ * ```typescript
+ * // Add some duration determined by field 'unit' and 'amount' to the 'timestamp' field.
+ * timestampAdd(field("timestamp"), field("unit"), field("amount"));
+ * ```
+ *
+ * @param timestamp The expression representing the timestamp.
+ * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
+ * @param amount The expression evaluates to amount of the unit.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampAdd(
+ timestamp: Expression,
+ unit: Expression,
+ amount: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that adds a specified amount of time to a timestamp.
+ *
+ * ```typescript
+ * // Add 1 day to the 'timestamp' field.
+ * timestampAdd(field("timestamp"), "day", 1);
+ * ```
+ *
+ * @param timestamp The expression representing the timestamp.
+ * @param unit The unit of time to add (e.g., "day", "hour").
+ * @param amount The amount of time to add.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampAdd(
+ timestamp: Expression,
+ unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day',
+ amount: number,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that adds a specified amount of time to a timestamp represented by a field.
+ *
+ * ```typescript
+ * // Add 1 day to the 'timestamp' field.
+ * timestampAdd("timestamp", "day", 1);
+ * ```
+ *
+ * @param fieldName The name of the field representing the timestamp.
+ * @param unit The unit of time to add (e.g., "day", "hour").
+ * @param amount The amount of time to add.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampAdd(
+ fieldName: string,
+ unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day',
+ amount: number,
+): FunctionExpression;
+export function timestampAdd(
+ timestamp: Expression | string,
+ unit:
+ | Expression
+ | 'microsecond'
+ | 'millisecond'
+ | 'second'
+ | 'minute'
+ | 'hour'
+ | 'day',
+ amount: Expression | number,
+): FunctionExpression {
+ const normalizedTimestamp = fieldOrExpression(timestamp);
+ const normalizedUnit = valueToDefaultExpr(unit);
+ const normalizedAmount = valueToDefaultExpr(amount);
+ return normalizedTimestamp.timestampAdd(normalizedUnit, normalizedAmount);
+}
+
+/**
+ * @beta
+ * Creates an expression that subtracts a specified amount of time from a timestamp.
+ *
+ * ```typescript
+ * // Subtract some duration determined by field 'unit' and 'amount' from the 'timestamp' field.
+ * timestampSubtract(field("timestamp"), field("unit"), field("amount"));
+ * ```
+ *
+ * @param timestamp The expression representing the timestamp.
+ * @param unit The expression evaluates to unit of time, must be one of 'microsecond', 'millisecond', 'second', 'minute', 'hour', 'day'.
+ * @param amount The expression evaluates to amount of the unit.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampSubtract(
+ timestamp: Expression,
+ unit: Expression,
+ amount: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that subtracts a specified amount of time from a timestamp.
+ *
+ * ```typescript
+ * // Subtract 1 day from the 'timestamp' field.
+ * timestampSubtract(field("timestamp"), "day", 1);
+ * ```
+ *
+ * @param timestamp The expression representing the timestamp.
+ * @param unit The unit of time to subtract (e.g., "day", "hour").
+ * @param amount The amount of time to subtract.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampSubtract(
+ timestamp: Expression,
+ unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day',
+ amount: number,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that subtracts a specified amount of time from a timestamp represented by a field.
+ *
+ * ```typescript
+ * // Subtract 1 day from the 'timestamp' field.
+ * timestampSubtract("timestamp", "day", 1);
+ * ```
+ *
+ * @param fieldName The name of the field representing the timestamp.
+ * @param unit The unit of time to subtract (e.g., "day", "hour").
+ * @param amount The amount of time to subtract.
+ * @return A new {@code Expression} representing the resulting timestamp.
+ */
+export function timestampSubtract(
+ fieldName: string,
+ unit: 'microsecond' | 'millisecond' | 'second' | 'minute' | 'hour' | 'day',
+ amount: number,
+): FunctionExpression;
+export function timestampSubtract(
+ timestamp: Expression | string,
+ unit:
+ | Expression
+ | 'microsecond'
+ | 'millisecond'
+ | 'second'
+ | 'minute'
+ | 'hour'
+ | 'day',
+ amount: Expression | number,
+): FunctionExpression {
+ const normalizedTimestamp = fieldOrExpression(timestamp);
+ const normalizedUnit = valueToDefaultExpr(unit);
+ const normalizedAmount = valueToDefaultExpr(amount);
+ return normalizedTimestamp.timestampSubtract(
+ normalizedUnit,
+ normalizedAmount,
+ );
+}
+
+/**
+ * @beta
+ *
+ * Creates an expression that evaluates to the current server timestamp.
+ *
+ * ```typescript
+ * // Get the current server timestamp
+ * currentTimestamp()
+ * ```
+ *
+ * @return A new Expression representing the current server timestamp.
+ */
+export function currentTimestamp(): FunctionExpression {
+ return new FunctionExpression('current_timestamp', []);
+}
+
+/**
+ * @beta
+ * Creates an expression that performs a logical 'AND' operation on multiple filter conditions.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the logical 'AND' operation.
+ */
+export function and(
+ first: BooleanExpression,
+ second: BooleanExpression,
+ ...more: BooleanExpression[]
+): BooleanExpression {
+ return new FunctionExpression('and', [first, second, ...more]).asBoolean();
+}
+
+/**
+ * @beta
+ * Creates an expression that performs a logical 'OR' operation on multiple filter conditions.
+ *
+ * ```typescript
+ * // Check if the 'age' field is greater than 18 OR the 'city' field is "London" OR
+ * // the 'status' field is "active"
+ * const condition = or(greaterThan("age", 18), equal("city", "London"), equal("status", "active"));
+ * ```
+ *
+ * @param first The first filter condition.
+ * @param second The second filter condition.
+ * @param more Additional filter conditions to 'OR' together.
+ * @return A new {@code Expression} representing the logical 'OR' operation.
+ */
+export function or(
+ first: BooleanExpression,
+ second: BooleanExpression,
+ ...more: BooleanExpression[]
+): BooleanExpression {
+ return new FunctionExpression('or', [first, second, ...more]).asBoolean();
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the value of the base expression raised to the power of the exponent expression.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of the 'exponent' field.
+ * pow(field("base"), field("exponent"));
+ * ```
+ *
+ * @param base The expression to raise to the power of the exponent.
+ * @param exponent The expression to raise the base to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+export function pow(base: Expression, exponent: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the value of the base expression raised to the power of the exponent.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of 2.
+ * pow(field("base"), 2);
+ * ```
+ *
+ * @param base The expression to raise to the power of the exponent.
+ * @param exponent The constant value to raise the base to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+export function pow(base: Expression, exponent: number): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the value of the base field raised to the power of the exponent expression.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of the 'exponent' field.
+ * pow("base", field("exponent"));
+ * ```
+ *
+ * @param base The name of the field to raise to the power of the exponent.
+ * @param exponent The expression to raise the base to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+export function pow(base: string, exponent: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the value of the base field raised to the power of the exponent.
+ *
+ * ```typescript
+ * // Raise the value of the 'base' field to the power of 2.
+ * pow("base", 2);
+ * ```
+ *
+ * @param base The name of the field to raise to the power of the exponent.
+ * @param exponent The constant value to raise the base to the power of.
+ * @return A new `Expression` representing the power operation.
+ */
+export function pow(base: string, exponent: number): FunctionExpression;
+export function pow(
+ base: Expression | string,
+ exponent: Expression | number,
+): FunctionExpression {
+ return fieldOrExpression(base).pow(exponent as number);
+}
+
+/**
+ * @beta
+ * Creates an expression that rounds a numeric value to the nearest whole number.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field.
+ * round("price");
+ * ```
+ *
+ * @param fieldName The name of the field to round.
+ * @return A new `Expression` representing the rounded value.
+ */
+export function round(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that rounds a numeric value to the nearest whole number.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field.
+ * round(field("price"));
+ * ```
+ *
+ * @param expression An expression evaluating to a numeric value, which will be rounded.
+ * @return A new `Expression` representing the rounded value.
+ */
+export function round(expression: Expression): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that rounds a numeric value to the specified number of decimal places.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field to two decimal places.
+ * round("price", 2);
+ * ```
+ *
+ * @param fieldName The name of the field to round.
+ * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places.
+ * @return A new `Expr` representing the rounded value.
+ */
+export function round(
+ fieldName: string,
+ decimalPlaces: number | Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that rounds a numeric value to the specified number of decimal places.
+ *
+ * ```typescript
+ * // Round the value of the 'price' field to two decimal places.
+ * round(field("price"), constant(2));
+ * ```
+ *
+ * @param expression An expression evaluating to a numeric value, which will be rounded.
+ * @param decimalPlaces A constant or expression specifying the rounding precision in decimal places.
+ * @return A new `Expr` representing the rounded value.
+ */
+export function round(
+ expression: Expression,
+ decimalPlaces: number | Expression,
+): FunctionExpression;
+export function round(
+ expr: Expression | string,
+ decimalPlaces?: number | Expression,
+): FunctionExpression {
+ if (decimalPlaces === undefined) {
+ return fieldOrExpression(expr).round();
+ } else {
+ return fieldOrExpression(expr).round(valueToDefaultExpr(decimalPlaces));
+ }
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the collection ID from a path.
+ *
+ * ```typescript
+ * // Get the collection ID from a path.
+ * collectionId("__name__");
+ * ```
+ *
+ * @param fieldName The name of the field to get the collection ID from.
+ * @return A new {@code Expression} representing the collectionId operation.
+ */
+export function collectionId(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that returns the collection ID from a path.
+ *
+ * ```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.
+ * @return A new {@code Expression} representing the collectionId operation.
+ */
+export function collectionId(expression: Expression): FunctionExpression;
+export function collectionId(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).collectionId();
+}
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of a string, array, map, vector, or bytes.
+ *
+ * ```typescript
+ * // Get the length of the 'name' field.
+ * length("name");
+ *
+ * // Get the number of items in the 'cart' array.
+ * length("cart");
+ * ```
+ *
+ * @param fieldName The name of the field to calculate the length of.
+ * @return A new `Expression` representing the length of the string, array, map, vector, or bytes.
+ */
+export function length(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that calculates the length of a string, array, map, vector, or bytes.
+ *
+ * ```typescript
+ * // Get the length of the 'name' field.
+ * length(field("name"));
+ *
+ * // Get the number of items in the 'cart' array.
+ * length(field("cart"));
+ * ```
+ *
+ * @param expression An expression evaluating to a string, array, map, vector, or bytes, which the length will be calculated for.
+ * @return A new `Expression` representing the length of the string, array, map, vector, or bytes.
+ */
+export function length(expression: Expression): FunctionExpression;
+export function length(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).length();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the natural logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the natural logarithm of the 'value' field.
+ * ln("value");
+ * ```
+ *
+ * @param fieldName The name of the field to compute the natural logarithm of.
+ * @return A new `Expression` representing the natural logarithm of the numeric value.
+ */
+export function ln(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes the natural logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the natural logarithm of the 'value' field.
+ * ln(field("value"));
+ * ```
+ *
+ * @param expression An expression evaluating to a numeric value, which the natural logarithm will be computed for.
+ * @return A new `Expression` representing the natural logarithm of the numeric value.
+ */
+export function ln(expression: Expression): FunctionExpression;
+export function ln(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).ln();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the square root of a numeric value.
+ *
+ * ```typescript
+ * // Compute the square root of the 'value' field.
+ * sqrt(field("value"));
+ * ```
+ *
+ * @param expression An expression evaluating to a numeric value, which the square root will be computed for.
+ * @return A new {@code Expression} representing the square root of the numeric value.
+ */
+export function sqrt(expression: Expression): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that computes the square root of a numeric value.
+ *
+ * ```typescript
+ * // Compute the square root of the 'value' field.
+ * sqrt("value");
+ * ```
+ *
+ * @param fieldName The name of the field to compute the square root of.
+ * @return A new {@code Expression} representing the square root of the numeric value.
+ */
+export function sqrt(fieldName: string): FunctionExpression;
+export function sqrt(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).sqrt();
+}
+
+/**
+ * @beta
+ * Creates an expression that reverses a string.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myString' field.
+ * stringReverse(field("myString"));
+ * ```
+ *
+ * @param stringExpression An expression evaluating to a string value, which will be reversed.
+ * @return A new {@code Expression} representing the reversed string.
+ */
+export function stringReverse(stringExpression: Expression): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that reverses a string value in the specified field.
+ *
+ * ```typescript
+ * // Reverse the value of the 'myString' field.
+ * stringReverse("myString");
+ * ```
+ *
+ * @param field The name of the field representing the string to reverse.
+ * @return A new {@code Expression} representing the reversed string.
+ */
+export function stringReverse(field: string): FunctionExpression;
+export function stringReverse(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).stringReverse();
+}
+
+/**
+ * @beta
+ * Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
+ *
+ * ```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.
+ * @return A new `Expression` representing the concatenation.
+ */
+export function concat(
+ first: Expression,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that concatenates strings, arrays, or blobs. Types cannot be mixed.
+ *
+ * ```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.
+ * @return A new `Expression` representing the concatenation.
+ */
+export function concat(
+ fieldName: string,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression;
+
+export function concat(
+ fieldNameOrExpression: string | Expression,
+ second: Expression | unknown,
+ ...others: Array
+): FunctionExpression {
+ return fieldOrExpression(fieldNameOrExpression).concat(
+ valueToDefaultExpr(second),
+ ...others.map(valueToDefaultExpr),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the absolute value of a numeric value.
+ *
+ * @param expr The expression to compute the absolute value of.
+ * @return A new {@code Expr} representing the absolute value of the numeric value.
+ */
+export 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.
+ * @return A new {@code Expr} representing the absolute value of the numeric value.
+ */
+export function abs(fieldName: string): FunctionExpression;
+export function abs(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).abs();
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseExpr` argument if `ifExpr` is absent, else return
+ * the result of the `ifExpr` argument evaluation.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or returns 'default_value'
+ * // if the field is absent.
+ * ifAbsent(field("optional_field"), constant("default_value"))
+ * ```
+ *
+ * @param ifExpr The expression to check for absence.
+ * @param elseExpr The expression that will be evaluated and returned if [ifExpr] is absent.
+ * @return A new Expression representing the ifAbsent operation.
+ */
+export function ifAbsent(ifExpr: Expression, elseExpr: Expression): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if `ifExpr` is absent, else
+ * return the result of the `ifExpr` argument evaluation.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or returns 'default_value'
+ * // if the field is absent.
+ * ifAbsent(field("optional_field"), "default_value")
+ * ```
+ *
+ * @param ifExpr The expression to check for absence.
+ * @param elseValue The value that will be returned if `ifExpr` evaluates to an absent value.
+ * @return A new [Expression] representing the ifAbsent operation.
+ */
+export function ifAbsent(ifExpr: Expression, elseValue: unknown): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseExpr` argument if `ifFieldName` is absent, else
+ * return the value of the field.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or returns the value of
+ * // 'default_field' if 'optional_field' is absent.
+ * ifAbsent("optional_field", field("default_field"))
+ * ```
+ *
+ * @param ifFieldName The field to check for absence.
+ * @param elseExpr The expression that will be evaluated and returned if `ifFieldName` is
+ * absent.
+ * @return A new Expression representing the ifAbsent operation.
+ */
+export function ifAbsent(ifFieldName: string, elseExpr: Expression): Expression;
+
+/**
+ * @beta
+ * Creates an expression that returns the `elseValue` argument if `ifFieldName` is absent, else
+ * return the value of the field.
+ *
+ * ```typescript
+ * // Returns the value of the optional field 'optional_field', or returns 'default_value'
+ * // if the field is absent.
+ * ifAbsent("optional_field", "default_value")
+ * ```
+ *
+ * @param ifFieldName The field to check for absence.
+ * @param elseValue The value that will be returned if [ifFieldName] is absent.
+ * @return A new Expression representing the ifAbsent operation.
+ */
+export function ifAbsent(
+ ifFieldName: string | Expression,
+ elseValue: Expression | unknown,
+): Expression;
+export function ifAbsent(
+ fieldNameOrExpression: string | Expression,
+ elseValue: Expression | unknown,
+): Expression {
+ return fieldOrExpression(fieldNameOrExpression).ifAbsent(
+ valueToDefaultExpr(elseValue),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that joins the elements of an array into a string.
+ *
+ * ```typescript
+ * // Join the elements of the 'tags' field with a comma and space.
+ * join("tags", ", ")
+ * ```
+ *
+ * @param arrayFieldName The name of the field containing the array.
+ * @param delimiter The string to use as a delimiter.
+ * @return A new Expression representing the join operation.
+ */
+export function join(arrayFieldName: string, delimiter: string): Expression;
+
+/**
+ * @beta
+ * Creates an expression that joins the elements of an array into a string.
+ *
+ * ```typescript
+ * // Join an array of string using the delimiter from the 'separator' field.
+ * join(array(['foo', 'bar']), field("separator"))
+ * ```
+ *
+ * @param arrayExpression An expression that evaluates to an array.
+ * @param delimiterExpression The expression that evaluates to the delimiter string.
+ * @return A new Expression representing the join operation.
+ */
+export function join(
+ arrayExpression: Expression,
+ delimiterExpression: Expression,
+): Expression;
+
+/**
+ * @beta
+ * Creates an expression that joins the elements of an array into a string.
+ *
+ * ```typescript
+ * // Join the elements of the 'tags' field with a comma and space.
+ * join(field("tags"), ", ")
+ * ```
+ *
+ * @param arrayExpression An expression that evaluates to an array.
+ * @param delimiter The string to use as a delimiter.
+ * @return A new Expression representing the join operation.
+ */
+export function join(
+ arrayExpression: Expression,
+ delimiter: string,
+): Expression;
+
+/**
+ * @beta
+ * Creates an expression that joins the elements of an array into a string.
+ *
+ * ```typescript
+ * // Join the elements of the 'tags' field with the delimiter from the 'separator' field.
+ * join('tags', field("separator"))
+ * ```
+ *
+ * @param arrayFieldName The name of the field containing the array.
+ * @param delimiterExpression The expression that evaluates to the delimiter string.
+ * @return A new Expression representing the join operation.
+ */
+export function join(
+ arrayFieldName: string,
+ delimiterExpression: Expression,
+): Expression;
+export function join(
+ fieldNameOrExpression: string | Expression,
+ delimiterValueOrExpression: Expression | string,
+): Expression {
+ return fieldOrExpression(fieldNameOrExpression).join(
+ valueToDefaultExpr(delimiterValueOrExpression),
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the base-10 logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the base-10 logarithm of the 'value' field.
+ * log10("value");
+ * ```
+ *
+ * @param fieldName The name of the field to compute the base-10 logarithm of.
+ * @return A new `Expr` representing the base-10 logarithm of the numeric value.
+ */
+export function log10(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes the base-10 logarithm of a numeric value.
+ *
+ * ```typescript
+ * // Compute the base-10 logarithm of the 'value' field.
+ * log10(field("value"));
+ * ```
+ *
+ * @param expression An expression evaluating to a numeric value, which the base-10 logarithm will be computed for.
+ * @return A new `Expr` representing the base-10 logarithm of the numeric value.
+ */
+export function log10(expression: Expression): FunctionExpression;
+export function log10(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).log10();
+}
+
+/**
+ * @beta
+ * Creates an expression that computes the sum of the elements in an array.
+ *
+ * ```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.
+ * @return A new `Expr` representing the sum of the elements in the array.
+ */
+export function arraySum(fieldName: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that computes the sum of the elements in an array.
+ *
+ * ```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.
+ * @return A new `Expr` representing the sum of the elements in the array.
+ */
+export function arraySum(expression: Expression): FunctionExpression;
+export function arraySum(expr: Expression | string): FunctionExpression {
+ return fieldOrExpression(expr).arraySum();
+}
+/**
+ * @beta
+ * Creates an expression that splits the value of a field on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scoresCsv' field on delimiter ','
+ * split('scoresCsv', ',')
+ * ```
+ *
+ * @param fieldName Split the value in this field.
+ * @param delimiter Split on this delimiter.
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+export function split(fieldName: string, delimiter: string): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that splits the value of a field on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scores' field on delimiter ',' or ':' depending on the stored format
+ * split('scores', conditional(field('format').equal('csv'), constant(','), constant(':'))
+ * ```
+ *
+ * @param fieldName Split the value in this field.
+ * @param delimiter Split on this delimiter returned by evaluating this expression.
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+export function split(
+ fieldName: string,
+ delimiter: Expression,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that splits a string into an array of substrings based on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scoresCsv' field on delimiter ','
+ * split(field('scoresCsv'), ',')
+ * ```
+ *
+ * @param expression Split the result of this expression.
+ * @param delimiter Split on this delimiter.
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+export function split(
+ expression: Expression,
+ delimiter: string,
+): FunctionExpression;
+
+/**
+ * @beta
+ * Creates an expression that splits a string into an array of substrings based on the provided delimiter.
+ *
+ * @example
+ * ```typescript
+ * // Split the 'scores' field on delimiter ',' or ':' depending on the stored format
+ * split(field('scores'), conditional(field('format').equal('csv'), constant(','), constant(':'))
+ * ```
+ *
+ * @param expression Split the result of this expression.
+ * @param delimiter Split on this delimiter returned by evaluating this expression.
+ *
+ * @return A new {@code Expression} representing the split function.
+ */
+export function split(
+ expression: Expression,
+ delimiter: Expression,
+): FunctionExpression;
+export function split(
+ fieldNameOrExpression: string | Expression,
+ delimiter: string | Expression,
+): FunctionExpression {
+ return fieldOrExpression(fieldNameOrExpression).split(
+ valueToDefaultExpr(delimiter),
+ );
+}
+
+/**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the beginning of the day.
+ * field('createdAt').timestampTruncate('day')
+ * ```
+ *
+ * @param fieldName Truncate the timestamp value contained in this field.
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+export function timestampTruncate(
+ fieldName: string,
+ granularity: firestore.Pipelines.TimeGranularity,
+ timezone?: string | Expression,
+): FunctionExpression;
+
+/**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'.
+ * field('createdAt').timestampTruncate(field('granularity'))
+ * ```
+ *
+ * @param fieldName Truncate the timestamp value contained in this field.
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+export function timestampTruncate(
+ fieldName: string,
+ granularity: Expression,
+ timezone?: string | Expression,
+): FunctionExpression;
+
+/**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the beginning of the day.
+ * field('createdAt').timestampTruncate('day')
+ * ```
+ *
+ * @param timestampExpression Truncate the timestamp value that is returned by this expression.
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+export function timestampTruncate(
+ timestampExpression: Expression,
+ granularity: firestore.Pipelines.TimeGranularity,
+ timezone?: string | Expression,
+): FunctionExpression;
+
+/**
+ * Creates an expression that truncates a timestamp to a specified granularity.
+ *
+ * @example
+ * ```typescript
+ * // Truncate the 'createdAt' timestamp to the granularity specified in the field 'granularity'.
+ * field('createdAt').timestampTruncate(field('granularity'))
+ * ```
+ *
+ * @param timestampExpression Truncate the timestamp value that is returned by this expression.
+ * @param granularity The granularity to truncate to.
+ * @param timezone The timezone to use for truncation. Valid values are from
+ * the TZ database (e.g., "America/Los_Angeles") or in the format "Etc/GMT-1".
+ * @return A new {Expression} representing the truncated timestamp.
+ */
+export function timestampTruncate(
+ timestampExpression: Expression,
+ granularity: Expression,
+ timezone?: string | Expression,
+): FunctionExpression;
+export function timestampTruncate(
+ fieldNameOrExpression: string | Expression,
+ granularity: firestore.Pipelines.TimeGranularity | Expression,
+ timezone?: string | Expression,
+): FunctionExpression {
+ const internalGranularity = isString(granularity)
+ ? valueToDefaultExpr(granularity.toLowerCase())
+ : granularity;
+ return fieldOrExpression(fieldNameOrExpression).timestampTruncate(
+ internalGranularity,
+ timezone,
+ );
+}
+
+/**
+ * @beta
+ * Creates an expression that returns the data type of the data in the specified field.
+ *
+ * @example
+ * ```typescript
+ * // Get the data type of the value in field 'title'
+ * type('title')
+ * ```
+ *
+ * @return A new {Expression} representing the data type.
+ */
+export function type(fieldName: string): FunctionExpression;
+/**
+ * @beta
+ * Creates an expression that returns the data type of an expression's result.
+ *
+ * @example
+ * ```typescript
+ * // Get the data type of a conditional expression
+ * type(conditional(exists('foo'), constant(1), constant(true)))
+ * ```
+ *
+ * @return A new {Expression} representing the data type.
+ */
+export function type(expression: Expression): FunctionExpression;
+export function type(
+ fieldNameOrExpression: string | Expression,
+): FunctionExpression {
+ return fieldOrExpression(fieldNameOrExpression).type();
+}
+
+// TODO(new-expression): Add new top-level expression function definitions above this line
+
+/**
+ * @beta
+ * Creates a {@link Field} instance representing the field at the given path.
+ *
+ * ```typescript
+ * // Sort documents by the 'name' field in lowercase in ascending order
+ * db.pipeline().collection("users")
+ * .sort(ascending(field("name").toLower()));
+ * ```
+ *
+ * @param expr The expression to create an ascending ordering for.
+ * @return A new `Ordering` for ascending sorting.
+ */
+export function ascending(expr: Expression): Ordering;
+
+/**
+ * @beta
+ * Creates an {@link Ordering} that sorts documents in ascending order based on a field.
+ *
+ * ```typescript
+ * // Sort documents by the 'name' field in ascending order
+ * db.pipeline().collection("users")
+ * .sort(ascending("name"));
+ * ```
+ *
+ * @param fieldName The field to create an ascending ordering for.
+ * @return A new `Ordering` for ascending sorting.
+ */
+export function ascending(fieldName: string): Ordering;
+export function ascending(field: Expression | string): Ordering {
+ return new Ordering(fieldOrExpression(field), 'ascending');
+}
+
+/**
+ * @beta
+ * Creates an {@link Ordering} that sorts documents in descending order based on an expression.
+ *
+ * ```typescript
+ * // Sort documents by the 'name' field in lowercase in descending order
+ * db.pipeline().collection("users")
+ * .sort(descending(field("name").toLower()));
+ * ```
+ *
+ * @param expr The expression to create a descending ordering for.
+ * @return A new `Ordering` for descending sorting.
+ */
+export function descending(expr: Expression): Ordering;
+
+/**
+ * @beta
+ * Creates an {@link Ordering} that sorts documents in descending order based on a field.
+ *
+ * ```typescript
+ * // Sort documents by the 'name' field in descending order
+ * db.pipeline().collection("users")
+ * .sort(descending("name"));
+ * ```
+ *
+ * @param fieldName The field to create a descending ordering for.
+ * @return A new `Ordering` for descending sorting.
+ */
+export function descending(fieldName: string): Ordering;
+export function descending(field: Expression | string): Ordering {
+ return new Ordering(fieldOrExpression(field), 'descending');
+}
+
+/**
+ * @beta
+ * Represents an ordering criterion for sorting documents in a Firestore pipeline.
+ *
+ * You create `Ordering` instances using the `ascending` and `descending` helper functions.
+ */
+export class Ordering implements HasUserData {
+ constructor(
+ readonly expr: Expression,
+ readonly direction: 'ascending' | 'descending',
+ ) {}
+
+ /**
+ * @beta
+ * @internal
+ * @private
+ * Indicates if this expression was created from a literal value passed
+ * by the caller.
+ */
+ _createdFromLiteral = false;
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _toProto(serializer: Serializer): api.IValue {
+ const expr = this.expr as Expression;
+ return {
+ mapValue: {
+ fields: {
+ direction: serializer.encodeValue(this.direction),
+ expression: expr._toProto(serializer),
+ },
+ },
+ };
+ }
+
+ _protoValueType: 'ProtoValue' = 'ProtoValue' as const;
+
+ /**
+ * @beta
+ * @private
+ * @internal
+ */
+ _validateUserData(ignoreUndefinedProperties: boolean): void {
+ (this.expr as Expression)._validateUserData(ignoreUndefinedProperties);
+ }
+}
diff --git a/dev/src/pipelines/index.ts b/dev/src/pipelines/index.ts
new file mode 100644
index 000000000..d3cd46b8f
--- /dev/null
+++ b/dev/src/pipelines/index.ts
@@ -0,0 +1,128 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export {
+ Pipeline,
+ PipelineResult,
+ PipelineSnapshot,
+ PipelineSource,
+} from './pipelines';
+
+export {
+ and,
+ arrayContains,
+ arrayContainsAny,
+ arrayReverse,
+ average,
+ equal,
+ ceil,
+ exp,
+ floor,
+ greaterThan,
+ like,
+ lessThan,
+ notEqual,
+ ascending,
+ not,
+ or,
+ regexContains,
+ regexMatch,
+ startsWith,
+ stringConcat,
+ subtract,
+ cosineDistance,
+ countDistinct,
+ dotProduct,
+ euclideanDistance,
+ mapGet,
+ lessThanOrEqual,
+ equalAny,
+ map,
+ array,
+ field,
+ xor,
+ AggregateFunction,
+ arrayGet,
+ add,
+ BooleanExpression,
+ Expression,
+ FunctionExpression,
+ minimum,
+ count,
+ countIf,
+ arrayLength,
+ stringContains,
+ charLength,
+ divide,
+ mod,
+ reverse,
+ trim,
+ toUpper,
+ toLower,
+ vectorLength,
+ exists,
+ isAbsent,
+ ifError,
+ isError,
+ substring,
+ documentId,
+ arrayContainsAll,
+ constant,
+ Field,
+ Constant,
+ sum,
+ maximum,
+ descending,
+ greaterThanOrEqual,
+ multiply,
+ conditional,
+ Ordering,
+ AliasedAggregate,
+ endsWith,
+ AliasedExpression,
+ mapMerge,
+ mapRemove,
+ byteLength,
+ logicalMaximum,
+ logicalMinimum,
+ notEqualAny,
+ countAll,
+ timestampAdd,
+ timestampSubtract,
+ timestampToUnixMicros,
+ timestampToUnixSeconds,
+ unixMicrosToTimestamp,
+ timestampToUnixMillis,
+ unixSecondsToTimestamp,
+ unixMillisToTimestamp,
+ pow,
+ collectionId,
+ length,
+ ln,
+ round,
+ sqrt,
+ stringReverse,
+ abs,
+ arraySum,
+ ifAbsent,
+ log10,
+ concat,
+ join,
+ currentTimestamp,
+ arrayConcat,
+ type,
+ timestampTruncate,
+ split,
+ // TODO(new-expression): Add new expression exports above this line
+} from './expression';
diff --git a/dev/src/pipelines/options-util.ts b/dev/src/pipelines/options-util.ts
new file mode 100644
index 000000000..bf9cc7e78
--- /dev/null
+++ b/dev/src/pipelines/options-util.ts
@@ -0,0 +1,89 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import {ObjectValue, Serializer} from '../serializer';
+import {ObjectValueFieldPath} from '../path';
+import {ApiMapValue} from '../types';
+import {isPlainObject, mapToArray} from '../util';
+import {google} from '../../protos/firestore_v1_proto_api';
+import IValue = google.firestore.v1.IValue;
+export type OptionsDefinitions = Record;
+export type OptionDefinition = {
+ serverName: string;
+ nestedOptions?: OptionsDefinitions;
+};
+
+export class OptionsUtil {
+ constructor(private optionDefinitions: OptionsDefinitions) {}
+
+ private _getKnownOptions(
+ options: Record,
+ serializer: Serializer,
+ ): ObjectValue {
+ const knownOptions: ObjectValue = ObjectValue.empty();
+
+ // SERIALIZE KNOWN OPTIONS
+ for (const knownOptionKey in this.optionDefinitions) {
+ const optionDefinition: OptionDefinition =
+ this.optionDefinitions[knownOptionKey];
+
+ if (knownOptionKey in options) {
+ const optionValue: unknown = options[knownOptionKey];
+ let protoValue: IValue | undefined = undefined;
+
+ if (optionDefinition.nestedOptions && isPlainObject(optionValue)) {
+ const nestedUtil = new OptionsUtil(optionDefinition.nestedOptions);
+ protoValue = {
+ mapValue: {
+ fields: nestedUtil.getOptionsProto(serializer, optionValue),
+ },
+ };
+ } else if (optionValue) {
+ protoValue = serializer.encodeValue(optionValue) ?? undefined;
+ }
+
+ if (protoValue) {
+ knownOptions.set(
+ new ObjectValueFieldPath(optionDefinition.serverName),
+ protoValue,
+ );
+ }
+ }
+ }
+
+ return knownOptions;
+ }
+
+ getOptionsProto(
+ serializer: Serializer,
+ knownOptions: Record,
+ optionsOverride?: Record,
+ ): ApiMapValue | undefined {
+ const result: ObjectValue = this._getKnownOptions(knownOptions, serializer);
+
+ // APPLY OPTIONS OVERRIDES
+ if (optionsOverride) {
+ const optionsMap = new Map(
+ mapToArray(optionsOverride, (value, key) => [
+ ObjectValueFieldPath.fromDotNotation(key),
+ value !== undefined ? serializer.encodeValue(value) : null,
+ ]),
+ );
+ result.setAll(optionsMap);
+ }
+
+ // Return IMapValue from `result`
+ return result.value.mapValue.fields ?? {};
+ }
+}
diff --git a/dev/src/pipelines/pipeline-util.ts b/dev/src/pipelines/pipeline-util.ts
new file mode 100644
index 000000000..f49cbcb32
--- /dev/null
+++ b/dev/src/pipelines/pipeline-util.ts
@@ -0,0 +1,765 @@
+// Copyright 2025 Google LLC
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import type * as firestore from '@google-cloud/firestore';
+import {GoogleError} from 'google-gax';
+import {Duplex, Transform} from 'stream';
+import {google} from '../../protos/firestore_v1_proto_api';
+
+import * as protos from '../../protos/firestore_v1_proto_api';
+import './expression';
+import Firestore, {
+ CollectionReference,
+ DocumentReference,
+ FieldValue,
+ Timestamp,
+ VectorValue,
+} from '../index';
+import {logger} from '../logger';
+import {FieldPath, QualifiedResourcePath} from '../path';
+import {CompositeFilterInternal} from '../reference/composite-filter-internal';
+import {NOOP_MESSAGE} from '../reference/constants';
+import {FieldFilterInternal} from '../reference/field-filter-internal';
+import {FilterInternal} from '../reference/filter-internal';
+import {
+ PipelineResponse,
+ PipelineStreamElement,
+ QueryCursor,
+} from '../reference/types';
+import {Serializer} from '../serializer';
+import {
+ Deferred,
+ getTotalTimeout,
+ isObject,
+ isPermanentRpcError,
+ isPlainObject,
+ requestTag,
+ wrapError,
+} from '../util';
+import api = protos.google.firestore.v1;
+
+import {
+ Expression,
+ BooleanExpression,
+ and,
+ or,
+ field as createField,
+ constant,
+ map,
+ array,
+ Constant,
+ field,
+ Ordering,
+ greaterThan,
+ lessThan,
+ Field,
+ AggregateFunction,
+} from './expression';
+import {Pipeline, PipelineResult, ExplainStats} from './pipelines';
+import {StructuredPipeline} from './structured-pipeline';
+import Selectable = FirebaseFirestore.Pipelines.Selectable;
+
+/**
+ * Returns a builder for DocumentSnapshot and QueryDocumentSnapshot instances.
+ * Invoke `.build()' to assemble the final snapshot.
+ *
+ * @private
+ * @internal
+ */
+export class ExecutionUtil {
+ constructor(
+ /** @private */
+ readonly _firestore: Firestore,
+ /** @private */
+ readonly _serializer: Serializer,
+ ) {}
+
+ _getResponse(
+ structuredPipeline: StructuredPipeline,
+ transactionOrReadTime?: Uint8Array | Timestamp | api.ITransactionOptions,
+ ): Promise {
+ // Capture the error stack to preserve stack tracing across async calls.
+ const stack = Error().stack!;
+
+ return new Promise((resolve, reject): void => {
+ const result: Array = [];
+ const output: PipelineResponse = {};
+
+ const stream: NodeJS.EventEmitter = this._stream(
+ structuredPipeline,
+ transactionOrReadTime,
+ );
+ stream.on('error', err => {
+ reject(wrapError(err, stack));
+ });
+ stream.on('data', (data: PipelineStreamElement[]) => {
+ for (const element of data) {
+ if (element.transaction) {
+ output.transaction = element.transaction;
+ }
+ if (element.executionTime) {
+ output.executionTime = element.executionTime;
+ }
+ if (element.explainStats) {
+ output.explainStats = element.explainStats;
+ }
+ if (element.result) {
+ result.push(element.result);
+ }
+ }
+ });
+ stream.on('end', () => {
+ output.result = result;
+ resolve(output);
+ });
+ });
+ }
+
+ // This method exists solely to enable unit tests to mock it.
+ _isPermanentRpcError(err: GoogleError, methodName: string): boolean {
+ return isPermanentRpcError(err, methodName);
+ }
+
+ _hasRetryTimedOut(methodName: string, startTime: number): boolean {
+ const totalTimeout = getTotalTimeout(methodName);
+ if (totalTimeout === 0) {
+ return false;
+ }
+
+ return Date.now() - startTime >= totalTimeout;
+ }
+
+ stream(
+ structuredPipeline: StructuredPipeline,
+ transactionOrReadTime?: Uint8Array | Timestamp | api.ITransactionOptions,
+ ): NodeJS.ReadableStream {
+ const responseStream = this._stream(
+ structuredPipeline,
+ transactionOrReadTime,
+ );
+ const transform = new Transform({
+ objectMode: true,
+ transform(chunk: Array