docs(aggregate): clarify AccumulatorArgs schema handling and usage

- Improve documentation for AccumulatorArgs.schema and exprs:
  - Add example showing how to retrieve field metadata and return field.
  - Explain synthesized schema behavior for literal-only inputs.
  - Clarify precedence when inputs are mixed (physical schema metadata wins; synthesized metadata used only when physical schema is empty).
- Update AggregateFunctionExpr::args_schema docs:
  - Explain field order guarantees, synthesized schema usage, and that std::borrow::Cow is used to avoid allocations when possible.
- Add a TODO to factor AccumulatorArgs construction into a private helper.

Documentation-only changes; no behavioral changes.

Author: kosiew

datafusion/expr/src/udaf.rs

@@ -752,7 +752,19 @@ pub trait AggregateUDFImpl: Debug + Send + Sync {
     ///
     /// acc_args: [`AccumulatorArgs`] contains information about how the
     /// aggregate function was called. Use `acc_args.exprs` together with
-    /// `acc_args.schema` to inspect the [`FieldRef`] of each input. When an
+    /// `acc_args.schema` to inspect the [`FieldRef`] of each input.
+    ///
+    /// Example: retrieving metadata and return field for input `i`:
+    /// ```rust
+    /// let metadata = acc_args.schema.field(i).metadata();
+    /// let field = acc_args.exprs[i].return_field(&acc_args.schema)?;
+    /// ```
+    /// Multi-argument functions: `exprs[i]` corresponds to `schema.field(i)`.
+    /// Mixed inputs (columns and literals): the physical input schema is used
+    /// when not empty; `acc_args.schema` is only synthesized from literals when
+    /// the physical schema is empty.
+    ///
+    /// When an
     /// aggregate is invoked with literal values only, `acc_args.schema` is
     /// synthesized from those literals so that any field metadata (for
     /// example Arrow extension types) is available to the accumulator

datafusion/functions-aggregate-common/src/accumulator.rs

@@ -32,11 +32,12 @@ pub struct AccumulatorArgs<'a> {
 
     /// The schema of the input arguments.
     ///
-    /// This schema contains the fields corresponding to [`Self::exprs`]. When
-    /// an aggregate is invoked with only literal values, this schema is
-    /// synthesized from those literals so that field-level metadata (such as
-    /// Arrow extension types) remains available to accumulator
-    /// implementations.
+    /// This schema contains the fields corresponding to the function’s input
+    /// expressions (`exprs`). When an aggregate is invoked with only literal
+    /// values, this schema is synthesized from those literals to preserve
+    /// field-level metadata (such as Arrow extension types). In mixed column
+    /// and literal inputs, metadata from the physical schema takes precedence;
+    /// synthesized metadata is only used when the physical schema is empty.
     pub schema: &'a Schema,
 
     /// Whether to ignore nulls.
@@ -74,6 +75,12 @@ pub struct AccumulatorArgs<'a> {
     /// The physical expressions for the aggregate function's arguments.
     /// Use these expressions together with [`Self::schema`] to obtain the
     /// [`FieldRef`] of each input via `expr.return_field(schema)`.
+    ///
+    /// Example:
+    /// ```rust
+    /// let input_field = exprs[i].return_field(&schema)?;
+    /// ```
+    /// Note: physical schema metadata takes precedence in mixed inputs.
     pub exprs: &'a [Arc<dyn PhysicalExpr>],
 }
 

datafusion/physical-expr/src/aggregate.rs

@@ -378,13 +378,19 @@ impl AggregateFunctionExpr {
     }
 
     /// Returns a schema containing the fields corresponding to this
-    /// aggregate's input expressions.
+    /// aggregate's input expressions in the same order as `input_fields`/`exprs`.
     ///
-    /// When an aggregate is invoked with only literal values, the
-    /// physical input schema is empty. In this case a schema is
-    /// synthesized from the literal expressions so that field metadata
-    /// (such as Arrow extension types) remains available to the
-    /// [`Accumulator`].
+    /// If the physical input schema is empty (literal-only inputs),
+    /// synthesizes a new schema from the literal expressions to preserve
+    /// field-level metadata (such as Arrow extension types).
+    /// Field order is guaranteed to match the order of input expressions.
+    /// In mixed column and literal inputs, existing physical schema fields
+    /// win; synthesized metadata is only applied when the physical schema
+    /// has no fields.
+    ///
+    /// Uses [`std::borrow::Cow`] to avoid allocation when the existing
+    /// schema is non-empty. For micro-optimizations, implementers may
+    /// cache the owned schema if multiple calls are made per instance.
     fn args_schema(&self) -> Cow<'_, Schema> {
         if self.schema.fields().is_empty() {
             Cow::Owned(Schema::new(
@@ -401,6 +407,7 @@ impl AggregateFunctionExpr {
     /// the accumulator used to accumulate values from the expressions.
     /// the accumulator expects the same number of arguments as `expressions` and must
     /// return states with the same description as `state_fields`
+    // TODO: factor AccumulatorArgs construction into a private helper to avoid duplication
     pub fn create_accumulator(&self) -> Result<Box<dyn Accumulator>> {
         let schema = self.args_schema();
         let acc_args = AccumulatorArgs {