feat: expose arrow_field, arrow_try_cast, cast_to_type, with_metadata

Adds Python bindings for five scalar functions from
datafusion::functions::expr_fn that were not previously surfaced:

- arrow_field: returns a struct describing an expression's Arrow field
  (name, data_type, nullable, metadata).
- arrow_try_cast: like arrow_cast but yields NULL on cast failure.
- cast_to_type / try_cast_to_type: casts a value to the type of a
  reference expression. These are exposed as a single Python entry
  point cast_to_type(value, type_ref, *, try_cast=False); the kwarg
  switches between the strict and try variants.
- with_metadata: attach Arrow field metadata; the inverse of
  arrow_metadata. Accepts a dict[str, str] for ergonomics.

Updates skills/datafusion_python/SKILL.md to list the new functions
and documents the cast_to_type kwarg behavior.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: timsaucer

crates/core/src/functions.rs

@@ -607,7 +607,12 @@ expr_fn_vec!(named_struct);
 expr_fn!(from_unixtime, unixtime);
 expr_fn!(arrow_typeof, arg_1);
 expr_fn!(arrow_cast, arg_1 datatype);
+expr_fn!(arrow_try_cast, arg_1 datatype);
+expr_fn!(arrow_field, arg_1);
+expr_fn!(cast_to_type, arg_1 reference);
+expr_fn!(try_cast_to_type, arg_1 reference);
 expr_fn_vec!(arrow_metadata);
+expr_fn_vec!(with_metadata);
 expr_fn!(union_tag, arg1);
 expr_fn!(random);
 
@@ -962,7 +967,12 @@ pub(crate) fn init_module(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_wrapped(wrap_pyfunction!(array_agg))?;
     m.add_wrapped(wrap_pyfunction!(arrow_typeof))?;
     m.add_wrapped(wrap_pyfunction!(arrow_cast))?;
+    m.add_wrapped(wrap_pyfunction!(arrow_try_cast))?;
+    m.add_wrapped(wrap_pyfunction!(arrow_field))?;
+    m.add_wrapped(wrap_pyfunction!(cast_to_type))?;
+    m.add_wrapped(wrap_pyfunction!(try_cast_to_type))?;
     m.add_wrapped(wrap_pyfunction!(arrow_metadata))?;
+    m.add_wrapped(wrap_pyfunction!(with_metadata))?;
     m.add_wrapped(wrap_pyfunction!(ascii))?;
     m.add_wrapped(wrap_pyfunction!(asin))?;
     m.add_wrapped(wrap_pyfunction!(asinh))?;

python/datafusion/functions.py

@@ -120,7 +120,9 @@
     "arrays_overlap",
     "arrays_zip",
     "arrow_cast",
+    "arrow_field",
     "arrow_metadata",
+    "arrow_try_cast",
     "arrow_typeof",
     "ascii",
     "asin",
@@ -138,6 +140,7 @@
     "btrim",
     "cardinality",
     "case",
+    "cast_to_type",
     "cbrt",
     "ceil",
     "char_length",
@@ -368,6 +371,7 @@
     "var_sample",
     "version",
     "when",
+    "with_metadata",
 ]
 
 
@@ -2930,6 +2934,82 @@ def arrow_cast(expr: Expr, data_type: Expr | str | pa.DataType) -> Expr:
     return Expr(f.arrow_cast(expr.expr, data_type.expr))
 
 
+def arrow_try_cast(expr: Expr, data_type: Expr | str) -> Expr:
+    """Casts an expression to a specified data type, returning NULL on failure.
+
+    Like :py:func:`arrow_cast` but produces NULL instead of erroring when the
+    cast cannot be performed. The ``data_type`` may be a string in DataFusion
+    type syntax (for example ``"Float64"``) or an ``Expr`` of string type.
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": ["oops"]})
+        >>> result = df.select(
+        ...     dfn.functions.arrow_try_cast(dfn.col("a"), "Float64").alias("c")
+        ... )
+        >>> result.collect_column("c")[0].as_py() is None
+        True
+    """
+    if isinstance(data_type, str):
+        data_type = Expr.string_literal(data_type)
+    return Expr(f.arrow_try_cast(expr.expr, data_type.expr))
+
+
+def arrow_field(expr: Expr) -> Expr:
+    """Returns the Arrow field information of an expression as a struct.
+
+    The returned struct contains the field's name, data type, nullability,
+    and metadata.
+
+    Examples:
+        >>> field = pa.field("val", pa.int64(), metadata={"k": "v"})
+        >>> schema = pa.schema([field])
+        >>> batch = pa.RecordBatch.from_arrays([pa.array([1])], schema=schema)
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.create_dataframe([[batch]])
+        >>> result = df.select(
+        ...     dfn.functions.arrow_field(dfn.col("val")).alias("f")
+        ... )
+        >>> result.collect_column("f")[0].as_py()["name"]
+        'val'
+    """
+    return Expr(f.arrow_field(expr.expr))
+
+
+def cast_to_type(value: Expr, type_ref: Expr, *, try_cast: bool = False) -> Expr:
+    """Casts ``value`` to the data type of ``type_ref``.
+
+    Only the *type* of ``type_ref`` is used; its value is ignored. This is
+    useful when the target type comes from another column or expression
+    rather than being known up-front. When ``try_cast=True``, casts that
+    fail produce NULL instead of erroring (this dispatches to upstream
+    ``try_cast_to_type``).
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": [1], "b": [1.0]})
+        >>> result = df.select(
+        ...     dfn.functions.cast_to_type(
+        ...         dfn.col("a"), dfn.col("b")
+        ...     ).alias("c")
+        ... )
+        >>> result.collect_column("c")[0].as_py()
+        1.0
+
+        >>> df = ctx.from_pydict({"a": ["oops"], "b": [1.0]})
+        >>> result = df.select(
+        ...     dfn.functions.cast_to_type(
+        ...         dfn.col("a"), dfn.col("b"), try_cast=True
+        ...     ).alias("c")
+        ... )
+        >>> result.collect_column("c")[0].as_py() is None
+        True
+    """
+    if try_cast:
+        return Expr(f.try_cast_to_type(value.expr, type_ref.expr))
+    return Expr(f.cast_to_type(value.expr, type_ref.expr))
+
+
 def arrow_metadata(expr: Expr, key: Expr | str | None = None) -> Expr:
     """Returns the metadata of the input expression.
 
@@ -2963,6 +3043,33 @@ def arrow_metadata(expr: Expr, key: Expr | str | None = None) -> Expr:
     return Expr(f.arrow_metadata(expr.expr, key.expr))
 
 
+def with_metadata(expr: Expr, metadata: dict[str, str]) -> Expr:
+    """Attaches Arrow field metadata (key/value pairs) to the input expression.
+
+    This is the inverse of :py:func:`arrow_metadata`. Existing metadata on the
+    input field is preserved; new keys overwrite on collision. Keys must be
+    non-empty strings; empty values are allowed.
+
+    Examples:
+        >>> ctx = dfn.SessionContext()
+        >>> df = ctx.from_pydict({"a": [1]})
+        >>> result = df.select(
+        ...     dfn.functions.with_metadata(
+        ...         dfn.col("a"), {"unit": "ms"}
+        ...     ).alias("a")
+        ... )
+        >>> result.select(
+        ...     dfn.functions.arrow_metadata(dfn.col("a"), "unit").alias("u")
+        ... ).collect_column("u")[0].as_py()
+        'ms'
+    """
+    args = [expr]
+    for k, v in metadata.items():
+        args.append(Expr.string_literal(k))
+        args.append(Expr.string_literal(v))
+    return Expr(f.with_metadata(*(a.expr for a in args)))
+
+
 def get_field(expr: Expr, *names: Expr | str) -> Expr:
     """Extracts a (possibly nested) field from a struct or map by name.
 

skills/datafusion_python/SKILL.md

@@ -758,7 +758,12 @@ F.left(col("c_phone"), lit(2))                # prefix shortcut
 
 **Hash**: `md5`, `sha224`, `sha256`, `sha384`, `sha512`, `digest`
 
-**Type**: `arrow_typeof`, `arrow_cast`, `arrow_metadata`
+**Type**: `arrow_typeof`, `arrow_cast`, `arrow_try_cast`, `arrow_field`,
+`arrow_metadata`, `cast_to_type`, `with_metadata`
+
+Note: ``cast_to_type(value, type_ref, *, try_cast=False)`` is the single
+Python entry point for both upstream ``cast_to_type`` and ``try_cast_to_type``;
+pass ``try_cast=True`` for the variant that returns NULL on failure.
 
 **Other**: `in_list`, `order_by`, `alias`, `col`, `encode`, `decode`,
 `to_hex`, `to_char`, `uuid`, `version`, `bit_length`, `octet_length`