feat: Add bigframes.pandas.col with basic operators (#2405)

Author: TrevorBergeron

bigframes/core/agg_expressions.py

@@ -19,7 +19,7 @@
 importfunctools
 importitertools
 importtyping
-fromtypingimportCallable, Mapping, Tuple, TypeVar
+fromtypingimportCallable, Hashable, Mapping, Tuple, TypeVar
 
 frombigframesimportdtypes
 frombigframes.coreimportexpression, window_spec
@@ -68,7 +68,7 @@ def children(self) -> Tuple[expression.Expression, ...]:
 returnself.inputs
 
 @property
-deffree_variables(self) ->typing.Tuple[str, ...]:
+deffree_variables(self) ->typing.Tuple[Hashable, ...]:
 returntuple(
 itertools.chain.from_iterable(map(lambdax: x.free_variables, self.inputs))
  )
@@ -92,7 +92,7 @@ def transform_children(
 
 defbind_variables(
 self: TExpression,
-bindings: Mapping[str, expression.Expression],
+bindings: Mapping[Hashable, expression.Expression],
 allow_partial_bindings: bool=False,
  ) ->TExpression:
 returnself.transform_children(
@@ -192,7 +192,7 @@ def children(self) -> Tuple[expression.Expression, ...]:
 returnself.inputs
 
 @property
-deffree_variables(self) ->typing.Tuple[str, ...]:
+deffree_variables(self) ->typing.Tuple[Hashable, ...]:
 returntuple(
 itertools.chain.from_iterable(map(lambdax: x.free_variables, self.inputs))
  )
@@ -216,7 +216,7 @@ def transform_children(
 
 defbind_variables(
 self: WindowExpression,
-bindings: Mapping[str, expression.Expression],
+bindings: Mapping[Hashable, expression.Expression],
 allow_partial_bindings: bool=False,
  ) ->WindowExpression:
 returnself.transform_children(

bigframes/core/col.py

@@ -0,0 +1,126 @@
+# Copyright 2026 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
+
+importdataclasses
+fromtypingimportAny, Hashable
+
+importbigframes_vendored.pandas.core.colaspd_col
+
+importbigframes.core.expressionasbf_expression
+importbigframes.operationsasbf_ops
+
+
+# Not to be confused with the Expression class in `bigframes.core.expressions`
+# Name collision unintended
+@dataclasses.dataclass(frozen=True)
+classExpression:
+__doc__=pd_col.Expression.__doc__
+
+_value: bf_expression.Expression
+
+def_apply_unary(self, op: bf_ops.UnaryOp) ->Expression:
+returnExpression(op.as_expr(self._value))
+
+def_apply_binary(self, other: Any, op: bf_ops.BinaryOp, reverse: bool=False):
+ifisinstance(other, Expression):
+other_value=other._value
+else:
+other_value=bf_expression.const(other)
+ifreverse:
+returnExpression(op.as_expr(other_value, self._value))
+else:
+returnExpression(op.as_expr(self._value, other_value))
+
+def__add__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.add_op)
+
+def__radd__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.add_op, reverse=True)
+
+def__sub__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.sub_op)
+
+def__rsub__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.sub_op, reverse=True)
+
+def__mul__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.mul_op)
+
+def__rmul__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.mul_op, reverse=True)
+
+def__truediv__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.div_op)
+
+def__rtruediv__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.div_op, reverse=True)
+
+def__floordiv__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.floordiv_op)
+
+def__rfloordiv__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.floordiv_op, reverse=True)
+
+def__ge__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.ge_op)
+
+def__gt__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.gt_op)
+
+def__le__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.le_op)
+
+def__lt__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.lt_op)
+
+def__eq__(self, other: object) ->Expression: # type: ignore
+returnself._apply_binary(other, bf_ops.eq_op)
+
+def__ne__(self, other: object) ->Expression: # type: ignore
+returnself._apply_binary(other, bf_ops.ne_op)
+
+def__mod__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.mod_op)
+
+def__rmod__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.mod_op, reverse=True)
+
+def__and__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.and_op)
+
+def__rand__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.and_op, reverse=True)
+
+def__or__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.or_op)
+
+def__ror__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.or_op, reverse=True)
+
+def__xor__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.xor_op)
+
+def__rxor__(self, other: Any) ->Expression:
+returnself._apply_binary(other, bf_ops.xor_op, reverse=True)
+
+def__invert__(self) ->Expression:
+returnself._apply_unary(bf_ops.invert_op)
+
+
+defcol(col_name: Hashable) ->Expression:
+returnExpression(bf_expression.free_var(col_name))
+
+
+col.__doc__=pd_col.col.__doc__

bigframes/core/expression.py

@@ -19,7 +19,7 @@
 importfunctools
 importitertools
 importtyping
-fromtypingimportCallable, Generator, Mapping, TypeVar, Union
+fromtypingimportCallable, Generator, Hashable, Mapping, TypeVar, Union
 
 importpandasaspd
 
@@ -39,7 +39,7 @@ def deref(name: str) -> DerefOp:
 returnDerefOp(ids.ColumnId(name))
 
 
-deffree_var(id: str) ->UnboundVariableExpression:
+deffree_var(id: Hashable) ->UnboundVariableExpression:
 returnUnboundVariableExpression(id)
 
 
@@ -52,7 +52,7 @@ class Expression(abc.ABC):
 """An expression represents a computation taking N scalar inputs and producing a single output scalar."""
 
 @property
-deffree_variables(self) ->typing.Tuple[str, ...]:
+deffree_variables(self) ->typing.Tuple[Hashable, ...]:
 return ()
 
 @property
@@ -116,7 +116,9 @@ def bind_refs(
 
 @abc.abstractmethod
 defbind_variables(
-self, bindings: Mapping[str, Expression], allow_partial_bindings: bool=False
+self,
+bindings: Mapping[Hashable, Expression],
+allow_partial_bindings: bool=False,
  ) ->Expression:
 """Replace variables with expression given in `bindings`.
 
@@ -191,7 +193,9 @@ def output_type(self) -> dtypes.ExpressionType:
 returnself.dtype
 
 defbind_variables(
-self, bindings: Mapping[str, Expression], allow_partial_bindings: bool=False
+self,
+bindings: Mapping[Hashable, Expression],
+allow_partial_bindings: bool=False,
  ) ->Expression:
 returnself
 
@@ -226,10 +230,10 @@ def transform_children(self, t: Callable[[Expression], Expression]) -> Expressio
 classUnboundVariableExpression(Expression):
 """A variable expression representing an unbound variable."""
 
-id: str
+id: Hashable
 
 @property
-deffree_variables(self) ->typing.Tuple[str, ...]:
+deffree_variables(self) ->typing.Tuple[Hashable, ...]:
 return (self.id,)
 
 @property
@@ -256,7 +260,9 @@ def bind_refs(
 returnself
 
 defbind_variables(
-self, bindings: Mapping[str, Expression], allow_partial_bindings: bool=False
+self,
+bindings: Mapping[Hashable, Expression],
+allow_partial_bindings: bool=False,
  ) ->Expression:
 ifself.idinbindings.keys():
 returnbindings[self.id]
@@ -304,7 +310,9 @@ def output_type(self) -> dtypes.ExpressionType:
 raiseValueError(f"Type of variable {self.id} has not been fixed.")
 
 defbind_variables(
-self, bindings: Mapping[str, Expression], allow_partial_bindings: bool=False
+self,
+bindings: Mapping[Hashable, Expression],
+allow_partial_bindings: bool=False,
  ) ->Expression:
 returnself
 
@@ -373,7 +381,7 @@ def column_references(
  )
 
 @property
-deffree_variables(self) ->typing.Tuple[str, ...]:
+deffree_variables(self) ->typing.Tuple[Hashable, ...]:
 returntuple(
 itertools.chain.from_iterable(map(lambdax: x.free_variables, self.inputs))
  )
@@ -408,7 +416,9 @@ def output_type(self) -> dtypes.ExpressionType:
 returnself.op.output_type(*input_types)
 
 defbind_variables(
-self, bindings: Mapping[str, Expression], allow_partial_bindings: bool=False
+self,
+bindings: Mapping[Hashable, Expression],
+allow_partial_bindings: bool=False,
  ) ->OpExpression:
 returnOpExpression(
 self.op,

bigframes/dataframe.py

@@ -58,6 +58,7 @@
 frombigframes.coreimportagg_expressions
 importbigframes.core.block_transformsasblock_ops
 importbigframes.core.blocksasblocks
+importbigframes.core.col
 importbigframes.core.convert
 importbigframes.core.explode
 importbigframes.core.expressionasex
@@ -94,7 +95,13 @@
 importbigframes.session
 
 SingleItemValue=Union[
-bigframes.series.Series, int, float, str, pandas.Timedelta, Callable
+bigframes.series.Series,
+int,
+float,
+str,
+pandas.Timedelta,
+Callable,
+bigframes.core.col.Expression,
  ]
 MultiItemValue=Union[
 "DataFrame", Sequence[int|float|str|pandas.Timedelta|Callable]
@@ -2236,6 +2243,13 @@ def _assign_single_item(
  ) ->DataFrame:
 ifisinstance(v, bigframes.series.Series):
 returnself._assign_series_join_on_index(k, v)
+elifisinstance(v, bigframes.core.col.Expression):
+label_to_col_ref= {
+label: ex.deref(id) forid, labelinself._block.col_id_to_label.items()
+ }
+resolved_expr=v._value.bind_variables(label_to_col_ref)
+block=self._block.project_block_exprs([resolved_expr], labels=[k])
+returnDataFrame(block)
 elifisinstance(v, bigframes.dataframe.DataFrame):
 v_df_col_count=len(v._block.value_columns)
 ifv_df_col_count!=1:

bigframes/pandas/__init__.py

@@ -27,6 +27,7 @@
 importpandas
 
 importbigframes._configasconfig
+frombigframes.core.colimportcol
 importbigframes.core.global_sessionasglobal_session
 importbigframes.core.indexes
 frombigframes.core.loggingimportlog_adapter
@@ -415,6 +416,7 @@ def reset_session():
 "clean_up_by_session_id",
 "concat",
 "crosstab",
+"col",
 "cut",
 "deploy_remote_function",
 "deploy_udf",