y
y
yq
Search…
Date Time
Various operators for parsing and manipulating dates.

Date time formattings

This uses the golangs built in time library for parsing and formatting date times.
When not specified, the RFC3339 standard is assumed 2006-01-02T15:04:05Z07:00 for parsing.
To specify a custom parsing format, use the with_dtf operator. The first parameter sets the datetime parsing format for the expression in the second parameter. The expression can be any valid yq expression tree.
yq 'with_dtf("myformat"; .a + "3h" | tz("Australia/Melbourne"))'
See https://pkg.go.dev/time#pkg-constants for examples of formatting options.

Timezones

This uses golangs built in LoadLocation function to parse timezones strings. See https://pkg.go.dev/time#LoadLocation for more details.

Durations

Durations are parsed using golangs built in ParseDuration function.
You can durations to time using the + operator.
Note that versions prior to 4.18 require the 'eval/e' command to be specified.
yq e <exp> <file>

Format: from standard RFC3339 format

Providing a single parameter assumes a standard RFC3339 datetime format. If the target format is not a valid yaml datetime format, the result will be a string tagged node.
Given a sample.yml file of:
a: 2001-12-15T02:59:43.1Z
then
yq '.a |= format_datetime("Monday, 02-Jan-06 at 3:04PM")' sample.yml
will output
a: Saturday, 15-Dec-01 at 2:59AM

Format: from custom date time

Use with_dtf to set a custom datetime format for parsing.
Given a sample.yml file of:
a: Saturday, 15-Dec-01 at 2:59AM
then
yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM"; format_datetime("2006-01-02"))' sample.yml
will output
a: 2001-12-15

Format: get the day of the week

Given a sample.yml file of:
a: 2001-12-15T02:59:43.1Z
then
yq '.a | format_datetime("Monday")' sample.yml
will output
Saturday

Now

Given a sample.yml file of:
a: cool
then
yq '.updated = now' sample.yml
will output
a: cool
updated: 2021-05-19T01:02:03Z

Timezone: from standard RFC3339 format

Returns a new datetime in the specified timezone. Specify standard IANA Time Zone format or 'utc', 'local'. When given a single parameter, this assumes the datetime is in RFC3339 format.
Given a sample.yml file of:
a: cool
then
yq '.updated = (now | tz("Australia/Sydney"))' sample.yml
will output
a: cool
updated: 2021-05-19T11:02:03+10:00

Timezone: with custom format

Specify standard IANA Time Zone format or 'utc', 'local'
Given a sample.yml file of:
a: Saturday, 15-Dec-01 at 2:59AM GMT
then
yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; tz("Australia/Sydney"))' sample.yml
will output
a: Saturday, 15-Dec-01 at 1:59PM AEDT

Add and tz custom format

Specify standard IANA Time Zone format or 'utc', 'local'
Given a sample.yml file of:
a: Saturday, 15-Dec-01 at 2:59AM GMT
then
yq '.a |= with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; tz("Australia/Sydney"))' sample.yml
will output
a: Saturday, 15-Dec-01 at 1:59PM AEDT

Date addition

Given a sample.yml file of:
a: 2021-01-01T00:00:00Z
then
yq '.a += "3h10m"' sample.yml
will output
a: 2021-01-01T03:10:00Z

Date subtraction

You can subtract durations from dates. Assumes RFC3339 date time format, see date-time operators for more information.
Given a sample.yml file of:
a: 2021-01-01T03:10:00Z
then
yq '.a -= "3h10m"' sample.yml
will output
a: 2021-01-01T00:00:00Z

Date addition - custom format

Given a sample.yml file of:
a: Saturday, 15-Dec-01 at 2:59AM GMT
then
yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; .a += "3h1m")' sample.yml
will output
a: Saturday, 15-Dec-01 at 6:00AM GMT

Date script with custom format

You can embed full expressions in with_dtf if needed.
Given a sample.yml file of:
a: Saturday, 15-Dec-01 at 2:59AM GMT
then
yq 'with_dtf("Monday, 02-Jan-06 at 3:04PM MST"; .a = (.a + "3h1m" | tz("Australia/Perth")))' sample.yml
will output
a: Saturday, 15-Dec-01 at 2:00PM AWST
Copy link
On this page
Date time formattings
Timezones
Durations
Format: from standard RFC3339 format
Format: from custom date time
Format: get the day of the week
Now
Timezone: from standard RFC3339 format
Timezone: with custom format
Add and tz custom format
Date addition
Date subtraction
Date addition - custom format
Date script with custom format