Updated on 2025-09-07 GMT+08:00

Date and Time functions

This section describes date and time functions, including their syntax, parameters, and usage examples.

In DSL processing, all values in logs are stored as strings. Convert the data type as required.

This section introduces the date and time functions used to convert the formats of time data in logs. There are three types of time data:

  • String: for example, 2022/07/03 02-41-26
  • Unix timestamp: for example, 1559500886
  • Date and time object: for example, 2022-07-01 10:10:10+08:00 or 2022-07-01 10:10:10

    Unix timestamps are essentially strings. Only the dt_parse, dt_str, and dt_parsetimestamp functions support the preceding three data types as parameters.

Function List

Type

Function

Description

General date and time conversion

dt_parse

Converts a value or time expression to a datetime object.

dt_str

Converts a value or time expression to a string.

dt_parsetimestamp

Converts a value or time expression to a Unix timestamp.

dt_prop

Extracts specific attributes, such as day and year, from a value or time expression.

Date and time obtaining

dt_now

Obtains the current datetime object.

dt_today

Obtains the current date, excluding the time.

dt_utcnow

Obtains the current datetime object of the current time zone.

dt_fromtimestamp

Converts a Unix timestamp to a datetime object.

dt_utcfromtimestamp

Converts a Unix timestamp to a datetime object of the current time zone.

dt_strptime

Parses a time string into a datetime object.

Unix timestamp obtaining

dt_currentstamp

Obtains the current Unix timestamp.

dt_totimestamp

Converts a datetime object to a Unix timestamp.

Date and time string obtaining

dt_strftime

Converts a datetime object to a string in a specific format.

dt_strftimestamp

Converts a Unix timestamp to a string in a specific format.

Data and time modification

dt_truncate

Truncates a specific time granularity from a value or time expression.

dt_add

Changes a value or time expression based on a specific time granularity.

dt_MO

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Monday.

dt_TU

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Tuesday.

dt_WE

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Wednesday.

dt_TH

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Thursday.

dt_FR

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Friday.

dt_SA

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Saturday.

dt_SU

Returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Sunday.

Time zone change

dt_astimezone

Converts a value or time expression to a datetime object of a specific time zone.

Difference obtaining

dt_diff

Obtains the difference between two values or time expressions based on a specific granularity.

dt_parse

This function converts a value or time expression to a datetime object.

  • Function format
    dt_parse(value, tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    The converted datetime object.

  • Function example
    1. Example 1: Convert the value of time to a datetime object.
      • Test data
        {
          "time": "1559500886"
        }
      • Processing rule
        e_set("test_time", dt_parse(v("time")))
      • Processing result
        time: 1559500886
        test_time: 2019-06-02 18:41:26 
    2. Example 2: Convert the value of time to a datetime object. Time zone: Shanghai.
      • Test data
        {
         "time": "2019-06-01 10:10:10"
         "tz": "Asia/Shanghai"
        }
      • Processing rule
        e_set("test_time", dt_parse(v("time"),tz=v("tz")))
      • Processing result
        time: 2019-06-01 10:10:10
        tz: Asia/Shanghai 
        test_time: 2019-06-01 10:10:10+08:00

dt_str

This function converts a value or time expression to a string.

  • Function format
    dt_str(value, fmt="format_string", tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    fmt

    String

    No

    Format string.

    tz

    String

    No

    Time zone.

  • Returned result

    The converted time string.

  • Function example
    1. Example 1: Convert the value of time to the fmt format. Time zone: Tokyo.
      • Test data
        {
         "time": "2019-06-03 02:41:26",
         "fmt": "%Y/%m/%d %H-%M-%S" ,
         "tz": "Asia/Tokyo"
        }
      • Processing rule
        e_set("dt_str", dt_str(v("time"),fmt=v("fmt"),tz=v("tz")))
      • Processing result
        {
         "time": "2019-06-03 02:41:26"
         "fmt": "%Y/%m/%d %H-%M-%S" 
         "tz": "Asia/Tokyo" 
         "dt_str": "2019/06/03 02-41-26"
        }
    2. Example 2: Convert the value of time (Unix timestamp) to the fmt format.
      • Test data
        {
         "time": "1559500886",
         "fmt": "%Y/%m/%d %H-%M-%S"
        }
      • Processing rule
        e_set("dt_str", dt_str(v("time"),fmt=v("fmt")))
      • Processing result
        time: 1559500886
        fmt: %Y/%m/%d %H-%M-%S 
        dt_str: 2019/06/02 18-41-26
    3. Example 3: Convert the value of time to the default format.
      • Test data
        {
         "time": "2019-06-03 02:41:26"
        }
      • Processing rule
        e_set("dt_str", dt_str(v("time")))
      • Processing result
        time: 2019-06-03 02:41:26
        dt_str: 2019-06-03 02:41:26

dt_parsetimestamp

This function converts a value or time expression to a Unix timestamp.

  • Function format
    dt_parsetimestamp(value, tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    The converted Unix timestamp.

  • Function example
    1. Example 1: Convert the value of time to a timestamp. Time zone: Beijing.
      • Test data
        {
         "time": "2019-06-03 2:41:26",
         "tz": "Asia/Tokyo"
        }
      • Processing rule
        e_set("dt_parsetimestamp", dt_parsetimestamp(v("time"),v("tz")))
      • Processing result
        time: 2019-06-03 2:41:26
        tz: Asia/Tokyo
        dt_parsetimestamp: 1559497286
    2. Example 2: Convert the value of time to a Unix timestamp.
      • Test data
        {
         "time": "2019-06-03 2:41:26"
        }
      • Processing rule
        e_set("dt_parsetimestamp",dt_parsetimestamp(v("time")))
      • Processing result
        time: 2019-06-03 2:41:26
        dt_parsetimestamp: 1559529686
    3. Example 3: Convert the value of time to a Unix timestamp.
      • Test data
        {
         "time": "2019-06-03 2:41:26"
        }
      • Processing rule
        e_set("dt_parsetimestamp",dt_parsetimestamp(v("time")))
      • Processing result
        time: 2019-06-03 02:41:26+8:00
        dt_parsetimestamp: 1559500886

dt_prop

This function extracts specific attributes, such as day and year, from a value or time expression.

  • Function format
    dt_prop(value, props)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    props

    String

    Yes

    Target attributes: day, year, month, hour, second, minute, microsecond, weekday, weekdayname, weekdayshortname, monthname, monthshortname, dayofyear, dayofweek, weekofyear, weekofyear_m, tzname, and weekofmonth.

  • Returned result

    The extracted attribute.

  • Function example
    1. Example 1: Extract the day attribute from time.
      • Test data
        {
         "time": "2018-10-2 09:11:40"
        }
      • Processing rule
        e_set("dt_parsetimestamp",dt_prop(dt_parse(v("time")),"day"))
      • Processing result
        time: 2018-10-2 09:11:40
        dt_parsetimestamp: 2
    2. Example 2: Extract the year attribute from time.
      • Test data
        {
         "time": "2018-10-2 09:11:40"
        }
      • Processing rule
        e_set("dt_parsetimestamp",dt_prop(dt_parse(v("time")),"year"))
      • Processing result
        time: 2018-10-2 09:11:40
        dt_parsetimestamp: 2018
    3. Example 3: Extract the weekdayname attribute from time.
      • Test data
        {
         "time": "2018-10-2 09:11:40"
        }
      • Processing rule
        e_set("dt_prop",dt_prop(dt_parse(v("time")),"weekdayname"))
      • Processing result
        time: 2018-10-2 09:11:40
        dt_prop: Tuesday
    4. Example 4: Extract the weekofyear attribute from time.
      • Test data
        {
         "time": "2018-10-2 09:11:40"
        }
      • Processing rule
        e_set("dt_prop",dt_prop(dt_parse(v("time")),"weekofyear"))
      • Processing result
        time: 2018-10-2 09:11:40
        dt_prop: 39

dt_now

This function obtains the current datetime object.

  • Function format

    dt_now(tz=None)

  • Description

    Parameter

    Type

    Mandatory

    Description

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    The datetime object of the specified time zone.

  • Function example

    Obtains the current datetime object. Time zone: Shanghai.

    • Test data
      {
        "tz": "Asia/Shanghai"
      }
    • Processing rule
      e_set("dt_now",dt_now(tz=v("tz")))
    • Processing result
      tz: Asia/Shanghai
      dt_now: 2022-06-30 11:21:25.111836+08:00

dt_today

This function obtains the current date, excluding the time.

  • Function format
    dt_today(tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    The date object of the specified time zone.

  • Function example

    Obtain the current date, excluding the time.

    • Test data

      None

    • Processing rule
      e_set("dt_today", dt_today())
    • Processing result
      dt_today: 2022-06-30 00:00:00

dt_utcnow

This function obtains the current UTC time.

  • Function format
    dt_utcnow()
  • Description

    None

  • Returned result

    The current UTC time

  • Function example

    Obtain the current UTC time

    • Test data

      None

    • Processing rule
      e_set("dt_utcnow",dt_utcnow())
    • Processing result
      dt_utcnow:2022-06-30 03:33:56.614005

dt_fromtimestamp

This function converts a Unix timestamp to a datetime object.

  • Function format
    dt_fromtimestamp(value, tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String

    Yes

    Value or time expression.

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    The converted datetime object

  • Function example
    1. Example 1: Convert the value of time to a datetime object.
      • Test data
        {
          "time": "1559500886"
        }
      • Processing rule
        e_set("dt_fromtimestamp",dt_fromtimestamp(v("time")))
      • Processing result
        time: 1559500886
        dt_fromtimestamp: 2019-06-02 18:41:26
    2. Example 2: Convert the value of time to a datetime object. Time zone: Shanghai.
      • Test data
        {
         "time": "1559500886"
         "tz": "Asia/Shanghai"
        }

        tz: Asia/Shanghai

      • Processing rule
        e_set("dt_fromtimestamp",dt_fromtimestamp(v("time"),tz=v("tz")))
      • Processing result
        time: 1559500886
        tz: Asia/Shanghai 
        dt_fromtimestamp: 2019-06-03 02:41:26

dt_utcfromtimestamp

This function converts a Unix timestamp to a datetime object of the current time zone.

  • Function format
    dt_utcfromtimestamp(value)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String

    Yes

    Value or time expression.

  • Returned result

    The converted datetime object.

  • Function example
    • Test data
      {
        "time": "1559500886"
      }
    • Processing rule
      e_set("dt_utcfromtimestamp",dt_utcfromtimestamp(v("time")))
    • Processing result
      time: 1559500886
      dt_utcfromtimestamp: 2019-06-02 18:41:26

dt_strptime

This function parses a time string into a datetime object.

  • Function format
    dt_strptime(value, "format_string")
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String

    Yes

    Value or time expression.

    fmt

    String

    No

    Format string.

  • Returned result

    Parsed datetime object

  • Function example
    • Test data
      {
       "time": "2019/06/03 02-41-26",
       "fmt": "%Y/%m/%d %H-%M-%S"
      }
    • Processing rule
      e_set("dt_strptime",dt_strptime(v("time"),v("fmt")))
    • Processing result
      time: 2019/06/03 02-41-26
      fmt: %Y/%m/%d %H-%M-%S 
      dt_strptime: 2019-06-03 02:41:26

dt_currentstamp

This function obtains the current Unix timestamp.

  • Function format
    dt_currentstamp(value, normalize='floor')
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String

    Yes

    Value or time expression.

    normalize

    String

    No

    Calculation result formats:

    • floor (default value): rounding down
    • int: truncating
    • round: rounding off
    • ceil: rounding up
  • Returned result

    The current Unix timestamp.

  • Function example
    • Test data

      None

    • Processing rule
      e_set("dt_currentstamp",dt_currentstamp())
    • Processing result
      dt_currentstamp: 1656560437

dt_totimestamp

This function converts a datetime object to a Unix timestamp.

  • Function format
    dt_totimestamp(timeexpression)
  • Description

    Parameter

    Type

    Mandatory

    Description

    timeexpression

    Datetime object

    Yes

    Datetime object to be converted.

  • Returned result

    The converted Unix timestamp.

  • Function example
    • Test data
      {
       "time": "2019-06-03 2:41:26"
      }
    • Processing rule
      e_set("dt_totimestamp",dt_totimestamp(dt_parse(v("time"))))
    • Processing result
      time: 2019-06-03 2:41:26
      dt_totimestamp: 1559529686

dt_strftime

This function converts a datetime object to a string in a specific format.

  • Function format
    dt_strftime(timeexpression, "format_string")
  • Description

    Parameter

    Type

    Mandatory

    Description

    timeexpression

    Datetime object

    Yes

    Datetime object to be converted.

    format_string

    String

    Yes

    Format string.

  • Returned result

    Formatted string.

  • Function example

    Convert the value of time based on the fmt format.

    • Test data
      {
       "time": "2019-06-03 2:41:26",
       "fmt": "%Y/%m/%d %H-%M-%S"
      }
    • Processing rule
      e_set("dt_strftime",dt_strftime(dt_parse(v("time")),v("fmt")))
    • Processing result
      time: 2019-06-03 2:41:26
      fmt: %Y/%m/%d %H-%M-%S 
      dt_strftime: 2019/06/03 02-41-26

dt_strftimestamp

This function converts a Unix timestamp to a string in a specific format.

  • Function format
    dt_strftimestamp(value, fmt="format_string", tz=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String

    Yes

    Unix timestamp to be converted.

    fmt

    String

    Yes

    Format string.

    tz

    String

    No

    Time zone (default value: None).

  • Returned result

    Formatted string.

  • Function example
    1. Example 1
      • Test data
        {
         "time": "1559500886",
         "fmt": "%Y/%m/%d %H-%M-%S"
        }
      • Processing rule
        e_set("dt_strftimestamp",dt_strftimestamp(v("time"),v("fmt")))
      • Processing result
        time: 1559500886
        fmt: %Y/%m/%d %H-%M-%S 
        dt_strftimestamp: 2019/06/02 18-41-26
    2. Example 2
      • Test data
        {
         "time": "1559500886",
         "fmt": "%Y/%m/%d %H-%M-%S",
         "tz": "Asia/shanghai"
        }
      • Processing rule
        e_set("dt_strftimestamp",dt_strftimestamp(v("time"),v("fmt"),v("tz")))
      • Processing result
        dt_strftimestamp:2019/06/03 03-41-26
        fmt:%Y/%m/%d %H-%M-%S 
        time:1559500886
        tz:Asia/shanghai

dt_truncate

Truncates a value or time expression value to a specific granularity.

  • Function format
    dt_truncate(value, unit='day')
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    unit

    String

    Yes

    Time attribute granularities: second, minute, <num>_minute (for example, 5_minute, 19_minute, and 2_minute), hour, day (default value), week, month, quarter, half_year, and year.

  • Returned result

    The truncated time value.

  • Function example
    1. Example 1
      • Test data
        {
         "time": "2019-06-03 2:41:26",
         "unit": "year"
        }
      • Processing rule
        e_set("dt_truncate",dt_truncate(v("time"),v("unit")))
      • Processing result
        time: 2019-06-03 2:41:26
        unit: year 
        dt_truncate: 2019-01-01 00:00:00
    2. Example 2
      • Test data
        {
         "time": "2019-06-03 2:41:26",
         "unit": "hour"
        }
      • Processing rule
        e_set("dt_truncate",dt_truncate(v("time"),v("unit")))
      • Processing result
        time: 2019-06-03 2:41:26
        unit: hour 
        dt_truncate: 2019-06-03 02:00:00

dt_add

This function changes a value or time expression based on a specific time granularity.

  • Function format
    dt_add(value, dt1=None, dt2=None, year(s)=None, month(s)=None, day(s)=None, hour(s)=None, minute(s)=None, second(s)=None, microsecond(s)=None, week(s)=None, weekday=None)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Date and time expression.

    dt1

    String, Unix timestamp, or datetime object

    No

    Date and time expression (default value: None).

    dt2

    String, Unix timestamp, or datetime object

    No

    Date and time expression (default value: None).

    year/years

    Number

    No

    • year: target year. Example: year=2020. Default value: None.
    • years: number of years to be added. For example, years=1 indicates that one year is added to the original year.

    day/days

    Number

    No

    • day: target day. Example: day=1. Default value: None.
    • days: number of days to be added. For example, days=1 indicates that one day is added to the original day.

    hour/hours

    Number

    No

    • hour: target hour. Example: hour=1. Default value: None.
    • hours: number of hours to be added. For example, hours=1 indicates that 1 hour is added to the original hour.

    minute/minutes

    Number

    No

    • minute: target minute. Example: minute=1. Default value: None.
    • minutes: number of minutes to be added. For example, minutes=1 indicates that 1 minute is added to the original minute.

    second/seconds

    Number

    No

    • second: target second. Example: second=1. Default value: None.
    • seconds: number of seconds to be added. For example, seconds=1 indicates that 1 second is added to the original second.

    microsecond/microseconds

    Number

    No

    • microsecond: target microsecond. Example: microsecond=1. Default value: None.
    • microseconds: number of microseconds to be added. For example, microseconds=1 indicates that one microsecond is added to the original microsecond.

    week/weeks

    Number

    No

    • week: number of weeks to be offset. Example: week=1. Default value: None.
    • weeks: number of weeks to be added. For example, weeks=1 indicates that one week is added to the original week.

    weekday

    Number

    No

    Target weekday. Example: weekday=dt_MO(1). Default value: None.

  • Returned result

    The new time expression.

  • Function example
    1. Example 1
      • Test data
        {
         "dt": "2018-10-10 1:2:3",
         "dt1": "2018-11-3 11:12:13",
         "dt2": "2018-10-1 10:10:10"
        }
      • Processing rule
        e_set("dt_add",dt_add(dt_parse(v("dt")), dt1=dt_parse(v("dt1")), dt2=dt_parse(v("dt2"))))
      • Processing result
        dt:2018-10-10 1:2:3
        dt1:2018-11-3 11:12:13 
        dt2:2018-10-1 10:10:10 
        dt_add:2018-11-12 02:04:06
    2. Example 2
      • Test data
        {
         "dt": "2018-10-11 02:03:04",
         "year": "2019"
        }

        year: 2019

      • Processing rule
        e_set("dt_add", dt_add(dt_parse(v("dt")), year=ct_int(v("year"))))
      • Processing result
        dt:2018-10-11 02:03:04
        dt_add:2019-10-11 02:03:04
        year:2019

dt_MO

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Monday.

  • Function format
    dt_MO(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2019-08-13 02:03:04"
      }
    • Processing rule
      e_set("dt_MO",dt_add(v("time"),weekday=dt_MO(1)))
    • Processing result
      time: 2019-08-13 02:03:04
      dt_MO: 2019-08-19 02:03:04

dt_TU

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Tuesday.

  • Function format
    dt_TU(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_TU",dt_add(v("time"),weekday=dt_TU(1)))
    • Processing result
      time: 2023-06-17 02:03:04
      dt_TU: 2023-06-20 02:03:04

dt_WE

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Wednesday.

  • Function format
    dt_WE(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_WE",dt_add(v("time"),weekday=dt_WE(1)))
    • Processing result
      time: 2023-06-17 02:03:04
      dt_WE: 2023-06-21 02:03:04

dt_TH

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Thursday.

  • Function format
    dt_TH(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_TH",dt_add(v("time"),weekday=dt_TH(1)))
    • Processing result
      time: 2023-06-17 02:03:04
      dt_TH: 2023-06-22 02:03:04

dt_FR

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Friday.

  • Function format
    dt_FR(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_FR",dt_add(v("time"),weekday=dt_FR(1)))
    • Processing result
      time: 2023-06-17 02:03:04
      dt_FR: 2023-06-23 02:03:04

dt_SA

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Saturday.

  • Function format
    dt_SA(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_SA",dt_add(v("time"),weekday=dt_SA(1)))
    • Processing result
      dt_SA: 2023-06-17 02:03:04
      time: 2023-06-17 02:03:04

dt_SU

This function returns a value to be passed to the weekday parameter of the dt_add function, representing an offset to a specific Sunday.

  • Function format
    dt_SU(Integer_or_negative)
  • Description

    Parameter

    Type

    Mandatory

    Description

    Integer_or_negative

    Number

    Yes

    Input offset. If a negative number needs to be input, use op_neg(positive). For example, -1 is represented by op_neg(1).

  • Returned result

    The time after the offset.

  • Function example
    • Test data
      {
       "time": "2023-06-17 02:03:04"
      }
    • Processing rule
      e_set("dt_SU",dt_add(v("time"),weekday=dt_SU(1)))
    • Processing result
      dt_SU: 2023-06-18 02:03:04
      time: 2023-06-17 02:03:04

dt_astimezone

This function converts a value or time expression to a datetime object of a specific time zone.

  • Function format
    dt_astimezone(value, tz, reset=false)
  • Description

    Parameter

    Type

    Mandatory

    Description

    value

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    tz

    String

    No

    Time zone (default value: None).

    reset

    Bool

    No

    Whether to reset the time zone. Default value: false. If the value is set to true, the original time plus the configured time zone is returned.

  • Returned result

    The datetime object of the specified time zone.

  • Function example
    1. Example 1
      • Test data
        {
         "time": "2019-06-03 2:41:26",
         "tz": "UTC"
        }
      • Processing rule
        e_set("dt_astimezone",dt_astimezone(dt_parse(v("time")), v("tz")))
      • Processing result
        time: 2019-06-03 2:41:26
        tz: UTC 
        dt_astimezone: 2019-06-03 02:41:26+00:00
    2. Example 2
      • Test data
        {
         "time": "2019-06-01 10:10:10+10:00",
         "tz": "Asia/shanghai"
        }
      • Processing rule
        e_set("dt_astimezone",dt_astimezone(v("time"), v("tz"),reset=true))
      • Processing result
        time: 2019-06-01 10:10:10+10:00
        tz: Asia/shanghai 
        
        dt_astimezone: 2019-06-01 10:10:10+08:00
    3. Example 3
      • Test data
        {
         "time": "2019-06-01 10:10:10+08:00",
         "tz": "Asia/shanghai"
        }
      • Processing rule
        e_set("dt_astimezone",dt_astimezone(v("time"), v("tz"),reset=false))
        e_set("dt_astimezone_true",dt_astimezone(v("time"), v("tz"),reset=true))
      • Processing result
        dt_astimezone: 2019-06-01 10:10:10+08:00
        dt_astimezone_true: 2019-06-01 10:10:10+08:00
        time:2019-06-01 10:10:10+08:00
        tz:Asia/shanghai

dt_diff

This function obtains the difference between two values or time expressions based on a specific granularity.

  • Function format
    dt_diff(value1, value2, unit='second', normalize='floor')
  • Description

    Parameter

    Type

    Mandatory

    Description

    value1

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    value2

    String, Unix timestamp, or datetime object

    Yes

    Value or time expression.

    unit

    String

    No

    Units of the returned value: second (default value), microsecond, millisecond, minutes, hours, or day.

    normalize

    String

    No

    Calculation result formats:

    • floor (default value): rounding down
    • int: truncating
    • round: rounding to N decimal places
    • ceil: rounding up
  • Returned result

    The difference between two values calculated at a specific granularity

  • Function example
    1. Example 1: Calculate the difference between the values of time1 and time2 by second.
      • Test data
        {
         "time1": "2018-10-1 10:10:10",
         "time2": "2018-10-1 10:10:10"
        }
      • Processing rule
        e_set("diff",dt_diff(v("time1"), v("time2")))
      • Processing result
        time1: 2018-10-1 10:10:10
        time2: 2018-10-1 10:10:10
        diff: 0
    2. Example 2: Calculate the difference between the values of time1 and time2 by second.
      • Test data
        {
         "time1": "2018-10-1 11:10:10",
         "time2": "2018-10-1 10:10:10"
        }
      • Processing rule
        e_set("diff",dt_diff(v("time1"), v("time2")))
      • Processing result
        time1: 2018-10-1 11:10:10
        time2: 2018-10-1 10:10:10
        diff: 3600
    3. Example 3: Calculate the difference between the values of time1 and time2 by microsecond.
      • Test data
        {
         "time1": "2018-10-1 11:10:11",
         "time2": "2018-10-1 10:10:10",
         "unit": "microsecond"
        }
      • Processing rule
        e_set("diff",dt_diff(v("time1"), v("time2"),v("unit")))
      • Processing result
        diff:3601000000
        time1:2018-10-1 11:10:11 
        time2:2018-10-1 10:10:10 
        unit:microsecond
    4. Example 4: Calculate the difference between the values of time1 and time2 by minute and round down the result.
      • Test data
        {
         "time1": "2018-10-1 11:11:59",
          "time2": "2018-10-1 10:10:00",
          "unit": "minute ",
          "normalize": "floor"
        }
      • Processing rule
        e_set("diff", dt_diff(v("time1"), v("time2"), v("unit"), v("normalize")))
      • Processing result
        diff:61
        normalize:floor 
        time1:2018-10-1 11:11:59
        time2:2018-10-1 10:10:00
        unit:minute
    5. Example 5: Calculate the difference between the values of time1 and time2 by second and round down the result.
      • Test data
        {
         "time1": "10:00:00",
         "time2": "11:00:00",
         "unit": "second" ,
         "normalize": "floor"
        }
      • Processing rule
        e_set("diff", dt_diff(v("time1"), v("time2"), v("unit"), v("normalize")))
        Processing result
        diff:-3600
        normalize:floor 
        time1:10:00:00
        time2:11:00:00
        unit:second