Casts the expression to a BooleanExpression.

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.

// Calculate total price and alias it "totalPrice"
Field("price").multiply(Field("quantity")).as("totalPrice")

Creates an expression that returns the value of self rounded to the nearest integer.

// Get the value of the "amount" field rounded to the nearest integer.
Field("amount").round()

Creates an expression that returns the square root of self.

// Get the square root of the "area" field.
Field("area").sqrt()

Creates an expression that returns the value of self raised to the power of self.

Returns zero on underflow.

// Get the value of the "amount" field raised to the power of 2.
Field("amount").pow(2)

Creates an expression that returns the value of self raised to the power of self.

Returns zero on underflow.

// Get the value of the "amount" field raised to the power of the "exponent" field.
Field("amount").pow(Field("exponent"))

Creates an expression that returns the natural logarithm of self.

// Get the natural logarithm of the "amount" field.
Field("amount").ln()

Creates an expression that returns the largest numeric value that isn’t greater than self.

// Get the floor of the "amount" field.
Field("amount").floor()

Creates an expression that returns e to the power of self.

Returns zero on underflow and nil on overflow.

// Get the exp of the "amount" field.
Field("amount").exp()

Creates an expression that returns the smallest numeric value that isn’t less than the number.

// Get the ceiling of the "amount" field.
Field("amount").ceil()

Creates an expression that returns the absolute value of the number.

// Get the absolute value of the "amount" field.
Field("amount").abs()

Creates an expression that adds another expression to this expression. To add multiple expressions, chain calls to this method. Assumes self and the parameter evaluate to compatible types for addition (e.g., numbers, or string/array concatenation if supported by the specific “add” implementation).

// Add the value of the "quantity" field and the "reserve" field.
Field("quantity").add(Field("reserve"))

// Add multiple numeric fields
Field("subtotal").add(Field("tax")).add(Field("shipping"))

Creates an expression that adds a literal value to this expression. To add multiple literals, chain calls to this method. Assumes self and the parameter evaluate to compatible types for addition.

// Add 5 to the "count" field
Field("count").add(5)

// Add multiple literal numbers
Field("score").add(10).add(20).add(-5)

Creates an expression that subtracts another expression from this expression. Assumes self and other evaluate to numeric types.

// Subtract the "discount" field from the "price" field
Field("price").subtract(Field("discount"))

Creates an expression that subtracts a literal value from this expression. Assumes self evaluates to a numeric type.

// Subtract 20 from the value of the "total" field
Field("total").subtract(20)

Creates an expression that multiplies this expression by another expression. To multiply multiple expressions, chain calls to this method. Assumes self and the parameter evaluate to numeric types.

// Multiply the "quantity" field by the "price" field
Field("quantity").multiply(Field("price"))

// Multiply "rate" by "time" and "conversionFactor" fields
Field("rate").multiply(Field("time")).multiply(Field("conversionFactor"))

Creates an expression that multiplies this expression by a literal value. To multiply multiple literals, chain calls to this method. Assumes self evaluates to a numeric type.

// Multiply the "score" by 1.1
Field("score").multiply(1.1)

// Multiply "base" by 2 and then by 3.0
Field("base").multiply(2).multiply(3.0)

Creates an expression that divides this expression by another expression. Assumes self and other evaluate to numeric types.

// Divide the "total" field by the "count" field
Field("total").divide(Field("count"))

Creates an expression that divides this expression by a literal value. Assumes self evaluates to a numeric type.

// Divide the "value" field by 10
Field("value").divide(10)

Creates an expression that calculates the modulo (remainder) of dividing this expression by another expression. Assumes self and other evaluate to numeric types.

// Calculate the remainder of dividing the "value" field by the "divisor" field
Field("value").mod(Field("divisor"))

Creates an expression that calculates the modulo (remainder) of dividing this expression by a literal value. Assumes self evaluates to a numeric type.

// Calculate the remainder of dividing the "value" field by 10
Field("value").mod(10)

Creates an expression that returns the input with elements in reverse order.

// Reverse the "tags" array.
Field("tags").arrayReverse()

Creates an expression that concatenates an array expression (from self) with one or more other array expressions. Assumes self and all parameters evaluate to arrays.

// Combine the "items" array with "otherItems" and "archiveItems" array fields.
Field("items").arrayConcat(Field("otherItems"), Field("archiveItems"))

Creates an expression that concatenates an array expression (from self) with one or more array literals. Assumes self evaluates to an array.

// Combine "tags" (an array field) with ["new", "featured"] and ["urgent"]
Field("tags").arrayConcat(["new", "featured"], ["urgent"])

Creates an expression that checks if an array (from self) contains a specific element expression. Assumes self evaluates to an array.

// Check if "sizes" contains the value from "selectedSize" field
Field("sizes").arrayContains(Field("selectedSize"))

Creates an expression that checks if an array (from self) contains a specific literal element. Assumes self evaluates to an array.

// Check if "colors" array contains "red"
Field("colors").arrayContains("red")

Creates an expression that checks if an array (from self) contains all the specified element expressions. Assumes self evaluates to an array.

// Check if "candidateSkills" contains all skills from "requiredSkill1" and "requiredSkill2"
fields
Field("candidateSkills").arrayContainsAll([Field("requiredSkill1"), Field("requiredSkill2")])

Creates an expression that checks if an array (from self) contains all the specified literal elements. Assumes self evaluates to an array.

// Check if "tags" contains both "urgent" and "review"
Field("tags").arrayContainsAll(["urgent", "review"])

Creates an expression that checks if an array (from self) contains all the specified element expressions. Assumes self evaluates to an array.

// Check if the "tags" array contains "foo", "bar", and "baz"
Field("tags").arrayContainsAll(Constant(["foo", "bar", "baz"]))

Creates an expression that checks if an array (from self) contains any of the specified element expressions. Assumes self evaluates to an array.

// Check if "userGroups" contains any group from "allowedGroup1" or "allowedGroup2" fields
Field("userGroups").arrayContainsAny([Field("allowedGroup1"), Field("allowedGroup2")])

Creates an expression that checks if an array (from self) contains any of the specified literal elements. Assumes self evaluates to an array.

// Check if "categories" contains either "electronics" or "books"
Field("categories").arrayContainsAny(["electronics", "books"])

Creates an expression that checks if an array (from self) contains any of the specified element expressions. Assumes self evaluates to an array.

// Check if "groups" array contains any of the values from the "userGroup" field
Field("groups").arrayContainsAny(Field("userGroup"))

Creates an expression that calculates the length of an array. Assumes self evaluates to an array.

// Get the number of items in the "cart" array
Field("cart").arrayLength()

Creates an expression that accesses an element in an array (from self) at the specified integer offset. A negative offset starts from the end. If the offset is out of bounds, an error may be returned during evaluation. Assumes self evaluates to an array.

// Return the value in the "tags" field array at index 1.
Field("tags").arrayGet(1)
// Return the last element in the "tags" field array.
Field("tags").arrayGet(-1)

Creates an expression that accesses an element in an array (from self) at the offset specified by an expression. A negative offset starts from the end. If the offset is out of bounds, an error may be returned during evaluation. Assumes self evaluates to an array and offsetExpr evaluates to an integer.

// Return the value in the tags field array at index specified by field "favoriteTagIndex".
Field("tags").arrayGet(Field("favoriteTagIndex"))

Creates an expression that returns the maximum element of an array.

Assumes self evaluates to an array.

// Get the maximum value in the "scores" array.
Field("scores").arrayMaximum()

Creates an expression that returns the minimum element of an array.

Assumes self evaluates to an array.

// Get the minimum value in the "scores" array.
Field("scores").arrayMinimum()

Creates a BooleanExpression that returns true if this expression is greater than the given expression.

Creates a BooleanExpression that returns true if this expression is greater than the given value.

Creates a BooleanExpression that returns true if this expression is greater than or equal to the given expression.

Creates a BooleanExpression that returns true if this expression is greater than or equal to the given value.

Creates a BooleanExpression that returns true if this expression is less than the given expression.

Creates a BooleanExpression that returns true if this expression is less than the given value.

Creates a BooleanExpression that returns true if this expression is less than or equal to the given expression.

Creates a BooleanExpression that returns true if this expression is less than or equal to the given value.

Creates a BooleanExpression that returns true if this expression is equal to the given expression.

Creates a BooleanExpression that returns true if this expression is equal to the given value.

Creates a BooleanExpression that returns true if this expression is not equal to the given expression.

Creates a BooleanExpression that returns true if this expression is not equal to the given value.

Creates an expression that checks if this expression is equal to any of the provided expression values.

// Check if "categoryID" field is equal to "featuredCategory" or "popularCategory" fields
Field("categoryID").equalAny([Field("featuredCategory"), Field("popularCategory")])

Creates an expression that checks if this expression is equal to any of the provided literal values.

// Check if "category" is "Electronics", "Books", or "Home Goods"
Field("category").equalAny(["Electronics", "Books", "Home Goods"])

Creates an expression that checks if this expression is equal to any of the provided expression values.

// Check if "categoryID" field is equal to any of "categoryIDs" fields
Field("categoryID").equalAny(Field("categoryIDs"))

Creates an expression that checks if this expression is not equal to any of the provided expression values.

// Check if "statusValue" is not equal to "archivedStatus" or "deletedStatus" fields
Field("statusValue").notEqualAny([Field("archivedStatus"), Field("deletedStatus")])

Creates an expression that checks if this expression is not equal to any of the provided literal values.

// Check if "status" is neither "pending" nor "archived"
Field("status").notEqualAny(["pending", "archived"])

Creates an expression that checks if this expression is equal to any of the provided expression values.

// Check if "categoryID" field is not equal to any of "categoryIDs" fields
Field("categoryID").equalAny(Field("categoryIDs"))

Creates an expression that checks if a field exists in the document.

// Check if the document has a field named "phoneNumber"
Field("phoneNumber").exists()

Creates an expression that checks if this expression produces an error during evaluation.

// Check if accessing a non-existent array index causes an error
Field("myArray").arrayGet(100).isError()

Creates an expression that returns true if the result of this expression is absent (e.g., a field does not exist in a map). Otherwise, returns false.

// Check if the field `value` is absent.
Field("value").isAbsent()

Creates an expression that joins the elements of an array of strings with a given separator.

Assumes self evaluates to an array of strings.

// Join the "tags" array with a ", " separator.
Field("tags").join(separator: ", ")

Creates an expression that splits a string into an array of substrings based on a delimiter.

Creates an expression that splits a string into an array of substrings based on a delimiter.

Creates an expression that returns the length of a string.

// Get the length of the "name" field.
Field("name").length()

Creates an expression that calculates the character length of a string in UTF-8. Assumes self evaluates to a string.

// Get the character length of the "name" field in its UTF-8 form.
Field("name").charLength()

Creates an expression that performs a case-sensitive string comparison using wildcards against a literal pattern. Assumes self evaluates to a string.

// Check if the "title" field contains the word "guide" (case-sensitive)
Field("title").like("%guide%")

Creates an expression that performs a case-sensitive string comparison using wildcards against an expression pattern. Assumes self evaluates to a string, and pattern evaluates to a string.

// Check if "filename" matches a pattern stored in "patternField"
Field("filename").like(Field("patternField"))

Creates an expression that checks if a string (from self) contains a specified regular expression literal as a substring. Assumes self evaluates to a string.

// Check if "description" contains "example" (case-insensitive)
Field("description").regexContains("(?i)example")

Creates an expression that checks if a string (from self) contains a specified regular expression (from an expression) as a substring. Assumes self evaluates to a string, and pattern evaluates to a string.

// Check if "logEntry" contains a pattern from "errorPattern" field
Field("logEntry").regexContains(Field("errorPattern"))

Creates an expression that returns the first substring of a string expression that matches a specified regular expression. Assumes self evaluates to a string.

// Extract the domain name from an email field
Field("email").regexFind("@[A-Za-z0-9.-]+")

Creates an expression that returns the first substring of a string expression that matches a specified regular expression. Assumes self evaluates to a string, and pattern evaluates to a string.

// Extract a substring based on a dynamic pattern stored in another field
Field("email").regexFind(Field("pattern"))

Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression. Assumes self evaluates to a string.

// Extract all hashtags from a post content field
Field("content").regexFindAll("#[A-Za-z0-9_]+")

Creates an expression that evaluates to a list of all substrings in a string expression that match a specified regular expression. Assumes self evaluates to a string, and pattern evaluates to a string.

// Extract all matches based on a dynamic pattern stored in another field
Field("content").regexFindAll(Field("pattern"))

Creates an expression that checks if a string (from self) matches a specified regular expression literal entirely. Assumes self evaluates to a string.

// Check if the "email" field matches a valid email pattern
Field("email").regexMatch("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}")

Creates an expression that checks if a string (from self) matches a specified regular expression (from an expression) entirely. Assumes self evaluates to a string, and pattern evaluates to a string.

// Check if "input" matches the regex stored in "validationRegex"
Field("input").regexMatch(Field("validationRegex"))

Creates an expression that checks if a string (from self) contains a specified literal substring (case-sensitive). Assumes self evaluates to a string.

// Check if the "description" field contains "example".
Field("description").stringContains("example")

Creates an expression that checks if a string (from self) contains a specified substring from an expression (case-sensitive). Assumes self evaluates to a string, and expression evaluates to a string.

// Check if the "message" field contains the value of the "keyword" field.
Field("message").stringContains(Field("keyword"))

Creates an expression that checks if a string (from self) starts with a given literal prefix (case-sensitive). Assumes self evaluates to a string.

// Check if the "name" field starts with "Mr."
Field("name").startsWith("Mr.")

Creates an expression that checks if a string (from self) starts with a given prefix from an expression (case-sensitive). Assumes self evaluates to a string, and prefix evaluates to a string.

// Check if "fullName" starts with the value of "firstName"
Field("fullName").startsWith(Field("firstName"))

Creates an expression that checks if a string (from self) ends with a given literal suffix (case-sensitive). Assumes self evaluates to a string.

// Check if the "filename" field ends with ".txt"
Field("filename").endsWith(".txt")

Creates an expression that checks if a string (from self) ends with a given suffix from an expression (case-sensitive). Assumes self evaluates to a string, and suffix evaluates to a string.

// Check if "url" ends with the value of "extension" field
Field("url").endsWith(Field("extension"))

Creates an expression that converts a string (from self) to lowercase. Assumes self evaluates to a string.

// Convert the "name" field to lowercase
Field("name").toLower()

Creates an expression that converts a string (from self) to uppercase. Assumes self evaluates to a string.

// Convert the "title" field to uppercase
Field("title").toUpper()

Creates an expression that removes leading and trailing whitespace from a string.

Assumes self evaluates to a string.

// Trim leading/trailing whitespace from the "comment" field.
Field("comment").trim()

Creates an expression that removes leading and trailing occurrences of specified characters from a string (from self). Assumes self evaluates to a string, and value evaluates to a string.

// Trim leading/trailing "xy" from field
Field("code").trim(characters: "xy")

Creates an expression that removes leading and trailing occurrences of specified string (from an expression) from a string (from self). Assumes self evaluates to a string, and value evaluates to a string.

// Trim characters specified by the "trimChars" field from "data"
Field("data").trim(characters: Field("trimChars"))

Creates an expression that concatenates this string expression with other string expressions. Assumes self and all parameters evaluate to strings.

// Combine "firstName", " ", and "lastName"
Field("firstName").stringConcat([" ", Field("lastName")])

Creates an expression that concatenates this string expression with other string expressions. Assumes self and all parameters evaluate to strings.

// Combine "firstName", "middleName", and "lastName" fields
Field("firstName").stringConcat(Field("middleName"), Field("lastName"))

Creates an expression that reverses this expression. Assumes self evaluates to a string.

// Reverse the value of the "myString" field.
Field("myString").reverse()

Creates an expression that reverses this string expression. Assumes self evaluates to a string.

// Reverse the value of the "myString" field.
Field("myString").stringReverse()

Creates an expression that calculates the length of this string or bytes expression in bytes. Assumes self evaluates to a string or bytes.

// Calculate the length of the "myString" field in bytes.
Field("myString").byteLength()

// Calculate the size of the "avatar" (Data/Bytes) field.
Field("avatar").byteLength()

Creates an expression that returns a substring of this expression (String or Bytes) using literal integers for position and optional length. Indexing is 0-based. Assumes self evaluates to a string or bytes.

// Get substring from index 5 with length 10
Field("myString").substring(5, 10)

// Get substring from "myString" starting at index 3 to the end
Field("myString").substring(3) // Default nil

Creates an expression that returns a substring of this expression (String or Bytes) using expressions for position and optional length. Indexing is 0-based. Assumes self evaluates to a string or bytes, and parameters evaluate to integers.

// Get substring from index calculated by Field("start") with length from Field("len")
Field("myString").substring(Field("start"), Field("len"))

// Get substring from index calculated by Field("start") to the end
Field("myString").substring(Field("start")) // Default nil for optional Expression length

Accesses a value from a map (object) field using the provided literal string key. Assumes self evaluates to a Map.

// Get the "city" value from the "address" map field
Field("address").mapGet("city")

Creates an expression that removes a key (specified by a literal string) from the map produced by evaluating this expression. Assumes self evaluates to a Map.

// Removes the key "baz" from the map held in field "myMap"
Field("myMap").mapRemove("baz")

Creates an expression that removes a key (specified by an expression) from the map produced by evaluating this expression. Assumes self evaluates to a Map, and keyExpression evaluates to a string.

// Removes the key specified by field "keyToRemove" from the map in "settings"
Field("settings").mapRemove(Field("keyToRemove"))

Creates an expression that merges this map with multiple other map literals. Assumes self evaluates to a Map. Later maps overwrite keys from earlier maps.

// Merge "settings" field with { "enabled": true } and another map literal { "priority": 1 }
Field("settings").mapMerge(["enabled": true], ["priority": 1])

Creates an expression that merges this map with multiple other map expressions. Assumes self and other arguments evaluate to Maps. Later maps overwrite keys from earlier maps.

// Merge "baseSettings" field with "userOverrides" field and "adminConfig" field
Field("baseSettings").mapMerge(Field("userOverrides"), Field("adminConfig"))

Creates an aggregation that counts the number of distinct values of this expression.

// Count the number of distinct categories.
Field("category").countDistinct().as("distinctCategories")

Creates an aggregation that counts the number of stage inputs where this expression evaluates to a valid, non-null value.

// Count the total number of products with a "productId"
Field("productId").count().alias("totalProducts")

Creates an aggregation that calculates the sum of this numeric expression across multiple stage inputs. Assumes self evaluates to a numeric type.

// Calculate the total revenue from a set of orders
Field("orderAmount").sum().alias("totalRevenue")

Creates an aggregation that calculates the average (mean) of this numeric expression across multiple stage inputs. Assumes self evaluates to a numeric type.

// Calculate the average age of users
Field("age").average().as("averageAge")

Creates an aggregation that finds the minimum value of this expression across multiple stage inputs.

// Find the lowest price of all products
Field("price").minimum().alias("lowestPrice")

Creates an aggregation that finds the maximum value of this expression across multiple stage inputs.

// Find the highest score in a leaderboard
Field("score").maximum().alias("highestScore")

Creates an expression that returns the larger value between this expression and other expressions, based on Firestore"s value type ordering.

// Returns the largest of "val1", "val2", and "val3" fields
Field("val1").logicalMaximum(Field("val2"), Field("val3"))

Creates an expression that returns the larger value between this expression and other literal values, based on Firestore"s value type ordering.

// Returns the largest of "val1" (a field), 100, and 200.0
Field("val1").logicalMaximum(100, 200.0)

Creates an expression that returns the smaller value between this expression and other expressions, based on Firestore"s value type ordering.

// Returns the smallest of "val1", "val2", and "val3" fields
Field("val1").logicalMinimum(Field("val2"), Field("val3"))

Creates an expression that returns the smaller value between this expression and other literal values, based on Firestore"s value type ordering.

// Returns the smallest of "val1" (a field), 0, and -5.5
Field("val1").logicalMinimum(0, -5.5)

Creates an expression that calculates the length (number of dimensions) of this Firestore Vector expression. Assumes self evaluates to a Vector.

// Get the vector length (dimension) of the field "embedding".
Field("embedding").vectorLength()

Calculates the cosine distance between this vector expression and another vector expression. Assumes both self and other evaluate to Vectors.

// Cosine distance between "userVector" field and "itemVector" field
Field("userVector").cosineDistance(Field("itemVector"))

Calculates the cosine distance between this vector expression and another vector literal (VectorValue). Assumes self evaluates to a Vector.

// Cosine distance with a VectorValue
let targetVector = VectorValue(vector: [0.1, 0.2, 0.3])
Field("docVector").cosineDistance(targetVector)

Calculates the cosine distance between this vector expression and another vector literal ([Double]). Assumes self evaluates to a Vector.

// Cosine distance between "location" field and a target location
Field("location").cosineDistance([37.7749, -122.4194])

Calculates the dot product between this vector expression and another vector expression. Assumes both self and other evaluate to Vectors.

// Dot product between "vectorA" and "vectorB" fields
Field("vectorA").dotProduct(Field("vectorB"))

Calculates the dot product between this vector expression and another vector literal (VectorValue). Assumes self evaluates to a Vector.

// Dot product with a VectorValue
let weightVector = VectorValue(vector: [0.5, -0.5])
Field("features").dotProduct(weightVector)

Calculates the dot product between this vector expression and another vector literal ([Double]). Assumes self evaluates to a Vector.

// Dot product between a feature vector and a target vector literal
Field("features").dotProduct([0.5, 0.8, 0.2])

Calculates the Euclidean distance between this vector expression and another vector expression. Assumes both self and other evaluate to Vectors.

// Euclidean distance between "pointA" and "pointB" fields
Field("pointA").euclideanDistance(Field("pointB"))

Calculates the Euclidean distance between this vector expression and another vector literal (VectorValue). Assumes self evaluates to a Vector.

let targetPoint = VectorValue(vector: [1.0, 2.0])
Field("currentLocation").euclideanDistance(targetPoint)

Calculates the Euclidean distance between this vector expression and another vector literal ([Double]). Assumes self evaluates to a Vector.

// Euclidean distance between "location" field and a target location literal
Field("location").euclideanDistance([37.7749, -122.4194])

Creates an expression that interprets this expression (evaluating to a number) as microseconds since the Unix epoch and returns a timestamp. Assumes self evaluates to a number.

// Interpret "microseconds" field as microseconds since epoch.
Field("microseconds").unixMicrosToTimestamp()

Creates an expression that converts this timestamp expression to the number of microseconds since the Unix epoch. Assumes self evaluates to a Timestamp.

// Convert "timestamp" field to microseconds since epoch.
Field("timestamp").timestampToUnixMicros()

Creates an expression that interprets this expression (evaluating to a number) as milliseconds since the Unix epoch and returns a timestamp. Assumes self evaluates to a number.

// Interpret "milliseconds" field as milliseconds since epoch.
Field("milliseconds").unixMillisToTimestamp()

Creates an expression that converts this timestamp expression to the number of milliseconds since the Unix epoch. Assumes self evaluates to a Timestamp.

// Convert "timestamp" field to milliseconds since epoch.
Field("timestamp").timestampToUnixMillis()

Creates an expression that interprets this expression (evaluating to a number) as seconds since the Unix epoch and returns a timestamp. Assumes self evaluates to a number.

// Interpret "seconds" field as seconds since epoch.
Field("seconds").unixSecondsToTimestamp()

Creates an expression that converts this timestamp expression to the number of seconds since the Unix epoch. Assumes self evaluates to a Timestamp.

// Convert "timestamp" field to seconds since epoch.
Field("timestamp").timestampToUnixSeconds()

Creates an expression that truncates a timestamp to a specified granularity. Assumes self evaluates to a Timestamp.

// Truncate "timestamp" field to the nearest day.
Field("timestamp").timestampTruncate(granularity: .day)

Creates an expression that truncates a timestamp to a specified granularity. Assumes self evaluates to a Timestamp.

// Truncate "timestamp" field to the nearest day using a literal string.
Field("timestamp").timestampTruncate(granularity: "day")

// Truncate "timestamp" field to the nearest day using an expression.
Field("timestamp").timestampTruncate(granularity: Field("granularity_field"))

Creates an expression that adds a specified amount of time to this timestamp expression, where unit and amount are provided as literals. Assumes self evaluates to a Timestamp.

// Add 1 day to the "timestamp" field.
Field("timestamp").timestampAdd(1, .day)