Merge pull request #18694 from taosdata/fix/TS-2144

enh(query): add timetruncate function ignore timezone option for 1d

docs/en/12-taos-sql/10-function.md

@@ -532,7 +532,12 @@ TIMEDIFF(expr1, expr2 [, time_unit])
 #### TIMETRUNCATE
 
 ```sql
-TIMETRUNCATE(expr, time_unit)
+TIMETRUNCATE(expr, time_unit [, ignore_timezone])
+
+ignore_timezone: {
+    0
+  | 1
+}
 ```
 
 **Description**: Truncate the input timestamp with unit specified by `time_unit`
@@ -548,7 +553,10 @@ TIMETRUNCATE(expr, time_unit)
           1b (nanoseconds), 1u (microseconds), 1a (milliseconds), 1s (seconds), 1m (minutes), 1h (hours), 1d (days), or 1w (weeks)
 - The precision of the returned timestamp is same as the precision set for the current data base in use
 - If the input data is not formatted as a timestamp, the returned value is null.
-
+- If `1d` is used as `time_unit` to truncate the timestamp, `ignore_timezone` option can be set to indicate if the returned result is affected by client timezone or not.
+  For example, if client timezone is set to UTC+0800, TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) will return '2020-01-01 08:00:00'.
+  Otherwise, TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) will return '2020-01-01 00:00:00'.
+  If `ignore_timezone` option is omitted, the default value is set to 1.
 
 #### TIMEZONE
 

docs/zh/12-taos-sql/10-function.md

@@ -533,7 +533,12 @@ TIMEDIFF(expr1, expr2 [, time_unit])
 #### TIMETRUNCATE
 
 ```sql
-TIMETRUNCATE(expr, time_unit)
+TIMETRUNCATE(expr, time_unit [, ignore_timezone])
+
+ignore_timezone: {
+    0
+  | 1
+}
 ```
 
 **功能说明**：将时间戳按照指定时间单位 time_unit 进行截断。
@@ -549,6 +554,11 @@ TIMETRUNCATE(expr, time_unit)
           1b(纳秒), 1u(微秒)，1a(毫秒)，1s(秒)，1m(分)，1h(小时)，1d(天), 1w(周)。
 - 返回的时间戳精度与当前 DATABASE 设置的时间精度一致。
 - 输入包含不符合时间日期格式的字符串则返回 NULL。
+- 当使用 1d 作为时间单位对时间戳进行截断时， 可通过设置 ignore_timezone 参数指定返回结果的显示是否忽略客户端时区的影响。
+  例如客户端所配置时区为 UTC+0800, 则 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 0) 返回结果为 '2020-01-01 08:00:00'。
+  而使用 TIMETRUNCATE('2020-01-01 23:00:00', 1d, 1) 设置忽略时区时，返回结果为 '2020-01-01 00:00:00'
+  ignore_timezone 如果忽略的话，则默认值为 1 。
+
 
 
 #### TIMEZONE
@@ -1085,7 +1095,7 @@ ignore_negative: {
 
 ```sql
 DIFF(expr [, ignore_negative])
- 
+
 ignore_negative: {
     0
   | 1

source/libs/function/src/builtins.c

@@ -1924,7 +1924,8 @@ static int32_t translateToUnixtimestamp(SFunctionNode* pFunc, char* pErrBuf, int
 }
 
 static int32_t translateTimeTruncate(SFunctionNode* pFunc, char* pErrBuf, int32_t len) {
-  if (2 != LIST_LENGTH(pFunc->pParameterList)) {
+  int32_t numOfParams = LIST_LENGTH(pFunc->pParameterList);
+  if (2 != numOfParams && 3 != numOfParams) {
     return invaildFuncParaNumErrMsg(pErrBuf, len, pFunc->functionName);
   }
 
@@ -1935,9 +1936,7 @@ static int32_t translateTimeTruncate(SFunctionNode* pFunc, char* pErrBuf, int32_
     return invaildFuncParaTypeErrMsg(pErrBuf, len, pFunc->functionName);
   }
 
-  // add database precision as param
   uint8_t dbPrec = pFunc->node.resType.precision;
-
   int32_t ret = validateTimeUnitParam(dbPrec, (SValueNode*)nodesListGetNode(pFunc->pParameterList, 1));
   if (ret == TIME_UNIT_TOO_SMALL) {
     return buildFuncErrMsg(pErrBuf, len, TSDB_CODE_FUNC_FUNTION_ERROR,
@@ -1948,11 +1947,30 @@ static int32_t translateTimeTruncate(SFunctionNode* pFunc, char* pErrBuf, int32_
         "TIMETRUNCATE function time unit parameter should be one of the following: [1b, 1u, 1a, 1s, 1m, 1h, 1d, 1w]");
   }
 
+  if (3 == numOfParams) {
+    uint8_t para3Type = ((SExprNode*)nodesListGetNode(pFunc->pParameterList, 2))->resType.type;
+    if (!IS_INTEGER_TYPE(para3Type)) {
+      return invaildFuncParaTypeErrMsg(pErrBuf, len, pFunc->functionName);
+    }
+    SValueNode* pValue = (SValueNode*)nodesListGetNode(pFunc->pParameterList, 2);
+    if (pValue->datum.i != 0 && pValue->datum.i != 1) {
+      return invaildFuncParaValueErrMsg(pErrBuf, len, pFunc->functionName);
+    }
+  }
+
+  // add database precision as param
+
   int32_t code = addDbPrecisonParam(&pFunc->pParameterList, dbPrec);
   if (code != TSDB_CODE_SUCCESS) {
     return code;
   }
 
+  // add client timezone as param
+  code = addTimezoneParam(pFunc->pParameterList);
+  if (code != TSDB_CODE_SUCCESS) {
+    return code;
+  }
+
   pFunc->node.resType =
       (SDataType){.bytes = tDataTypes[TSDB_DATA_TYPE_TIMESTAMP].bytes, .type = TSDB_DATA_TYPE_TIMESTAMP};
   return TSDB_CODE_SUCCESS;

source/libs/scalar/src/sclfunc.c

@@ -1174,12 +1174,35 @@ int32_t toJsonFunction(SScalarParam *pInput, int32_t inputNum, SScalarParam *pOu
 }
 
 /** Time functions **/
+static int64_t offsetFromTz(char *timezone, int64_t factor) {
+  char *minStr = &timezone[3];
+  int64_t minutes = taosStr2Int64(minStr, NULL, 10);
+  memset(minStr, 0, strlen(minStr));
+  int64_t hours = taosStr2Int64(timezone, NULL, 10);
+  int64_t seconds = hours * 3600 + minutes * 60;
+
+  return seconds * factor;
+
+}
+
 int32_t timeTruncateFunction(SScalarParam *pInput, int32_t inputNum, SScalarParam *pOutput) {
   int32_t type = GET_PARAM_TYPE(&pInput[0]);
 
   int64_t timeUnit, timePrec, timeVal = 0;
+  bool    ignoreTz = true;
+  char    timezone[20] = {0};
+
   GET_TYPED_DATA(timeUnit, int64_t, GET_PARAM_TYPE(&pInput[1]), pInput[1].columnData->pData);
-  GET_TYPED_DATA(timePrec, int64_t, GET_PARAM_TYPE(&pInput[2]), pInput[2].columnData->pData);
+
+  int32_t timePrecIdx = 2, timeZoneIdx = 3;
+  if (inputNum == 5) {
+    timePrecIdx += 1;
+    timeZoneIdx += 1;
+    GET_TYPED_DATA(ignoreTz, bool, GET_PARAM_TYPE(&pInput[2]), pInput[2].columnData->pData);
+  }
+
+  GET_TYPED_DATA(timePrec, int64_t, GET_PARAM_TYPE(&pInput[timePrecIdx]), pInput[timePrecIdx].columnData->pData);
+  memcpy(timezone, varDataVal(pInput[timeZoneIdx].columnData->pData), varDataLen(pInput[timeZoneIdx].columnData->pData));
 
   int64_t factor = TSDB_TICK_PER_SECOND(timePrec);
   int64_t unit = timeUnit * 1000 / factor;
@@ -1294,13 +1317,29 @@ int32_t timeTruncateFunction(SScalarParam *pInput, int32_t inputNum, SScalarPara
       }
       case 86400000: { /* 1d */
         if (tsDigits == TSDB_TIME_PRECISION_MILLI_DIGITS) {
-          timeVal = timeVal / 1000 / 86400 * 86400 * 1000;
+          if (ignoreTz) {
+            timeVal = timeVal - (timeVal + offsetFromTz(timezone, 1000)) % (86400L * 1000);
+          } else {
+            timeVal = timeVal / 1000 / 86400 * 86400 * 1000;
+          }
         } else if (tsDigits == TSDB_TIME_PRECISION_MICRO_DIGITS) {
-          timeVal = timeVal / 1000000 / 86400 * 86400 * 1000000;
+          if (ignoreTz) {
+            timeVal = timeVal - (timeVal + offsetFromTz(timezone, 1000000)) % (86400L * 1000000);
+          } else {
+            timeVal = timeVal / 1000000 / 86400 * 86400 * 1000000;
+          }
         } else if (tsDigits == TSDB_TIME_PRECISION_NANO_DIGITS) {
-          timeVal = timeVal / 1000000000 / 86400 * 86400 * 1000000000;
+          if (ignoreTz) {
+            timeVal = timeVal - (timeVal + offsetFromTz(timezone, 1000000000)) % (86400L * 1000000000);
+          } else {
+            timeVal = timeVal / 1000000000 / 86400 * 86400 * 1000000000;
+          }
         } else if (tsDigits <= TSDB_TIME_PRECISION_SEC_DIGITS) {
-          timeVal = timeVal * factor / factor / 86400 * 86400 * factor;
+          if (ignoreTz) {
+            timeVal = (timeVal - (timeVal + offsetFromTz(timezone, 1)) % (86400L)) * factor;
+          } else {
+            timeVal = timeVal * factor / factor / 86400 * 86400 * factor;
+          }
         } else {
           colDataAppendNULL(pOutput->columnData, i);
           continue;

tests/system-test/2-query/timetruncate.py

@@ -30,7 +30,7 @@ class TDTestCase:
         self.stbname = f'{self.dbname}.stb'
         self.ctbname = f'{self.dbname}.ctb'
 
-    def check_ms_timestamp(self,unit,date_time):
+    def check_ms_timestamp(self,unit,date_time, ignore_tz):
         if unit.lower() == '1a':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_ms_timestamp(str(tdSql.queryResult[i][0]))
@@ -50,13 +50,17 @@ class TDTestCase:
         elif unit.lower() == '1d':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_ms_timestamp(str(tdSql.queryResult[i][0]))
-                tdSql.checkEqual(ts_result,int(date_time[i]/1000/60/60/24)*24*60*60*1000)
+                if ignore_tz == 0:
+                    tdSql.checkEqual(ts_result,int(date_time[i]/1000/60/60/24)*24*60*60*1000)
+                else:
+                    # assuming the client timezone is UTC+0800
+                    tdSql.checkEqual(ts_result,int(date_time[i] - (date_time[i] + 8 * 3600 * 1000) % (86400 * 1000)))
         elif unit.lower() == '1w':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_ms_timestamp(str(tdSql.queryResult[i][0]))
                 tdSql.checkEqual(ts_result,int(date_time[i]/1000/60/60/24/7)*7*24*60*60*1000)
 
-    def check_us_timestamp(self,unit,date_time):
+    def check_us_timestamp(self,unit,date_time, ignore_tz):
         if unit.lower() == '1u':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_us_timestamp(str(tdSql.queryResult[i][0]))
@@ -80,13 +84,17 @@ class TDTestCase:
         elif unit.lower() == '1d':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_us_timestamp(str(tdSql.queryResult[i][0]))
-                tdSql.checkEqual(ts_result,int(date_time[i]/1000/1000/60/60/24)*24*60*60*1000*1000 )
+                if ignore_tz == 0:
+                    tdSql.checkEqual(ts_result,int(date_time[i]/1000/1000/60/60/24)*24*60*60*1000*1000 )
+                else:
+                    # assuming the client timezone is UTC+0800
+                    tdSql.checkEqual(ts_result,int(date_time[i] - (date_time[i] + 8 * 3600 * 1000000) % (86400 * 1000000)))
         elif unit.lower() == '1w':
             for i in range(len(self.ts_str)):
                 ts_result = self.get_time.get_us_timestamp(str(tdSql.queryResult[i][0]))
                 tdSql.checkEqual(ts_result,int(date_time[i]/1000/1000/60/60/24/7)*7*24*60*60*1000*1000)
 
-    def check_ns_timestamp(self,unit,date_time):
+    def check_ns_timestamp(self,unit,date_time, ignore_tz):
         if unit.lower() == '1b':
             for i in range(len(self.ts_str)):
                 if self.rest_tag != 'rest':
@@ -114,21 +122,26 @@ class TDTestCase:
         elif unit.lower() == '1d':
             for i in range(len(self.ts_str)):
                 if self.rest_tag != 'rest':
-                    tdSql.checkEqual(tdSql.queryResult[i][0],int(date_time[i]*1000/1000/1000/1000/1000/60/60/24)*24*60*60*1000*1000*1000 )
+                    if ignore_tz == 0:
+                        tdSql.checkEqual(tdSql.queryResult[i][0],int(date_time[i]*1000/1000/1000/1000/1000/60/60/24)*24*60*60*1000*1000*1000 )
+                    else:
+                        # assuming the client timezone is UTC+0800
+                        tdSql.checkEqual(tdSql.queryResult[i][0],int(date_time[i] - (date_time[i] + 8 * 3600 * 1000000) % (86400 * 1000000)))
         elif unit.lower() == '1w':
             for i in range(len(self.ts_str)):
                 if self.rest_tag != 'rest':
                     tdSql.checkEqual(tdSql.queryResult[i][0],int(date_time[i]*1000/1000/1000/1000/1000/60/60/24/7)*7*24*60*60*1000*1000*1000)
 
-    def check_tb_type(self,unit,tb_type):
+    def check_tb_type(self,unit,tb_type,ignore_tz):
         if tb_type.lower() == 'ntb':
-            tdSql.query(f'select timetruncate(ts,{unit}) from {self.ntbname}')
+            tdSql.query(f'select timetruncate(ts,{unit},{ignore_tz}) from {self.ntbname}')
         elif tb_type.lower() == 'ctb':
-            tdSql.query(f'select timetruncate(ts,{unit}) from {self.ctbname}')
+            tdSql.query(f'select timetruncate(ts,{unit},{ignore_tz}) from {self.ctbname}')
         elif tb_type.lower() == 'stb':
-            tdSql.query(f'select timetruncate(ts,{unit}) from {self.stbname}')
+            tdSql.query(f'select timetruncate(ts,{unit},{ignore_tz}) from {self.stbname}')
 
     def data_check(self,date_time,precision,tb_type):
+        tz_options = [0, 1]
         for unit in self.time_unit:
             if (unit.lower() == '1u' and precision.lower() == 'ms') or (unit.lower() == '1b' and precision.lower() == 'us') or (unit.lower() == '1b' and precision.lower() == 'ms'):
                 if tb_type.lower() == 'ntb':
@@ -138,17 +151,20 @@ class TDTestCase:
                 elif tb_type.lower() == 'stb':
                     tdSql.error(f'select timetruncate(ts,{unit}) from {self.stbname}')
             elif precision.lower() == 'ms':
-                self.check_tb_type(unit,tb_type)
-                tdSql.checkRows(len(self.ts_str))
-                self.check_ms_timestamp(unit,date_time)
+                for ignore_tz in tz_options:
+                    self.check_tb_type(unit,tb_type,ignore_tz)
+                    tdSql.checkRows(len(self.ts_str))
+                    self.check_ms_timestamp(unit,date_time,ignore_tz)
             elif precision.lower() == 'us':
-                self.check_tb_type(unit,tb_type)
-                tdSql.checkRows(len(self.ts_str))
-                self.check_us_timestamp(unit,date_time)
+                for ignore_tz in tz_options:
+                    self.check_tb_type(unit,tb_type,ignore_tz)
+                    tdSql.checkRows(len(self.ts_str))
+                    self.check_us_timestamp(unit,date_time,ignore_tz)
             elif precision.lower() == 'ns':
-                self.check_tb_type(unit,tb_type)
-                tdSql.checkRows(len(self.ts_str))
-                self.check_ns_timestamp(unit,date_time)
+                for ignore_tz in tz_options:
+                    self.check_tb_type(unit,tb_type, ignore_tz)
+                    tdSql.checkRows(len(self.ts_str))
+                    self.check_ns_timestamp(unit,date_time,ignore_tz)
         for unit in self.error_unit:
             if tb_type.lower() == 'ntb':
                 tdSql.error(f'select timetruncate(ts,{unit}) from {self.ntbname}')
@@ -181,8 +197,8 @@ class TDTestCase:
             date_time = self.get_time.time_transform(self.ts_str,precision)
             self.data_check(date_time,precision,'ctb')
             self.data_check(date_time,precision,'stb')
-    
-   
+
+
     def run(self):
         self.function_check_ntb()
         self.function_check_stb()