Enhance doc and error message handling for bins on time-related fields (opensearch-project#4713)

(cherry picked from commit ef4c51e)
Signed-off-by: Kai Huang <ahkcs@amazon.com>

Author: ahkcs

core/src/main/java/org/opensearch/sql/calcite/utils/CalciteToolsHelper.java

@@ -360,6 +360,17 @@ public RelNode visit(TableScan scan) {
         final RelRunner runner = connection.unwrap(RelRunner.class);
         return runner.prepareStatement(rel);
       } catch (SQLException e) {
+        // Detect if error is due to window functions in unsupported context (bins on time fields)
+        String errorMsg = e.getMessage();
+        if (errorMsg != null
+            && errorMsg.contains("Error while preparing plan")
+            && errorMsg.contains("WIDTH_BUCKET")) {
+          throw new UnsupportedOperationException(
+              "The 'bins' parameter on timestamp fields requires: (1) pushdown to be enabled"
+                  + " (controlled by plugins.calcite.pushdown.enabled, enabled by default), and"
+                  + " (2) the timestamp field to be used as an aggregation bucket (e.g., 'stats"
+                  + " count() by @timestamp').");
+        }
         throw Util.throwAsRuntime(e);
       }
     }

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

@@ -28,7 +28,11 @@ public RexNode createExpression(
     CountBin countBin = (CountBin) node;
 
     // Create validated binnable field (validates that field is numeric or time-based)
-    // 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);