feat(firestore): support array functions

packages/google-cloud-firestore/google/cloud/firestore_v1/pipeline_expressions.py

@@ -1490,6 +1490,202 @@ def last(self) -> "Expression":
         """
         return AggregateFunction("last", [self])
 
+    @expose_as_static
+    def array_first(self) -> "Expression":
+        """Creates an expression that returns the first element of an array.
+
+        Example:
+            >>> # Select the first element of array 'colors'
+            >>> Field.of("colors").array_first()
+
+        Returns:
+            A new `Expression` representing the first element of the array.
+        """
+        return FunctionExpression("array_first", [self])
+
+    @expose_as_static
+    def array_last(self) -> "Expression":
+        """Creates an expression that returns the last element of an array.
+
+        Example:
+            >>> # Select the last element of array 'colors'
+            >>> Field.of("colors").array_last()
+
+        Returns:
+            A new `Expression` representing the last element of the array.
+        """
+        return FunctionExpression("array_last", [self])
+
+    @expose_as_static
+    def array_first_n(self, n: int | "Expression") -> "Expression":
+        """Creates an expression that returns the first `n` elements of an array.
+
+        Example:
+            >>> # Select the first 2 elements of array 'colors'
+            >>> Field.of("colors").array_first_n(2)
+
+        Returns:
+            A new `Expression` representing the first `n` elements of the array.
+        """
+        return FunctionExpression(
+            "array_first_n", [self, self._cast_to_expr_or_convert_to_constant(n)]
+        )
+
+    @expose_as_static
+    def array_last_n(self, n: int | "Expression") -> "Expression":
+        """Creates an expression that returns the last `n` elements of an array.
+
+        Example:
+            >>> # Select the last 2 elements of array 'colors'
+            >>> Field.of("colors").array_last_n(2)
+
+        Returns:
+            A new `Expression` representing the last `n` elements of the array.
+        """
+        return FunctionExpression(
+            "array_last_n", [self, self._cast_to_expr_or_convert_to_constant(n)]
+        )
+
+    @expose_as_static
+    def array_maximum(self) -> "Expression":
+        """Creates an expression that returns the maximum element of an array.
+
+        Example:
+            >>> # Select the maximum element of array 'scores'
+            >>> Field.of("scores").array_maximum()
+
+        Returns:
+            A new `Expression` representing the maximum element of the array.
+        """
+        return FunctionExpression(
+            "maximum", [self], infix_name_override="array_maximum"
+        )
+
+    @expose_as_static
+    def array_minimum(self) -> "Expression":
+        """Creates an expression that returns the minimum element of an array.
+
+        Example:
+            >>> # Select the minimum element of array 'scores'
+            >>> Field.of("scores").array_minimum()
+
+        Returns:
+            A new `Expression` representing the minimum element of the array.
+        """
+        return FunctionExpression(
+            "minimum", [self], infix_name_override="array_minimum"
+        )
+
+    @expose_as_static
+    def array_maximum_n(self, n: int | "Expression") -> "Expression":
+        """Creates an expression that returns the maximum `n` elements of an array.
+
+        Example:
+            >>> # Select the maximum 2 elements of array 'scores'
+            >>> Field.of("scores").array_maximum_n(2)
+
+        Note:
+            Returns the n largest non-null elements in the array, in descending
+            order. This does not use a stable sort, meaning the order of equivalent
+            elements is undefined.
+
+        Returns:
+            A new `Expression` representing the maximum `n` elements of the array.
+        """
+        return FunctionExpression(
+            "maximum_n",
+            [self, self._cast_to_expr_or_convert_to_constant(n)],
+            infix_name_override="array_maximum_n",
+        )
+
+    @expose_as_static
+    def array_minimum_n(self, n: int | "Expression") -> "Expression":
+        """Creates an expression that returns the minimum `n` elements of an array.
+
+        Example:
+            >>> # Select the minimum 2 elements of array 'scores'
+            >>> Field.of("scores").array_minimum_n(2)
+
+        Note:
+            Returns the n smallest non-null elements in the array, in ascending
+            order. This does not use a stable sort, meaning the order of equivalent
+            elements is undefined.
+
+        Returns:
+            A new `Expression` representing the minimum `n` elements of the array.
+        """
+        return FunctionExpression(
+            "minimum_n",
+            [self, self._cast_to_expr_or_convert_to_constant(n)],
+            infix_name_override="array_minimum_n",
+        )
+
+    @expose_as_static
+    def array_slice(
+        self, offset: int | "Expression", length: int | "Expression" | None = None
+    ) -> "Expression":
+        """Creates an expression that returns a slice of an array starting from the specified
+        offset with a given length.
+
+        Example:
+            >>> # Slice array 'scores' starting at index 1 with length 2
+            >>> Field.of("scores").array_slice(1, 2)
+
+        Args:
+            offset: the 0-based index of the first element to include.
+            length: The number of elements to include in the slice. If omitted, slices to the end.
+
+        Returns:
+            A new `Expression` representing the slice of the array.
+        """
+        args = [self, self._cast_to_expr_or_convert_to_constant(offset)]
+        if length is not None:
+            args.append(self._cast_to_expr_or_convert_to_constant(length))
+        return FunctionExpression("array_slice", args)
+
+    @expose_as_static
+    def array_index_of(self, search: "Expression" | CONSTANT_TYPE) -> "Expression":
+        """Creates an expression that returns the first index of the search value in the array,
+        or -1 if not found.
+
+        Example:
+            >>> # Get the index of "comedy" in the 'tags' array
+            >>> Field.of("tags").array_index_of("comedy")
+
+        Args:
+            search: An expression evaluating to the value to search for.
+
+        Returns:
+            A new `Expression` representing the index.
+        """
+        return FunctionExpression(
+            "array_index_of",
+            [
+                self,
+                self._cast_to_expr_or_convert_to_constant(search),
+                self._cast_to_expr_or_convert_to_constant("first"),
+            ],
+        )
+
+    @expose_as_static
+    def array_index_of_all(self, search: "Expression" | CONSTANT_TYPE) -> "Expression":
+        """Creates an expression that returns all indices of a value in an array.
+
+        Example:
+            >>> # Get all indices of "comedy" in the 'tags' array
+            >>> Field.of("tags").array_index_of_all("comedy")
+
+        Args:
+            search: An expression evaluating to the value to search for.
+
+        Returns:
+            A new `Expression` representing the indices.
+        """
+        return FunctionExpression(
+            "array_index_of_all",
+            [self, self._cast_to_expr_or_convert_to_constant(search)],
+        )
+
     @expose_as_static
     def unix_micros_to_timestamp(self) -> "Expression":
         """Creates an expression that converts a number of microseconds since the epoch (1970-01-01