This topic describes the syntax and parameters of date and time functions. This topic also provides examples on how to use date and time functions.

All values in log events are stored as strings based on the transformation logic of Log Service domain-specific language (DSL). You must convert data types based on your business requirements.

Date and time functions support the following data types. You can use the functions provided in this topic to convert date and time formats.
  • String

    Example: 2022/07/03 02-41-26.

  • UNIX timestamp

    Example: 1559500886.

  • Datetime object

    Example: 2022-07-01 10:10:10+08:00 and 2022-07-01 10:10:10.

Note A UNIX timestamp is a string.

Among the date and time functions that are described in this topic, only the dt_parse, dt_str, and dt_parsetimestamp functions support the preceding data types. For other functions, you must make sure that the parameter values are of the same type.

Functions

Category Function Description
Common datetime conversion dt_parse Converts a value or the value of a time expression to a datetime object.
dt_str Converts a value or the value of a time expression to a string.
dt_parsetimestamp Converts a value or the value of a time expression to a UNIX timestamp.
dt_prop Returns the specified attributes of a value, or returns the specified attributes of the value of a time expression. The attributes include day and year.
Datetime query dt_now Returns the current datetime object.
dt_today Returns only the current date.
dt_utcnow Returns the current datetime object in the current time zone.
dt_fromtimestamp Converts a UNIX timestamp to a datetime object.
dt_utcfromtimestamp Converts a UNIX timestamp to a datetime object in the current time zone.
dt_strptime Parses a time string into a datetime object.
UNIX timestamp generation dt_currentstamp Returns the current UNIX timestamp.
dt_totimestamp Converts a datetime object to a UNIX timestamp.
Datetime string generation dt_strftime Converts a datetime object to a string in a specified format.
dt_strftimestamp Converts a UNIX timestamp to a string in a specified format.
Datetime change dt_truncate Extracts a time value from a value or the value of a time expression based on a specified time granularity.
dt_add Changes a value or the value of a time expression based on a specified time granularity.
dt_MO Offsets a specified time to the date of the previous or following Nth Monday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_TU Offsets a specified time to the date of the previous or following Nth Tuesday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_WE Offsets a specified time to the date of the previous or following Nth Wednesday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_TH Offsets a specified time to the date of the previous or following Nth Thursday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_FR Offsets a specified time to the date of the previous or following Nth Friday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_SA Offsets a specified time to the date of the previous or following Nth Saturday. The offset value N is passed to the weekday parameter of the dt_add function.
dt_SU Offsets a specified time to the date of the previous or following Nth Sunday. The offset value N is passed to the weekday parameter of the dt_add function.
Time zone change dt_astimezone Converts a value or the value of a time expression to a datetime object in a specified time zone.
Difference generation dt_diff Returns the difference between two values or between the values of two time expressions based on a specified time granularity.

dt_parse

The function is used to convert a value or the value of a time expression to a datetime object.

  • Syntax

    dt_parse(value, tz=None)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A datetime object is returned.

  • Examples

    • Example 1: Convert the value of the time field to a datetime object.
      • Raw log:
        time: 1559500886
      • Transformation rule:
        e_set("test_time", dt_parse(v("time")))
      • Result:
        time: 1559500886
test_time: 2019-06-02 18:41:26
    • Example 2: Convert the value of the time field to a datetime object in the time zone of Shanghai.
      • Raw log:
        time: 2019-06-01 10:10:10
tz: Asia/Shanghai
      • Transformation rule:
        e_set("test_time", dt_parse(v("time"),tz=v("tz")))
      • Result:
        time: 2019-06-01 10:10:10
tz: Asia/Shanghai
test_time: 2019-06-01 10:10:10+08:00

dt_str

The function is used to convert a value or the value of a time expression to a string.

  • Syntax

    dt_str(value, fmt="format_string", tz=None)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    fmt String No The format of the string. For more information, see Date and time formatting directives. By default, the parameter is empty and the format of the string remains unchanged.
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A time string is returned.

  • Examples

    • Example 1: Convert the value of the time field to a time string of the specified format in the time zone of Tokyo.
      • Raw log:
        time: 2019-06-03 02:41:26
fmt: %Y/%m/%d %H-%M-%S
tz: Asia/Tokyo
      • Transformation rule:
        e_set("dt_str", dt_str(v("time"),fmt=v("fmt"),tz=v("tz")))
      • 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
    • Example 2: Convert the value of the time field to a time string of the specified format. In this example, the value of the time field is a UNIX timestamp.
      • Raw log:
        time: 1559500886
fmt: %Y/%m/%d %H-%M-%S
      • Transformation rule:
        e_set("dt_str", dt_str(v("time"),fmt=v("fmt")))
      • Result:
        time: 1559500886
fmt: %Y/%m/%d %H-%M-%S
dt_str: 2019/06/02 18-41-26
    • Example 3: Convert the value of the time field to a time string in the default format.
      • Raw log:
        time: 2019-06-03 02:41:26
      • Transformation rule:
        e_set("dt_str", dt_str(v("time")))
      • Result:
        time: 2019-06-03 02:41:26
dt_str: 2019-06-03 02:41:26

dt_parsetimestamp

The function is used to convert a value or the value of a time expression to a UNIX timestamp.

  • Syntax

    dt_parsetimestamp(value, tz=None)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A UNIX timestamp is returned.

  • Examples

    • Example 1: Convert the value of the time field to a UNIX timestamp in the time zone of Tokyo.
      • Raw log:
        time: 2019-06-03 2:41:26
tz: Asia/Tokyo
      • Transformation rule:
        e_set("dt_parsetimestamp", dt_parsetimestamp(v("time"),v("tz")))
      • Result:
        time: 2019-06-03 2:41:26
tz: Asia/Tokyo
dt_parsetimestamp: 1559497286
    • Example 2: Convert the value of the time field to a UNIX timestamp.
      • Raw log:
        time: 2019-06-03 2:41:26
      • Transformation rule:
        e_set("dt_parsetimestamp",dt_parsetimestamp(v("time")))
      • Result:
        time: 2019-06-03 2:41:26
dt_parsetimestamp: 1559529686
    • Example 3: Convert the value of the time field to a UNIX timestamp.
      • Raw log:
        time: 2019-06-03 02:41:26+8:00
      • Transformation rule:
        e_set("dt_parsetimestamp",dt_parsetimestamp(v("time")))
      • Result:
        time: 2019-06-03 02:41:26+8:00
dt_parsetimestamp: 1559500886

dt_prop

The function is used to return the specified attribute of a value or the value of a time expression, such as day and year.

  • Syntax

    dt_prop(value, props)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    props String Yes The attribute that you want to obtain. For example, if you set the attribute parameter to year, only the year is returned. Valid values: day, year, month, hour, second, minute, microsecond, weekday, weekdayname, weekdayshortname, monthname, monthshortname, dayofyear, dayofweek, weekofyear, weekofyear_m, tzname, weekofmonth.

  • Response

    The value of the attribute is returned.

  • Examples

    • Example 1: Extract the value of the day attribute from the time field.
      • Raw log:
        time: 2018-10-2 09:11:40
      • Transformation rule:
        e_set("dt_parsetimestamp",dt_prop(dt_parse(v("time")),"day"))
      • Result:
        time: 2018-10-2 09:11:40
dt_parsetimestamp: 2
    • Example 2: Extract the value of the year attribute from the time field.
      • Raw log:
        time: 2018-10-2 09:11:40
      • Transformation rule:
        e_set("dt_parsetimestamp",dt_prop(dt_parse(v("time")),"year"))
      • Result:
        time: 2018-10-2 09:11:40
dt_parsetimestamp: 2018
    • Example 3: Extract the value of the weekdayname attribute from the time field.
      • Raw log:
        time: 2018-10-2 09:11:40
weekdayname: weekdayname
      • Transformation rule:
        e_set("dt_prop",dt_prop(dt_parse(v("time")),"weekdayname"))
      • Result:
        time: 2018-10-2 09:11:40
dt_prop: Tuesday
    • Example 4: Extract the value of the weekofyear attribute from the time field.
      • Raw log:
        time: 2018-10-2 09:11:40
      • Transformation rule:
        e_set("dt_prop",dt_prop(dt_parse(v("time")),"weekofyear"))
      • Result:
        time: 2018-10-2 09:11:40
dt_prop: 39

dt_now

The function is used to return the current datetime object.

  • Syntax

    dt_now(tz=None)

  • Parameters

    Parameter Type Required Description
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A datetime object in the specified time zone is returned.

  • Examples

    Return the current datetime object in the time zone of Shanghai.
    • Raw log:
      tz: Asia/Shanghai
    • Transformation rule:
      e_set("dt_now",dt_now(tz=v("tz")))
    • Result:
      tz: Asia/Shanghai
dt_now: 2022-06-30 11:21:25.111836+08:00

dt_today

The function is used to return only the current date.

  • Syntax

    dt_today(tz=None)

  • Parameters

    Parameter Type Required Description
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A date object in the specified time zone is returned.

  • Examples

    Return only the current date.
    • Raw log:
      No default value
    • Transformation rule:
      e_set("dt_today", dt_today())
    • Result:
      dt_today: 2022-06-30 00:00:00

dt_utcnow

The function is used to return the current datetime object in the current time zone.

  • Syntax

    dt_utcnow()

  • Parameters

    None.

  • Response

    The current datetime object in the current time zone is returned.

  • Examples

    Return the current datetime object in the current time zone.
    • Raw log:
      None
    • Transformation rule:
      e_set("dt_utcnow",dt_utcnow())
    • Result:
      dt_utcnow:2022-06-30 03:33:56.614005

dt_fromtimestamp

The function is used to convert a UNIX timestamp to a datetime object.

  • Syntax

    dt_fromtimestamp(value, tz=None)

  • Parameters

    Parameter Type Required Description
    value String Yes The value or time expression.
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A datetime object is returned.

  • Examples

    • Example 1: Convert the value of the time field to a datetime object.
      • Raw log:
        time: 1559500886
      • Transformation rule:
        e_set("dt_fromtimestamp",dt_fromtimestamp(v("time")))
      • Result:
        time: 1559500886
dt_fromtimestamp: 2019-06-02 18:41:26
    • Example 2: Convert the value of the time field to a datetime object in the time zone of Shanghai.
      • Raw log:
        time: 1559500886
tz: Asia/Shanghai
      • Transformation rule:
        e_set("dt_fromtimestamp",dt_fromtimestamp(v("time"),tz=v("tz")))
      • Result:
        time: 1559500886
tz: Asia/Shanghai
dt_fromtimestamp: 2019-06-03 02:41:26+08:00

dt_utcfromtimestamp

The function is used to convert a UNIX timestamp to a datetime object in the current time zone.

  • Syntax

    dt_utcfromtimestamp(value)

  • Parameters

    Parameter Type Required Description
    value String Yes The value or time expression.

  • Response

    A datetime object is returned.

  • Examples

    • Raw log:
      time: 1559500886
    • Transformation rule:
      e_set("dt_utcfromtimestamp",dt_utcfromtimestamp(v("time")))
    • Result:
      time: 1559500886
dt_utcfromtimestamp: 2019-06-02 18:41:26

dt_strptime

The function is used to parse a time string into a datetime object.

  • Syntax

    dt_strptime(value, "format_string")

  • Parameters

    Parameter Type Required Description
    value String Yes The value or time expression.
    fmt String No The format of the string. For more information, see Date and time formatting directives.

  • Response

    A datetime object is returned.

  • Examples

    • Raw log:
      time: 2019/06/03 02-41-26
fmt: %Y/%m/%d %H-%M-%S
    • Transformation rule:
      e_set("dt_strptime",dt_strptime(v("time"),v("fmt")))
    • 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

The function is used to return the current UNIX timestamp.

  • Syntax

    dt_currentstamp(value, normalize='floor')

  • Parameters

    Parameter Type Required Description
    value String Yes The value or time expression.
    normalize String No The numeric format in which you want the function to return the result. Valid values:
    • floor: rounds a number down to the nearest integer. This is the default value.
    • int: returns the integer part of a number.
    • round: rounds a number to the nearest integer.
    • ceil: rounds a number up to the nearest integer.

  • Response

    The current UNIX timestamp is returned.

  • Examples

    • Raw log:
      No default value
    • Transformation rule:
      e_set("dt_currentstamp",dt_currentstamp())
    • Result:
      dt_currentstamp: 1656560437

dt_totimestamp

The function is used to convert a datetime object to a UNIX timestamp.

  • Syntax

    dt_totimestamp(timeexpression)

  • Parameters

    Parameter Type Required Description
    timeexpression Datetime object Yes The datetime object that you want to convert.

  • Response

    A UNIX timestamp is returned.

  • Examples

    • Raw log:
      time: 2019-06-03 2:41:26
    • Transformation rule:
      e_set("dt_totimestamp",dt_totimestamp(dt_parse(v("time"))))
    • Result:
      time: 2019-06-03 2:41:26
dt_totimestamp: 1559529686

dt_strftime

The function is used to return a datetime object to a string in a specified format.

  • Syntax

    dt_strftime(timeexpression, "format_string")

  • Parameters

    Parameter Type Required Description
    timeexpression Datetime object Yes The datetime object that you want to convert.
    format_string String Yes The format of the string. For more information, see Date and time formatting directives.

  • Response

    A formatted string is returned.

  • Examples

    Convert the value of the time field to a string of the specified format.
    • Raw log:
      time: 2019-06-03 2:41:26
fmt: %Y/%m/%d %H-%M-%S
    • Transformation rule:
      e_set("dt_strftime",dt_strftime(dt_parse(v("time")),v("fmt")))
    • 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

The function is used to convert a UNIX timestamp to a string in a specified format.

  • Syntax

    dt_strftimestamp(value, fmt="format_string", tz=None)

  • Parameters

    Parameter Type Required Description
    value String Yes The UNIX timestamp that you want to convert.
    fmt String Yes The format of the string. For more information, see Date and time formatting directives.
    tz String No The time zone. Default value: None. For more information, see Time zones.

  • Response

    A formatted string is returned.

  • Examples

    • Example 1
      • Raw log:
        time: 1559500886
fmt: %Y/%m/%d %H-%M-%S
      • Transformation rule:
        e_set("dt_strftimestamp",dt_strftimestamp(v("time"),v("fmt")))
      • Result:
        time: 1559500886
fmt: %Y/%m/%d %H-%M-%S
dt_strftimestamp: 2019/06/02 18-41-26
    • Example 2
      • Raw log:
        time: 1559500886
fmt: %Y/%m/%d %H-%M-%S
tz: Asia/Tokyo
      • Transformation rule:
        e_set("dt_strftimestamp",dt_strftimestamp(v("time"),v("fmt"),v("tz")))
      • Result:
        dt_strftimestamp:2019/06/03 03-41-26
fmt:%Y/%m/%d %H-%M-%S
time:1559500886
tz:Asia/Tokyo

dt_truncate

The function is used to extract a time value from a value or the value of a time expression based on a specified time granularity.

  • Syntax

    dt_truncate(value, unit='day')

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    unit String Yes The time granularity that you want to obtain. Default value: day. Valid values: second, minute, <num>_minute (for example, 5_minute, 19_minute, and 2_minute), hour, day, week, month, quarter, half_year, and year.

  • Response

    The extracted time value is returned.

  • Examples

    • Example 1
      • Raw log:
        time: 2019-06-03 2:41:26
unit: year
      • Transformation rule:
        e_set("dt_truncate",dt_truncate(v("time"),v("unit")))
      • Result:
        time: 2019-06-03 2:41:26
unit: year
dt_truncate: 2019-01-01 00:00:00
    • Example 2
      • Raw log:
        time: 2019-06-03 2:41:26
unit: hour
      • Transformation rule:
        e_set("dt_truncate",dt_truncate(v("time"),v("unit")))
      • Result:
        time: 2019-06-03 2:41:26
unit: hour
dt_truncate: 2019-06-03 02:00:00

dt_add

The function is used to change a value or the value of a time expression based on a specified time granularity.

  • Syntax

    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)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The datetime expression.
    dt1 String, UNIX timestamp, or datetime object No The datetime expression. Default value: None.
    dt2 String, UNIX timestamp, or datetime object No The datetime expression. Default value: None.
    year/years Number No
    • year: the year that is used to replace the year in the specified time. For example, you can set year=2020. Default value: None.
    • years: the number of years by which you want to offset the specified time. For example, if you set years=1, the function increases the year by one year.
    day/days Number No
    • day: the day that is used to replace the day in the specified time. For example, you can set day=1. Default value: None.
    • days: the number of days by which you want to offset the specified time. For example, if you set days=1, the function increases the day by one day.
    hour/hours Number No
    • hour: the hour that is used to replace the hour in the specified time. For example, you can set hour=1. Default value: None.
    • hours: the number of hours by which you want to offset the specified time. For example, if you set hours=1, the function increases the hour by one hour.
    minute/minutes Number No
    • minute: the minute that is used to replace the minute in the specified time. For example, you can set minute=1. Default value: None.
    • minutes: the number of minutes by which you want to offset the specified time. For example, if you set minutes=1, the function increases the minute by one minute.
    second/seconds Number No
    • second: the second that is used to replace the second in the specified time. For example, you can set second=1. Default value: None.
    • seconds: the number of seconds by which you want to offset the specified time. For example, if you set seconds=1, the function increases the second by one second.
    microsecond/microseconds Number No
    • microsecond: the microsecond that is used to replace the microsecond in the specified time. For example, you can set microsecond=1. Default value: None.
    • microseconds: the number of microseconds by which you want to offset the specified time. For example, if you set microseconds=1, the function increases the microsecond by one microsecond.
    week/weeks Number No
    • week: the week that is used to replace the week in the specified time. For example, you can set week=1. Default value: None.
    • weeks: the number of weeks by which you want to offset the specified time. For example, if you set weeks=1, the function increases the week by one week.
    weekday Number No The weekday that is used to replace the weekday in the specified time. For example, you can set weekday=dt_MO(1). Default value: None.

  • Response

    The new value of the time expression is returned.

  • Examples

    • Example 1
      • Raw log:
        dt: 2018-10-10 1:2:3
dt1: 2018-11-3 11:12:13
dt2: 2018-10-1 10:10:10
      • Transformation rule:
        e_set("dt_add",dt_add(dt_parse(v("dt")), dt1=dt_parse(v("dt1")), dt2=dt_parse(v("dt2"))))
      • 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
    • Example 2
      • Raw log:
        dt: 2018-10-11 02:03:04
year: 2019
      • Transformation rule:
        e_set("dt_add", dt_add(dt_parse(v("dt")), year=ct_int(v("year"))))
      • Result:
        dt:2018-10-11 02:03:04
dt_add:2019-10-11 02:03:04
year:2019

dt_MO

The function is used to offset a specified time to the same time of the previous or next Nth Monday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_MO(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    • Raw log:
      time: 2019-08-13 02:03:04
    • Transformation rule:
      e_set("dt_MO",dt_add(v("time"),weekday=dt_MO(1)))
    • Result:
      time: 2019-08-13 02:03:04
dt_MO: 2019-08-19 02:03:04

dt_TU

The function is used to offset a specified time to the date of the previous or following Nth Tuesday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_TU(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_WE

The function is used to offset a specified time to the date of the previous or following Nth Wednesday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_WE(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_TH

The function is used to offset a specified time to the date of the previous or following Nth Thursday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_TH(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_FR

The function is used to offset a specified time to the date of the previous or following Nth Friday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_FR(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_SA

The function is used to offset a specified time to the date of the previous or following Nth Saturday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_SA(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_SU

The function is used to offset a specified time to the date of the previous or following Nth Sunday. The offset value N is passed to the weekday parameter of the dt_add function.

  • Syntax

    dt_SU(Integer_or_negative)

  • Parameters

    Parameter Type Required Description
    Integer_or_negative Number Yes The offset value. If you want to pass a negative integer, use op_neg(Positive integer). For example, use op_neg(1) to indicate -1.

  • Response

    The time that is offset is returned.

  • Examples

    For more examples, see dt_MO.

dt_astimezone

The function is used to convert a value or the value of a time expression to a datetime object in a specified time zone.

  • Syntax

    dt_astimezone(value, tz, reset=False)

  • Parameters

    Parameter Type Required Description
    value String, UNIX timestamp, or datetime object Yes The value or time expression.
    tz String No The time zone. Default value: None. For more information, see Time zones.
    reset Bool No Specifies whether to change the time zone. The default value False specifies that the datetime object is returned in the current time zone. The value True specifies that the datetime object is returned in the specified time zone.

  • Response

    A datetime object in the specified time zone is returned.

  • Examples

    • Example 1
      • Raw log:
        time: 2019-06-03 2:41:26
tz: UTC
      • Transformation rule:
        e_set("dt_astimezone",dt_astimezone(dt_parse(v("time")), v("tz")))
      • Result:
        time: 2019-06-03 2:41:26
tz: UTC
dt_astimezone: 2019-06-03 02:41:26+00:00
    • Example 2
      • Raw log:
        time: 2019-06-01 10:10:10+10:00
tz: Asia/Tokyo
      • Transformation rule:
        e_set("dt_astimezone",dt_astimezone(v("time"), v("tz"),reset=True))
      • Result:
        time: 2019-06-01 10:10:10+10:00
tz: Asia/Tokyo
dt_astimezone: 2019-06-01 10:10:10+09:00
    • Example 3
      • Raw log:
        time: 2019-06-01 10:10:10+08:00
tz: Asia/Tokyo
      • Transformation 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))
      • Result:
        dt_astimezone:2019-06-01 11:10:10+09:00
dt_astimezone_true:2019-06-01 10:10:10+09:00
time:2019-06-01 10:10:10+08:00
tz:Asia/Tokyo

dt_diff

The function is used to return the difference between two values or between the values of two time expressions based on a specified time granularity.

  • Syntax

    dt_diff(value1, value2, unit='second', normalize='floor')

  • Parameters

    Parameter Type Required Description
    value1 String, UNIX timestamp, or datetime object Yes The value or time expression.
    value2 String, UNIX timestamp, or datetime object Yes The value or time expression.
    unit String No The time granularity in which you want the function to return the difference. Default value: second. Valid values: second, microsecond, millisecond, minutes, hours, and day.
    normalize String No The numeric format in which you want the function to return the result. Valid values:
    • floor: rounds a number down to the nearest integer. Default value: floor.
    • int: returns the integer part of a number.
    • round: retains N decimal places.
    • ceil: rounds a number up to the nearest integer.

  • Response

    The difference between two values is returned based on the specified time granularity.

  • Examples

    • Example 1: Calculate the difference between the value of the time1 field and the value of the time2 field. Unit: seconds.
      • Raw log:
        time1: 2018-10-1 10:10:10
time2: 2018-10-1 10:10:10
      • Transformation rule:
        e_set("diff",dt_diff(v("time1"), v("time2")))
      • Result:
        time1: 2018-10-1 10:10:10
time2: 2018-10-1 10:10:10
diff: 0
    • Example 2: Calculate the difference between the value of the time1 field and the value of the time2 field. Unit: seconds.
      • Raw log:
        time1: 2018-10-1 11:10:10
time2: 2018-10-1 10:10:10
      • Transformation rule:
        e_set("diff",dt_diff(v("time1"), v("time2")))
      • Result:
        time1: 2018-10-1 11:10:10
time2: 2018-10-1 10:10:10
diff: 3600
    • Example 3: Calculate the difference between the value of the time1 field and the value of the time2 field. Unit: microseconds.
      • Raw log:
        time1: 2018-10-1 11:10:11
time2: 2018-10-1 10:10:10
unit: microsecond
      • Transformation rule:
        e_set("diff",dt_diff(v("time1"), v("time2"),v("unit")))
      • Result:
        diff:3601000000
time1:2018-10-1 11:10:11
time2:2018-10-1 10:10:10
unit:microsecond
    • Example 4: Calculate the difference between the value of the time1 field and the value of the time2 field and round the return value down to the nearest integer. Unit: minutes.
      • Raw log:
        time1: 2018-10-1 11:11:59
time2: 2018-10-1 10:10:00
unit: minute
normalize: floor
      • Transformation rule:
        e_set("diff", dt_diff(v("time1"), v("time2"), v("unit"), v("normalize")))
      • Result:
        diff:61
normalize:floor
time1:2018-10-1 11:11:59
time2:2018-10-1 10:10:00
unit:minute
    • Example 5: Calculate the difference between the value of the time1 field and the value of the time2 field and round the return value down to the nearest integer. Unit: seconds.
      • Raw log:
        time1: 10:00:00
time2: 11:00:00
unit: second
normalize: floor
      • Transformation rule:
        e_set("diff", dt_diff(v("time1"), v("time2"), v("unit"), v("normalize")))
      • Result:
        diff:-3600
normalize:floor
time1:10:00:00
time2:11:00:00
unit:second