IoT Platform：日期函數

CURRENT_TIMESTAMP

• 命令格式

  timestamp current_timestamp()

• 命令說明

  返回當前TIMESTAMP類型的時間戳記，值不固定。

• 傳回值說明

  返回TIMESTAMP類型。

• 樣本

  --返回'2017-08-03 11:50:30.661'。
      current_timestamp(); 

DATEADD

• 命令格式

  datetime dateadd(datetime <date>, bigint <delta>, string <datepart>)

• 命令說明

  按照指定的單位datepart和幅度delta修改date的值。如果您需要擷取在目前時間基礎上指定變動幅度的日期，請結合GETDATE函數使用。

• 參數說明
  • date：必填。日期值，DATETIME類型。

    如果參數為STRING類型，則會隱式轉換為DATETIME類型後參與運算。參數為其他資料類型時會返回報錯。

  • delta：必填。修改幅度，BIGINT類型。如果delta大於0，則增，否則減。

    如果參數為STRING或DOUBLE類型，則會隱式轉換為BIGINT類型後參與運算。參數為其他資料類型時會返回報錯。

    說明

    • 按照指定的單位增減delta時，會導致更高單位的進位或退位。年、月、時、分秒分別按照10進位、12進位、24進位、60進位進行計算。
    • 當delta的單位是月時，如果delta的月部分在增加delta值之後不造成Day溢出，則保持Day值不變，否則將Day值設定為結果月份的最後1天。
  • datepart：必填。指定修改的單位，STRING類型常量。非常量、不支援的格式或其他類型會返回報錯。

    此欄位的取值遵循STRING與DATETIME類型轉換的約定，即yyyy表示年，mm表示月，dd表示天。關於類型轉換的規則，請參見下文STRING與DATETIME類型之間的轉換。該欄位也支援擴充的日期格式：年-year、月-month或-mon、日-day和小時-hour。

• 傳回值說明

  返回DATETIME類型。如果任一輸入參數為NULL，則返回NULL。

• 樣本
  • 樣本1：trans_date=2005-02-28 00:00:00。

    --返回2005-03-01 00:00:00。加1天，結果超出當年2月份的最後一天，實際值為下個月的第1天。
        dateadd(trans_date, 1, 'dd');
    
    --返回2005-02-27 00:00:00。減1天。
        dateadd(trans_date, -1, 'dd');
    
    --返回2006-10-28 00:00:00。加20個月，月份溢出，年份加1。
        dateadd(trans_date, 20, 'mm');
    
    --返回2005-03-28 00:00:00。
        dateadd(trans_date, 1, 'mm');

  • 樣本2：trans_date=2005-01-29 00:00:00。

    --返回2005-02-28 00:00:00。2005年2月沒有29日，日期截取至當月最後1天。
        dateadd(trans_date, 1, 'mm');

  • 樣本3：trans_date2005-03-30 00:00:00。

    --返回2005-02-28 00:00:00。
        dateadd(trans_date, -1, 'mm');

  • 樣本4：計算目前時間。

    --假設目前時間為2020-11-17 16:31:44，返回2020-11-16 16:31:44。
        dateadd(getdate(),-1,'dd');

  • 樣本5：將STRING類型常量顯式轉換為DATETIME類型。

    --返回2005-02-28 00:00:00。
        dateadd(cast("2005-03-30 00:00:00" as datetime), -1, 'mm');

DATEDIFF

• 命令格式

  bigint datediff(datetime <date1>, datetime <date2>, string <datepart>)

• 命令說明

  計算兩個時間date1、date2的差值，將差值以指定的時間單位datepart表示。

• 參數說明
  • date1、date2：必填。DATETIME類型，被減數和減數。如果輸入為STRING類型，則會隱式轉換為DATETIME類型後參與運算。其他資料類型會返回報錯。
  • datepart：必填。指定修改的單位，STRING類型常量。非常量、不支援的格式或其他類型會返回報錯。

    此欄位的取值遵循STRING與DATETIME類型轉換的約定，即yyyy表示年，mm表示月，dd表示天。關於類型轉換的規則，請參見下文STRING與DATETIME類型之間的轉換。該欄位也支援擴充的日期格式：年-year、月-month或-mon、日-day和小時-hour。

    說明 系統計算時會按照datepart切掉低單位部分，然後再計算結果。
• 傳回值說明

  返回BIGINT類型。如果任一輸入參數為NULL，則返回NULL。如果date1小於date2，傳回值為負數。

• 樣本
  • 樣本1：start=2005-12-31 23:59:59，end=2006-01-01 00:00:00。

    --返回1。
        datediff(end, start, 'dd'); 
    
    --返回1。
        datediff(end, start, 'mm');
    
    --返回1。
        datediff(end, start, 'yyyy');
    
    --返回1。
        datediff(end, start, 'hh');
    
    --返回1。
        datediff(end, start, 'mi');
    
    --返回1。
        datediff(end, start, 'ss');
    
    --返回1800。
        datediff(datetime'2013-05-31 13:00:00', '2013-05-31 12:30:00', 'ss');
    
    --返回30。
        datediff(datetime'2013-05-31 13:00:00', '2013-05-31 12:30:00', 'mi');  

  • 樣本2：start = 2018-06-04 19:33:23.234，end = 2018-06-04 19:33:23.250，含毫秒的日期不屬於標準DATETIME式樣，不能直接隱式轉換，此處需進行顯示轉換。

    --返回16。
        datediff(to_date('2018-06-04 19:33:23.250', 'yyyy-mm-dd hh:mi:ss.ff3'), to_date('2018-06-04 19:33:23.234', 'yyyy-mm-dd hh:mi:ss.ff3') , 'ff3');

FROM_UNIXTIME

• 命令格式

  datetime from_unixtime(bigint <unixtime>)

• 命令說明

  將數字型的UNIX時間日期值unixtime轉為日期值。

• 參數說明

  unixtime：必填。BIGINT類型，秒數，UNIX格式的日期時間值。如果輸入為STRING、DOUBLE或DECIMAL類型，則會隱式轉換為BIGINT後參與運算。

• 傳回值說明

  返回DATETIME類型的日期值。如果輸入參數為NULL，則返回NULL。

• 樣本

  --返回1973-11-30 05:33:09。
      from_unixtime(123456789);

FROM_UTC_TIMESTAMP

• 命令格式

  timestamp from_utc_timestamp({any primitive type}*, string <timezone>)

• 命令說明

  將一個UTC時區的時間戳記轉換成一個指定時區的時間戳記。

• 參數說明
  • {any primitive type}*：必填。時間戳記，支援TIMESTAMP、DATETIME、TINYINT、SMALLINT、INT或BIGINT資料類型。如果該參數為TINYINT、SMALLINT、INT或BIGINT資料類型，則單位為毫秒。
  • timezone：必填。指定需要轉換的目標時區，例如PST。

    本函數只支援Asia、Shanghai這種格式，不支援GMT+9這種格式。

    UTC時間為0時區時間，上海為東八區，對應上海時間為UTC+8小時。

• 傳回值說明

  返回TIMESTAMP類型。

• 樣本

  --輸入參數為毫秒（ms），返回2017-08-01 04:24:00.0。
      from_utc_timestamp(1501557840000, 'PST'); 
  
  --返回1970-01-30 08:00:00.0。
      from_utc_timestamp('1970-01-30 16:00:00','PST'); 
  
  --返回1970-01-29 16:00:00.0。
      from_utc_timestamp('1970-01-30','PST') ; 

GETDATE

• 命令格式

  datetime getdate()

• 命令說明

  擷取當前系統時間。

• 傳回值說明

  返回當前日期和時間，DATETIME類型。

ISDATE

• 命令格式

  boolean isdate(string <date>, string <format>)

• 命令說明

  判斷一個日期文字能否根據指定的格式串轉換為一個日期值。如果能轉換成功，返回True；否則返回False。

• 參數說明
  • date：必填。STRING類型。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，會隱式轉換為STRING類型後參與運算。輸入為其他資料類型會返回報錯。
  • format：必填。STRING類型常量，不支援日期擴充格式。輸入其他資料類型會返回報錯。如果format中出現多餘的格式串，則只取第一個格式串對應的日期數值，其餘的會被視為分隔字元。
• 傳回值說明

  返回BOOLEAN類型。如果任一輸入參數為NULL，則返回NULL。

• 樣本

  --返回True。
  isdate("1234-yyyy", "yyyy-yyyy");

TO_DATE

• 命令格式

  datetime to_date(string <date>, string <format>)

• 命令說明

  將date轉換成符合format格式的日期值。

• 參數說明
  • date：必填。STRING類型，要轉換的字串格式的日期值。如果輸入為BIGINT、DOUBLE、DECIMAL或DATETIME類型，則會隱式轉換為STRING類型後參與運算，輸入為其他類型或者空串時會返回報錯。
  • format：必填。STRING類型常量，日期格式。輸入其他資料類型會返回報錯。format不支援日期擴充格式，其他字元在解析時當作無用字元忽略。

    format：參數至少包含yyyy，否則會返回NULL。如果format中出現多餘的格式串，則只取第一個格式串對應的日期數值，其餘的會被視為分隔字元。例如to_date("1234-2234", "yyyy-yyyy")會返回1234-01-01 00:00:00。

    format格式：yyyy為4位元的年，mm為2位元的月，dd為2位元的日，hh為24小時制的時，mi為2位元的分鐘，ss為2位元秒，ff3為3位精度毫秒。

• 傳回值說明

  返回DATETIME類型，格式為yyyy-mm-dd hh:mi:ss。如果任一輸入參數為NULL，則返回NULL。

• 樣本

  --返回2010-12-03 00:00:00。
      to_date('測試2010-12*03', '測試yyyy-mm*dd');
  
  --返回2008-07-18 00:00:00。
      to_date('20080718', 'yyyymmdd');
  
  --返回2008-07-18 20:30:00。
      to_date('200807182030','yyyymmddhhmi');
  
  --'2008718'無法轉為標準日期值，引發異常，應該為'20080718'。
      to_date('2008718', 'yyyymmdd');
  
  --'測試2010-12*3'無法轉為標準日期值，引發異常，應該為'測試2010-12*03'。
      to_date('測試2010-12*3', '測試yyyy-mm*dd');
  
  --'2010-24-01'無法轉為標準日期值，引發異常，應該為'2010-01-24'。
      to_date('2010-24-01', 'yyyy');
  
  --返回2018-10-30 15:13:12。
      to_date('20181030 15-13-12.345','yyyymmdd hh-mi-ss.ff3');

TO_CHAR

• 命令格式

  string to_char(datetime <date>, string <format>)

• 命令說明

  將日期類型date按照format指定的格式轉成字串。

• 參數說明
  • date：必填。DATETIME類型，要轉換的日期值。如果輸入為STRING類型，會隱式轉換為DATETIME類型後參與運算。輸入為其他資料類型會返回報錯。
  • format：必填。STRING類型常量。非常量或其他資料類型會返回報錯。format中的日期格式部分會被替換成相應的資料，其他字元直接輸出。
• 傳回值說明

  返回STRING類型。如果任一輸入參數為NULL，則返回NULL。

• 樣本

  --返回20080718。
      to_char(datetime'2008-07-18 00:00:00', 'yyyymmdd');
  
  --'測試2010-12*3'無法轉換為符合要求的格式，會引發異常，應該為'測試2010-12*03'。
      to_char(datetime'測試2010-12*3', '測試yyyy-mm*dd');
  
  --'2010-24-01'不是標準日期值，引發異常，應該為'2010-01-24'。
      to_char(datetime'2010-24-01', 'yyyy');
  
  --'2008718'不是標準日期值，引發異常，應該為'20080718'。
      to_char(datetime'2008718', 'yyyymmdd');

UNIX_TIMESTAMP

• 命令格式

  bigint unix_timestamp(datetime <date>)

• 命令說明

  將日期date轉化為整型的UNIX格式的日期時間值。

• 參數說明

  date：必填。DATETIME類型日期值。如果輸入為STRING類型，則會隱式轉換為DATETIME類型後參與運算。輸入為其他資料類型會返回報錯。當開啟新資料類型屬性時，隱式轉換會失敗，此時需要通過cast函數轉換，例如unix_timestamp(cast(... as datetime))。

• 傳回值說明

  返回BIGINT類型，表示UNIX格式日期值。參數輸入值為NULL時，返回NULL值。

• 樣本

  --返回1237518660。
      unix_timestamp(datetime'2009-03-20 11:11:00'); 

LAST_DAY

• 命令格式

  string last_day(string <date>)

• 命令說明

  返回該日期所在月份的最後一天日期。

• 參數說明

  date：必填。STRING類型日期值，格式至少包含yyyy-mm-dd，其他類型將返回NULL。

• 傳回值說明

  返回STRING類型的日期值，格式為yyyy-mm-dd。

• 樣本

  --返回2017-03-31。
      last_day('2017-03-04');
  
  --返回2017-07-31。
      last_day('2017-07-04 11:40:00');
  
  --返回NULL。
      last_day('20170304');

STRING與DATETIME類型之間的轉換

STRING類型和DATETIME類型之間的相互轉換時，使用的格式為yyyy-mm-dd hh:mi:ss。