Using Time Macros

Applicable Scenarios

In some scenarios, you need to display the specific date of today or yesterday. In this case, set a dynamic time macro. Dynamic time macros are used in many places, such as card titles, filter default values, subscriptions, and alerts. For details, see the product documentation Dynamic Time Macro.

Demo

Log in to experience the demo case Dynamic Time Macro Introduction.

Case Download

Download this case from Guandata App Marketplace to your local environment: Dynamic Time Macro.

Usage Introduction

1. Structure: the outer layer consists of three pairs of braces {}, and the middle contains an English keyword that represents a date. Example: {{{today}}}.
2. Dynamic time macros are mainly divided into two types: time point macros and offset macros. They can be used in combination.

Time Point Type

Keyword	Usage (case-insensitive)
today	Today
yesterday	Yesterday
tomorrow	Tomorrow
first day of last month	The first day of last month. first day can be replaced with last day to represent the last day. last month can be replaced with this month or next month to represent this month or next month. month can be replaced with year or quarter.
Monday last week	Monday of last week. Monday can be replaced with Tuesday, Wednesday, Thursday, Friday, Saturday, or Sunday. last week can be replaced with this week or next week to represent this week or next week.

Offset Type

Keyword	Usage (case-insensitive)
today - 1 days	One day ago. today can be replaced with any time point keyword. days can be replaced with weeks, months, or years to represent one week ago, one month ago, or one year ago. + can be replaced with -, and the number can be changed freely.

Note

Pay attention to date offsets by month. For example, if you want to get "the last day of the month before last", do not write last day of last month -1 months, because the number of days in each month is uncertain and the result may differ from expectations. Write first day of last month - 1 days instead. Subtracting one day from the first day of a month always returns the last day of the previous month.

Returned Date Format

1. A dynamic time macro expression generally returns a date type, such as "2021-12-31". It cannot be accurate to hour, minute, and second.

2. If needed, you can format a dynamic time macro, such as returning only the year or month. Add formatting parameters such as "%", "y", "M", and "d" after the dynamic time macro.

The date formatting parameters are as follows:

Parameter	Meaning	Example	Returned Value (using 2021-12-31)	Returned Value (using 2022-01-01)
%y	Year of the date corresponding to the current time macro (calendar year)	today %y	2021	2022
%Y	Year of the date corresponding to the current time macro (week year)	today %Y	2022	2022
%M	Month of the date corresponding to the current time macro	today %M	12	1
%d	Day of the month for the date corresponding to the current time macro	today %d	31	1
%D	Day of the year for the date corresponding to the current time macro	today %D	365	1
%e	Day of the week for the date corresponding to the current time macro (Sunday is the first day)	today %e	6	7
%E	Weekday of the date corresponding to the current time macro	today %E	Friday	Saturday
%w	Week of the year for the date corresponding to the current time macro	today %w	1	1
%W	Week of the month for the date corresponding to the current time macro	today %W	5	1
%Q/q	Quarter of the date corresponding to the current time macro	today %q	4	1

These formatting parameters can also be combined. Using March 15, 2023 as an example, entering {{{today %y 年 M 月 d 日 E}}} returns 2023 年 3 月 15 日 周三. Repeated letters can fine-tune the format, such as padding numbers with zeros. Using March 15, 2023 as an example, entering {{{today %y-M}}} returns 2023-3, and entering {{{today %yyyy-MM}}} returns 2023-03.

Notes

1. Lowercase w: the week number returned by %w counts Sunday as the first day of the week. This is different from the commonly used ISO week calculation method. If you want Monday to be the first day of the week, try correcting it with -1 days, such as {{{yesterday -1 days %w}}}.
2. Uppercase Y: %Y represents the week year, which is the year of the week where the current date falls. If this week crosses the year boundary, the week is counted as part of the next year. This is also different from the commonly used ISO week year. If you need the calendar year week, use lowercase y.
3. Because of the two points above, cross-year week display can differ significantly from ISO week. Use it carefully. For example, on 2021-12-31 and 2022-01-01, {{{today %YYYY 年第 w 周}}} displays "2022 年第 1 周", while the week dragged into the dimension field in the card, namely ISO week, is actually "2021 年第 52 周". On 2022-12-31 (Saturday), {{{today %YYYY 年第 w 周}}} displays "2022 年第 53 周", while the actual week in the card is "2022 年第 52 周". Similar cases cannot be corrected with -1 days.
4. The formatting parameters above only support returning dates in Chinese and numeric formats. They do not support returning dates in English format, such as April 1, 2023.

Use Cases

Time Range

Scenario	Time Macro Start	Time Macro End
January of this year	{{{first day of this year}}} {{{today %yyyy-01-01}}}	{{{today %yyyy-01-31}}}
February of this year	{{{first day of this year +1 months}}} {{{today %yyyy-02-01}}}	{{{last day of last year +2 months}}} {{{last day of this year -10 months}}}
This quarter	{{{first day of this quarter}}}	{{{today}}} {{{yesterday}}}
Last quarter	{{{first day of last quarter}}}	{{{last day of last quarter}}}
Q1 of this year	{{{first day of this year}}} {{{today %yyyy-01-01}}}	{{{today %yyyy-03-31}}}
Q2 of this year	{{{first day of this year +3 months}}} {{{today %yyyy-04-01}}}	{{{today %yyyy-06-30}}}
From Sunday of the week before last to Saturday of last week	{{{Sunday last week - 7 days}}}	{{{Saturday last week}}}
The year before last	{{{first day of last year - 1 years}}}	{{{first day of last year - 1 days}}}
Last 7 days (excluding today)	{{{yesterday -6 days}}} {{{today - 1 weeks}}}	{{{yesterday}}}
Last 7 days (including today)	{{{today -6 days}}}	{{{today}}}
Last 4 weeks (not 28 days)	{{{Monday this week -3 weeks}}}	{{{today}}} {{{yesterday}}}

Time Point

Scenario	Time Macro
The last day of the month before last	{{{first day of last month-1 days}}}
A fixed day	{{{%2023-02-20}}}
The 1st day of yesterday's month	{{{yesterday %yyyy-MM-01}}}
The 8th day of last month	{{{today - 1 months %yyyy-MM-08}}} {{{first day of last month +7 days}}}

Text Display (for Selecting Filter Default Options, Cards, and Subscription Titles)

Scenario	Time Macro
2023_Q01	{{{today%yyyy_'Q'QQ}}}
Q1 of 2023	{{{today%y 年第 Q 季度}}} and {{{today %y 年第 qqq}}}
Wednesday, March 15, 2023	{{{today %y 年 M 月 d 日 E}}}
March as numeric month	{{{today %MMM}}}
March as Chinese month name	{{{today %MMMM}}}
First quarter	{{{today %qqqq}}}