feat: add the bigframes.bigquery sub-package with a bigframes.bigquery.array_length function

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,30 @@
+# 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"]])
+ 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,
+ )