Update doc

Signed-off-by: Kai Huang <[email protected]>

Author: ahkcs

core/src/main/java/org/opensearch/sql/calcite/utils/binning/handlers/CountBinHandler.java

@@ -28,7 +28,12 @@ public RexNode createExpression(
     CountBin countBin = (CountBin) node;
 
     // Create validated binnable field (validates that field is numeric or time-based)
-    // Note: bins parameter on time-based fields requires pushdown to be enabled
+    // Note: bins parameter works with both numeric and time-based fields
+    // Note: bins parameter on time-based fields requires:
+    //       1. Pushdown to be enabled (controlled by plugins.calcite.pushdown.enabled, enabled by
+    //          default)
+    //       2. The time-based field to be used as an aggregation bucket
+    //          (e.g., stats count() by @timestamp)
     String fieldName = BinFieldValidator.extractFieldName(node);
     BinnableField field = new BinnableField(fieldExpr, fieldExpr.getType(), fieldName);
 

docs/user/ppl/cmd/bin.rst

@@ -182,7 +182,10 @@ Automatically calculates the span using a mathematical O(1) algorithm to create
 
 **Validation**: The bins parameter must be between 2 and 50000 (inclusive). Values outside this range will result in an error.
 
-**Limitation**: The bins parameter on timestamp fields requires pushdown to be enabled. When pushdown is disabled, use the ``span`` parameter instead (e.g., ``bin @timestamp span=5m``).
+**Limitation**: The bins parameter on timestamp fields has the following requirements:
+
+1. **Pushdown must be enabled**: Controlled by ``plugins.calcite.pushdown.enabled`` (enabled by default). When pushdown is disabled, use the ``span`` parameter instead (e.g., ``bin @timestamp span=5m``).
+2. **Timestamp field must be used as an aggregation bucket**: The binned timestamp field must be used in a ``stats`` aggregation (e.g., ``source=events | bin @timestamp bins=3 | stats count() by @timestamp``). Using bins on timestamp fields outside of aggregation buckets is not supported.
 
 The algorithm uses **mathematical optimization** instead of iteration for O(1) performance:
 

integ-test/src/test/java/org/opensearch/sql/calcite/remote/CalciteBinCommandIT.java

@@ -1140,6 +1140,10 @@ public void testBinsOnTimeFieldWithPushdownDisabled_ShouldFail() throws IOExcept
                     "source=events_null | bin @timestamp bins=3 | stats count() by @timestamp"));
 
     // Verify the error message clearly explains the limitation and suggests solutions
+    // Note: bins parameter on timestamp fields requires BOTH:
+    //   1. Pushdown to be enabled (plugins.calcite.pushdown.enabled=true, enabled by default)
+    //   2. The timestamp field to be used as an aggregation bucket (e.g., stats count() by
+    // @timestamp)
     String errorMessage = exception.getMessage();
     assertTrue(
         "Expected clear error message about bins parameter not supported on timestamp fields when "