revise 5476

julianhyde · Mar 20, 2023 · 9299057 · 9299057
1 parent 42bb9fb
commit 9299057
Show file tree

Hide file tree

Showing 2 changed files with 70 additions and 55 deletions.
diff --git a/core/src/main/java/org/apache/calcite/sql/fun/SqlLibraryOperators.java b/core/src/main/java/org/apache/calcite/sql/fun/SqlLibraryOperators.java
@@ -529,7 +529,8 @@ private SqlLibraryOperators() {
 
   /** The "DATETIME" function returns a Calcite
    * {@code TIMESTAMP} (which BigQuery calls a {@code DATETIME}).
-   * It has the following overloads:
+   *
+   * <p>It has the following overloads:
    *
    * <ul>
    *   <li>{@code DATETIME(year, month, day, hour, minute, second)}
@@ -838,7 +839,10 @@ private SqlLibraryOperators() {
           SqlFunctionCategory.STRING);
 
   /** The "FORMAT_DATETIME(string, timestamp)" function (BigQuery);
-   * Formats a timestamp object according to the specified string. */
+   * formats a timestamp object according to the specified string.
+   *
+   * <p>Note that the {@code TIMESTAMP} type of Calcite and Standard SQL
+   * is called {@code DATETIME} in BigQuery. */
   @LibraryOperator(libraries = {BIG_QUERY})
   public static final SqlFunction FORMAT_DATETIME =
       SqlBasicFunction.create("FORMAT_DATETIME",
@@ -938,15 +942,23 @@ private SqlLibraryOperators() {
           OperandTypes.TIMESTAMP_INTERVAL)
           .withFunctionType(SqlFunctionCategory.TIMEDATE);
 
-  /** BigQuery's {@code DATETIME_SUB(timestamp, interval)} function
-   * is a synonym for TIMESTAMP_SUB because in Calcite, DATETIME
-   * is an alias for TIMESTAMP. */
+  /** The "DATETIME_SUB(timestamp, interval)" function (BigQuery).
+   *
+   * <p>Note that the {@code TIMESTAMP} type of Calcite and Standard SQL
+   * is called {@code DATETIME} in BigQuery.
+   *
+   * <p>A synonym for {@link #TIMESTAMP_SUB}, which supports both
+   * {@code TIMESTAMP} and {@code TIMESTAMP WITH LOCAL TIME ZONE} operands. */
   @LibraryOperator(libraries = {BIG_QUERY})
   public static final SqlFunction DATETIME_SUB =
       TIMESTAMP_SUB.withName("DATETIME_SUB");
 
   /** The "TIMESTAMP_TRUNC(timestamp, timeUnit[, timeZone])" function (BigQuery);
-   * truncates a TIMESTAMP value to the beginning of a timeUnit. */
+   * truncates a {@code TIMESTAMP WITH LOCAL TIME ZONE} value to the beginning
+   * of a timeUnit.
+   *
+   * <p>Note that the {@code TIMESTAMP WITH LOCAL TIME ZONE} type of Calcite
+   * is called {@code TIMESTAMP} in BigQuery. */
   @LibraryOperator(libraries = {BIG_QUERY})
   public static final SqlFunction TIMESTAMP_TRUNC =
       SqlBasicFunction.create("TIMESTAMP_TRUNC",
@@ -956,18 +968,18 @@ private SqlLibraryOperators() {
               OperandTypes.TIMESTAMP, OperandTypes.timestampInterval()),
           SqlFunctionCategory.TIMEDATE);
 
-  /** The "DATETIME_TRUNC(timestamp, timeUnit)"
-   * function (BigQuery); truncates a timestamp value to the granularity of
-   * timeUnit. The timestamp value is always rounded to the beginning of
-   * timeUnit. */
+  /** The "DATETIME_TRUNC(timestamp, timeUnit)" function (BigQuery);
+   * truncates a TIMESTAMP value to the beginning of a timeUnit.
+   *
+   * <p>Note that the {@code TIMESTAMP} type of Calcite and Standard SQL
+   * is called {@code DATETIME} in BigQuery. */
   @LibraryOperator(libraries = {BIG_QUERY})
   public static final SqlFunction DATETIME_TRUNC =
-      SqlBasicFunction.create(
-        "DATETIME_TRUNC",
-        ReturnTypes.TIMESTAMP_NULLABLE,
-        OperandTypes.sequence(
-            "'DATETIME_TRUNC(<TIMESTAMP>, <DATETIME_INTERVAL>)'",
-            OperandTypes.TIMESTAMP, OperandTypes.timestampInterval()),
+      SqlBasicFunction.create("DATETIME_TRUNC",
+          ReturnTypes.TIMESTAMP_NULLABLE,
+          OperandTypes.sequence(
+              "'DATETIME_TRUNC(<TIMESTAMP>, <DATETIME_INTERVAL>)'",
+              OperandTypes.TIMESTAMP, OperandTypes.timestampInterval()),
           SqlFunctionCategory.TIMEDATE);
 
   /** The "TIMESTAMP_SECONDS(bigint)" function; returns a TIMESTAMP value
@@ -1024,7 +1036,10 @@ private SqlLibraryOperators() {
   public static final SqlFunction DATETIME_ADD =
       TIMESTAMP_ADD2.withName("DATETIME_ADD");
 
-  /** The "DATETIME_DIFF(timestamp, timestamp2, timeUnit)" function (BigQuery). */
+  /** The "DATETIME_DIFF(timestamp, timestamp2, timeUnit)" function (BigQuery).
+   *
+   * <p>Note that the {@code TIMESTAMP} type of Calcite and Standard SQL
+   * is called {@code DATETIME} in BigQuery. */
   @LibraryOperator(libraries = {BIG_QUERY})
   public static final SqlFunction DATETIME_DIFF =
       new SqlTimestampDiffFunction("DATETIME_DIFF",

diff --git a/testkit/src/main/java/org/apache/calcite/test/SqlOperatorTest.java b/testkit/src/main/java/org/apache/calcite/test/SqlOperatorTest.java
@@ -8752,6 +8752,44 @@ void testTimestampDiff(boolean coercionEnabled) {
         "2015-01-01 00:00:00", "TIMESTAMP(0) NOT NULL");
   }
 
+  @Test void testDatetimeTrunc() {
+    SqlOperatorFixture nonBigQuery = fixture()
+        .setFor(SqlLibraryOperators.DATETIME_TRUNC);
+    nonBigQuery.checkFails("^datetime_trunc(timestamp '2012-05-02 15:30:00', hour)^",
+        "No match found for function signature "
+            + "DATETIME_TRUNC\\(<TIMESTAMP>, <INTERVAL_DAY_TIME>\\)",
+        false);
+
+    final SqlOperatorFixture f = fixture()
+        .withLibrary(SqlLibrary.BIG_QUERY)
+        .setFor(SqlLibraryOperators.DATETIME_TRUNC);
+    f.checkFails("^datetime_trunc(100, hour)^",
+        "Cannot apply 'DATETIME_TRUNC' to arguments of type "
+            + "'DATETIME_TRUNC\\(<INTEGER>, <INTERVAL HOUR>\\)'\\. "
+            + "Supported form\\(s\\): 'DATETIME_TRUNC\\(<TIMESTAMP>, <DATETIME_INTERVAL>\\)'",
+        false);
+    f.checkFails("^datetime_trunc(100, foo)^",
+        "Cannot apply 'DATETIME_TRUNC' to arguments of type "
+            + "'DATETIME_TRUNC\\(<INTEGER>, <INTERVAL `FOO`>\\)'\\. "
+            + "Supported form\\(s\\): 'DATETIME_TRUNC\\(<TIMESTAMP>, <DATETIME_INTERVAL>\\)'",
+        false);
+
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56.78', second)",
+        "2015-02-19 12:34:56", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', minute)",
+        "2015-02-19 12:34:00", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', hour)",
+        "2015-02-19 12:00:00", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', day)",
+        "2015-02-19 00:00:00", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', week)",
+        "2015-02-15 00:00:00", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', month)",
+        "2015-02-01 00:00:00", "TIMESTAMP(0) NOT NULL");
+    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', year)",
+        "2015-01-01 00:00:00", "TIMESTAMP(0) NOT NULL");
+  }
+
   @Test void testDateTrunc() {
     final SqlOperatorFixture f = fixture()
         .withLibrary(SqlLibrary.BIG_QUERY)
@@ -8876,44 +8914,6 @@ void testTimestampDiff(boolean coercionEnabled) {
         "VARCHAR(2000) NOT NULL");
   }
 
-  @Test void testDatetimeTrunc() {
-    SqlOperatorFixture nonBigQuery = fixture()
-        .setFor(SqlLibraryOperators.DATETIME_TRUNC);
-    nonBigQuery.checkFails("^datetime_trunc(timestamp '2012-05-02 15:30:00', hour)^",
-        "No match found for function signature "
-            + "DATETIME_TRUNC\\(<TIMESTAMP>, <INTERVAL_DAY_TIME>\\)",
-        false);
-
-    final SqlOperatorFixture f = fixture()
-        .withLibrary(SqlLibrary.BIG_QUERY)
-        .setFor(SqlLibraryOperators.DATETIME_TRUNC);
-    f.checkFails("^datetime_trunc(100, hour)^",
-        "Cannot apply 'DATETIME_TRUNC' to arguments of type "
-            + "'DATETIME_TRUNC\\(<INTEGER>, <INTERVAL HOUR>\\)'\\. "
-            + "Supported form\\(s\\): 'DATETIME_TRUNC\\(<TIMESTAMP>, <DATETIME_INTERVAL>\\)'",
-        false);
-    f.checkFails("^datetime_trunc(100, foo)^",
-        "Cannot apply 'DATETIME_TRUNC' to arguments of type "
-            + "'DATETIME_TRUNC\\(<INTEGER>, <INTERVAL `FOO`>\\)'\\. "
-            + "Supported form\\(s\\): 'DATETIME_TRUNC\\(<TIMESTAMP>, <DATETIME_INTERVAL>\\)'",
-        false);
-
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56.78', second)",
-        "2015-02-19 12:34:56", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', minute)",
-        "2015-02-19 12:34:00", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', hour)",
-        "2015-02-19 12:00:00", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', day)",
-        "2015-02-19 00:00:00", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', week)",
-        "2015-02-15 00:00:00", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', month)",
-        "2015-02-01 00:00:00", "TIMESTAMP(0) NOT NULL");
-    f.checkScalar("datetime_trunc(timestamp '2015-02-19 12:34:56', year)",
-        "2015-01-01 00:00:00", "TIMESTAMP(0) NOT NULL");
-  }
-
   @Test void testDenseRankFunc() {
     final SqlOperatorFixture f = fixture();
     f.setFor(SqlStdOperatorTable.DENSE_RANK, VM_FENNEL, VM_JAVA);