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.

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

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, days, hours, and so on 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 "12" and not "132". 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.