ansible.builtin.to_datetime filter – Get datetime from string

Note

This filter plugin is part of ansible-core and included in all Ansible installations. In most cases, you can use the short plugin name to_datetime. However, we recommend you use the Fully Qualified Collection Name (FQCN) ansible.builtin.to_datetime for easy linking to the plugin documentation and to avoid conflicting with other collections that may have the same filter plugin name.

Synopsis

  • Using the input string attempt to create a matching Python datetime object.

  • Adding or Subtracting two datetime objects will result in a Python timedelta object.

Input

This describes the input of the filter, the value before | ansible.builtin.to_datetime.

Parameter

Comments

Input

string / required

A string containing date time information.

Keyword parameters

This describes keyword parameters of the filter. These are the values key1=value1, key2=value2 and so on in the following example: input | ansible.builtin.to_datetime(key1=value1, key2=value2, ...)

Parameter

Comments

format

string

strformat formatted string that describes the expected format of the input string.

Notes

Note

  • For a full list of format codes for working with Python date format strings, see the Python documentation.

  • The timedelta object produced by the difference of two datetimes store the days, seconds, and microseconds of the delta. This results in the seconds attribute being the total seconds of the minutes and hours of that delta. See datatime.timedelta for more information about how a timedelta works.

Examples

# Get total amount of seconds between two dates. Default date format is %Y-%m-%d %H:%M:%S but you can pass your own format
secsdiff: '{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime("%Y-%m-%d"))).total_seconds()  }}'

# Get remaining seconds after delta has been calculated. NOTE: This does NOT convert years and days to seconds. For that, use total_seconds()
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2016-08-14 18:00:00" | to_datetime)).seconds  }}
# This expression evaluates to "7212". Delta is 2 hours, 12 seconds

# get amount of days between two dates. This returns only number of days and discards remaining hours, minutes, and seconds
{{ (("2016-08-14 20:00:12" | to_datetime) - ("2015-12-25" | to_datetime('%Y-%m-%d'))).days  }}

# difference between to dotnet (100ns precision) and iso8601 microsecond timestamps
# the date1_short regex replace will work for any timestamp that has a higher than microsecond precision
# by cutting off anything more precise than microseconds
vars:
  date1: '2022-11-15T03:23:13.6869568Z'
  date2: '2021-12-15T16:06:24.400087Z'
  date1_short: '{{ date1|regex_replace("([^.]+)(\.\d{6})(\d*)(.+)", "\1\2\4") }}' # shorten to microseconds
  iso8601format: '%Y-%m-%dT%H:%M:%S.%fZ'
  date_diff_isoed: '{{ (date1_short|to_datetime(iso8601format) - date2|to_datetime(iso8601format)).total_seconds() }}'

Return Value

Key

Description

Return value

any

datetime object from the represented value.

Returned: success

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.