feat: Add bigframes.bigquery.rand() function (#2501)

This change adds `bigframes.bigquery.rand()` which wraps the BigQuery
`RAND()` function. It includes a warning about non-determinism in the
docstring.
Additionally, `SqlScalarOp` has been updated to accept an
`is_deterministic` argument, which is set to `False` for `rand()`.
Fixes customer request for this function. 🦕
Co-authored-by: tswast <247555+tswast@users.noreply.github.com>

Author: tswast

bigframes/bigquery/__init__.py

@@ -58,6 +58,7 @@
 to_json,
 to_json_string,
 )
+frombigframes.bigquery._operations.mathematicalimportrand
 frombigframes.bigquery._operations.searchimportcreate_vector_index, vector_search
 frombigframes.bigquery._operations.sqlimportsql_scalar
 frombigframes.bigquery._operations.structimportstruct
@@ -99,6 +100,8 @@
 parse_json,
 to_json,
 to_json_string,
+# mathematical ops
+rand,
 # search ops
 create_vector_index,
 vector_search,
@@ -154,6 +157,8 @@
 "parse_json",
 "to_json",
 "to_json_string",
+# mathematical ops
+"rand",
 # search ops
 "create_vector_index",
 "vector_search",

bigframes/bigquery/_operations/mathematical.py

@@ -0,0 +1,53 @@
+# Copyright 2025 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__ importannotations
+
+frombigframesimportdtypes
+frombigframesimportoperationsasops
+importbigframes.core.col
+importbigframes.core.expression
+
+
+defrand() ->bigframes.core.col.Expression:
+"""
+ Generates a pseudo-random value of type FLOAT64 in the range of [0, 1),
+ inclusive of 0 and exclusive of 1.
+
+ .. warning::
+ This method introduces non-determinism to the expression. Reading the
+ same column twice may result in different results. The value might
+ change. Do not use this value or any value derived from it as a join
+ key.
+
+ **Examples:**
+
+ >>> import bigframes.pandas as bpd
+ >>> import bigframes.bigquery as bbq
+ >>> df = bpd.DataFrame({"a": [1, 2, 3]})
+ >>> df['random'] = bbq.rand()
+ >>> # Resulting column 'random' will contain random floats between 0 and 1.
+
+ Returns:
+ bigframes.pandas.api.typing.Expression:
+ An expression that can be used in
+ :func:`~bigframes.pandas.DataFrame.assign` and other methods. See
+ :func:`bigframes.pandas.col`.
+ """
+op=ops.SqlScalarOp(
+_output_type=dtypes.FLOAT_DTYPE,
+sql_template="RAND()",
+is_deterministic=False,
+ )
+returnbigframes.core.col.Expression(bigframes.core.expression.OpExpression(op, ()))

bigframes/operations/generic_ops.py

@@ -443,10 +443,15 @@ class SqlScalarOp(base_ops.NaryOp):
 name: typing.ClassVar[str] ="sql_scalar"
 _output_type: dtypes.ExpressionType
 sql_template: str
+is_deterministic: bool=True
 
 defoutput_type(self, *input_types: dtypes.ExpressionType) ->dtypes.ExpressionType:
 returnself._output_type
 
+@property
+defdeterministic(self) ->bool:
+returnself.is_deterministic
+
 
 @dataclasses.dataclass(frozen=True)
 classPyUdfOp(base_ops.NaryOp):

tests/system/small/bigquery/test_mathematical.py

@@ -0,0 +1,37 @@
+# Copyright 2025 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.
+
+importbigframes.bigqueryasbbq
+
+
+deftest_rand(scalars_df_index):
+df=scalars_df_index
+
+# Apply rand
+df=df.assign(random=bbq.rand())
+result=df["random"]
+
+# Eagerly evaluate
+result_pd=result.to_pandas()
+
+# Check length
+assertlen(result_pd) ==len(df)
+
+# Check values in [0, 1)
+assert (result_pd>=0).all()
+assert (result_pd<1).all()
+
+# Check not all values are equal (unlikely collision for random)
+iflen(result_pd) >1:
+assertresult_pd.nunique() >1

tests/unit/bigquery/test_mathematical.py

@@ -0,0 +1,33 @@
+# Copyright 2025 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.
+
+importbigframes.bigqueryasbbq
+importbigframes.core.colascol
+importbigframes.core.expressionasex
+importbigframes.dtypesasdtypes
+importbigframes.operationsasops
+
+
+deftest_rand_returns_expression():
+expr=bbq.rand()
+
+assertisinstance(expr, col.Expression)
+node=expr._value
+assertisinstance(node, ex.OpExpression)
+op=node.op
+assertisinstance(op, ops.SqlScalarOp)
+assertop.sql_template=="RAND()"
+assertop._output_type==dtypes.FLOAT_DTYPE
+assertnotop.is_deterministic
+assertlen(node.inputs) ==0