feat: add the bigframes.bigquery sub-package with a bigframes.bigquery.array_length function (#630)

* feat: creats bigquery namespace and adds bigquery.array_length function

* add docs

* minor fix

* fixing docs

* add more doc tests

* sentence-case

* TODO for null arrays

---------

Co-authored-by: Tim Sweña (Swast) <[email protected]>

Author: chelsea-lin

bigframes/bigquery/__init__.py

@@ -0,0 +1,60 @@
+# Copyright 2024 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.
+
+
+"""This module integrates BigQuery built-in functions for use with DataFrame objects,
+such as array functions:
+https://cloud.google.com/bigquery/docs/reference/standard-sql/array_functions. """
+
+
+from __future__ import annotations
+
+import typing
+
+import bigframes.operations as ops
+
+if typing.TYPE_CHECKING:
+    import bigframes.series as series
+
+
+def array_length(series: series.Series) -> series.Series:
+    """Compute the length of each array element in the Series.
+
+    **Examples:**
+
+        >>> import bigframes.pandas as bpd
+        >>> import bigframes.bigquery as bbq
+        >>> bpd.options.display.progress_bar = None
+
+        >>> s = bpd.Series([[1, 2, 8, 3], [], [3, 4]])
+        >>> bbq.array_length(s)
+        0    4
+        1    0
+        2    2
+        dtype: Int64
+
+    You can also apply this function directly to Series.
+
+        >>> s.apply(bbq.array_length, by_row=False)
+        0    4
+        1    0
+        2    2
+        dtype: Int64
+
+    Returns:
+        bigframes.series.Series: A Series of integer values indicating
+            the length of each element in the Series.
+
+    """
+    return series._apply_unary_op(ops.len_op)

docs/reference/bigframes.bigquery/index.rst

@@ -0,0 +1,9 @@
+
+===========================
+BigQuery Built-in Functions
+===========================
+
+.. automodule:: bigframes.bigquery
+    :members:
+    :inherited-members:
+    :undoc-members:

docs/reference/bigframes/index.rst

@@ -1,4 +1,5 @@
 
+============
 Core objects
 ============
 

docs/reference/index.rst

@@ -10,3 +10,4 @@ packages.
     bigframes/index
     bigframes.pandas/index
     bigframes.ml/index
+    bigframes.bigquery/index

docs/templates/toc.yml

@@ -189,5 +189,9 @@
         uid: bigframes.ml.remote.VertexAIModel
       name: remote
     name: bigframes.ml
+  - items:
+    - name: BigQuery built-in functions
+      uid: bigframes.bigquery
+    name: bigframes.bigquery
   name: BigQuery DataFrames
   status: beta

tests/system/small/bigquery/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2024 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.

tests/system/small/bigquery/test_array.py

@@ -0,0 +1,32 @@
+# Copyright 2024 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 numpy as np
+import pandas as pd
+
+import bigframes.bigquery as bbq
+import bigframes.pandas as bpd
+
+
+def test_array_length():
+    series = bpd.Series([["A", "AA", "AAA"], ["BB", "B"], np.nan, [], ["C"]])
+    # TODO(b/336880368): Allow for NULL values to be input for ARRAY columns.
+    # Once we actually store NULL values, this will be NULL where the input is NULL.
+    expected = pd.Series([3, 2, 0, 0, 1])
+    pd.testing.assert_series_equal(
+        bbq.array_length(series).to_pandas(),
+        expected,
+        check_dtype=False,
+        check_index_type=False,
+    )