yq
v4.x
v4.x
  • yq
  • How It Works
  • Recipes
  • Upgrading from V3
  • Commands
    • Evaluate
    • Evaluate All
    • Shell Completion
  • Operators
    • Add
    • Alternative (Default value)
    • Anchor and Alias Operators
    • Array to Map
    • Assign (Update)
    • Boolean Operators
    • Collect into Array
    • Column
    • Comment Operators
    • Compare Operators
    • Contains
    • Create, Collect into Object
    • Date Time
    • Delete
    • Divide
    • Document Index
    • Encode / Decode
    • Entries
    • Env Variable Operators
    • Equals
    • Eval
    • File Operators
    • Filter Operator
    • Flatten
    • Group By
    • Has
    • Keys
    • Kind
    • Length
    • Line
    • Load
    • Min
    • Map
    • Max
    • Modulo
    • Multiply (Merge)
    • Omit
    • Parent
    • Path
    • Pick
    • Pipe
    • Pivot
    • Recursive Descent (Glob)
    • Reduce
    • Reverse
    • Select
    • Shuffle
    • Slice Array
    • Sort
    • Sort Keys
    • Split into Documents
    • String Operators
    • Style
    • Subtract
    • Tag
    • To Number
    • Traverse (Read)
    • Union
    • Unique
    • Variable Operators
    • With
  • Usage
    • Output format
    • Working with CSV, TSV
    • Working with JSON
    • Working with Properties
    • Working with XML
    • Working with LUA
    • Working with TOML
    • Working with Shell Output
    • Front Matter
    • Split into multiple files
    • GitHub Action
    • Tips, Tricks, Troubleshooting
  • Github Page
Powered by GitBook
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
  • From Unix
  • To Unix
  • 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

Was this helpful?

  1. Operators

Date Time

PreviousCreate, Collect into ObjectNextDelete

Last updated 2 years ago

Was this helpful?

Various operators for parsing and manipulating dates.

Date time formattings

This uses Golang's 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 the for examples of formatting options.

Timezones

This uses Golang's built in LoadLocation function to parse timezones strings. See the for more details.

Durations

Durations are parsed using Golang's built in function.

You can add durations to time using the + operator.

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-15

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

From Unix

Converts from unix time. Note, you don't have to pipe through the tz operator :)

Running

yq --null-input '1675301929 | from_unix | tz("UTC")'

will output

2023-02-02T01:38:49Z

To Unix

Converts to unix time

Running

yq --null-input 'now | to_unix'

will output

1621386123

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

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

You can subtract durations from dates. Assumes RFC3339 date time format, see for more information.

library docs
library docs
ParseDuration
date-time operators