chore: add experimental series. blob.metadata() function (#1169)

Author: GarrettWu

bigframes/core/compile/scalar_op_compiler.py

@@ -42,6 +42,14 @@
 # ln(2**(2**10)) == (2**10)*ln(2) ~= 709.78, so EXP(x) for x>709.78 will overflow.
 _FLOAT64_EXP_BOUND = typing.cast(ibis_types.NumericValue, ibis_types.literal(709.78))
 
+_OBJ_REF_STRUCT_SCHEMA = (
+ ("uri", ibis_dtypes.String),
+ ("version", ibis_dtypes.String),
+ ("authorizer", ibis_dtypes.String),
+ ("details", ibis_dtypes.JSON),
+)
+_OBJ_REF_IBIS_DTYPE = ibis_dtypes.Struct.from_tuples(_OBJ_REF_STRUCT_SCHEMA)
+
 # Datetime constants
 UNIT_TO_US_CONVERSION_FACTORS = {
  "W": 7 * 24 * 60 * 60 * 1000 * 1000,
@@ -1161,6 +1169,12 @@ def json_extract_string_array_op_impl(
  return json_extract_string_array(json_obj=x, json_path=op.json_path)
 
 
+# Blob Ops
+@scalar_op_compiler.register_unary_op(ops.obj_fetch_metadata_op)
+def obj_fetch_metadata_op_impl(x: ibis_types.Value):
+ return obj_fetch_metadata(obj_ref=x)
+
+
 ### Binary Ops
 def short_circuit_nulls(type_override: typing.Optional[ibis_dtypes.DataType] = None):
  """Wraps a binary operator to generate nulls of the expected type if either input is a null scalar."""
@@ -1832,3 +1846,8 @@ def json_extract_string_array(
 @ibis.udf.scalar.builtin(name="ML.DISTANCE")
 def vector_distance(vector1, vector2, type: str) -> ibis_dtypes.Float64:
  """Computes the distance between two vectors using specified type ("EUCLIDEAN", "MANHATTAN", or "COSINE")"""
+
+
+@ibis.udf.scalar.builtin(name="OBJ.FETCH_METADATA")
+def obj_fetch_metadata(obj_ref: _OBJ_REF_IBIS_DTYPE) -> _OBJ_REF_IBIS_DTYPE: # type: ignore
+ """Fetch metadata from ObjectRef Struct."""

bigframes/operations/__init__.py

@@ -326,6 +326,10 @@ def create_binary_op(
 log10_op = create_unary_op(name="log10", type_signature=op_typing.UNARY_REAL_NUMERIC)
 log1p_op = create_unary_op(name="log1p", type_signature=op_typing.UNARY_REAL_NUMERIC)
 sqrt_op = create_unary_op(name="sqrt", type_signature=op_typing.UNARY_REAL_NUMERIC)
+## Blob Ops
+obj_fetch_metadata_op = create_unary_op(
+ name="obj_fetch_metadata", type_signature=op_typing.BLOB_TRANSFORM
+)
 
 
 # Parameterized unary ops

bigframes/operations/blob.py

@@ -0,0 +1,36 @@
+# 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.
+
+from __future__ import annotations
+
+import bigframes
+from bigframes.operations import base
+import bigframes.operations as ops
+
+
+class BlobAccessor(base.SeriesMethods):
+ def __init__(self, *args, **kwargs):
+ if not bigframes.options.experiments.blob:
+ raise NotImplementedError()
+
+ super().__init__(*args, **kwargs)
+
+ def metadata(self):
+ details_json = self._apply_unary_op(ops.obj_fetch_metadata_op).struct.field(
+ "details"
+ )
+
+ import bigframes.bigquery as bbq
+
+ return bbq.json_extract(details_json, "$.gcs_metadata")

bigframes/operations/type.py

@@ -213,6 +213,7 @@ def output_type(
 UNARY_REAL_NUMERIC = UnaryRealNumeric()
 BINARY_NUMERIC = BinaryNumeric()
 BINARY_REAL_NUMERIC = BinaryRealNumeric()
+BLOB_TRANSFORM = TypePreserving(bigframes.dtypes.is_struct_like, description="blob")
 COMPARISON = Comparison()
 COERCE = CoerceCommon()
 LOGICAL = Logical()

bigframes/series.py

@@ -54,6 +54,7 @@
 import bigframes.operations as ops
 import bigframes.operations.aggregations as agg_ops
 import bigframes.operations.base
+import bigframes.operations.blob as blob
 import bigframes.operations.datetimes as dt
 import bigframes.operations.lists as lists
 import bigframes.operations.plotting as plotting
@@ -187,6 +188,10 @@ def struct(self) -> structs.StructAccessor:
  def list(self) -> lists.ListAccessor:
  return lists.ListAccessor(self._block)
 
+ @property
+ def blob(self) -> blob.BlobAccessor:
+ return blob.BlobAccessor(self._block)
+
  @property
  @validations.requires_ordering()
  def T(self) -> Series: