Skip to main content

Using Time Macros

Applicable Scenarios

In some scenarios, we need to display the specific date of today or yesterday, which requires setting dynamic time macros. 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 Macros".

Demo Experience

See the demo case "Introduction to Dynamic Time Macros".

Case Download

Download this case from the Guandata App Market to your local environment: "Dynamic Time Macros".

Usage Introduction

  1. Structure: Use three curly braces {{{}}}, with an English keyword representing the date in the middle. For example, {{{today}}}.

  2. There are two main types of dynamic time macros: point-in-time type and offset type, which can be combined.

Point-in-Time Type

KeywordUsage (case-insensitive)
todayToday
yesterdayYesterday
tomorrowTomorrow
first day of last monthFirst day of last month. "first day" can be replaced with "last day" for the last day; "last month" can be replaced with "this month" or "next month" for this month or next month; "month" can be replaced with "year" or "quarter".
Monday last weekMonday of last week. "Monday" can be replaced with Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday; "last week" can be replaced with "this week" or "next week".

Offset Type

KeywordUsage (case-insensitive)
today - 1 days1 day ago. "Today" can be replaced with any point-in-time keyword; "days" can be replaced with weeks, months, years for 1 week ago, 1 month ago, 1 year ago; + can be replaced with -; the number can be any value.

Note: For month date offsets, pay attention to the following case. For example, to get the last day of the month before last, it is not recommended to 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; it is recommended to write first day of last month - 1 days, using the first day of the month minus one day, which will always give the last day of the month before last.

Return Date Format

  1. Dynamic time macro expressions generally return a date type, such as "2021-12-31", and cannot be accurate to the time.

  2. If needed, you can also format the dynamic time macro, such as returning only the year or month, by adding "%", "y", "M", "d", etc. after the macro.

Date formatting parameters are as follows:

ParameterMeaningExample UsageReturn Value (2021-12-31)Return Value (2022-01-01)
%yYear (calendar year)today %y20212022
%YYear (week year)today %Y20222022
%MMonthtoday %M121
%dDay of monthtoday %d311
%DDay of yeartoday %D3651
%eDay of week (Sunday=1)today %e67
%EDay of week (name)today %EFridaySaturday
%wWeek of yeartoday %w11
%WWeek of monthtoday %W51
%Q/qQuartertoday %q41

The above formatting parameters can also be combined. For example, for March 15, 2023, input {{{today %y年M月d日 E}}} to get 2023年3月15日 周三. Repeated letters can be used to fine-tune the format (e.g., add leading zeros). For example, input {{{today %y-M}}} to get 2023-3; input {{{today %yyyy-MM}}} to get 2023-03.

Notes

  1. Lowercase w: %w gives the week number of the year, counting Sunday as the first day of the week, which is different from the ISO week calculation. If you want Monday as the first day, try using -1 days for correction, e.g., {{{yesterday -1 days %w}}}.
  2. Uppercase Y: %Y represents the week year, i.e., the year of the week the current date is in. If the week crosses years, it counts as the next year, which is also different from the ISO week year. If you need the calendar year, use lowercase y.
  3. Based on the above, the display of cross-year weeks differs greatly from the ISO week, so use with caution. For example, for 2021-12-31 and 2022-01-01, {{{today %YYYY年第w周}}} shows "2022年第1周", but the actual ISO week is "2021年第52周"; for 2022-12-31 (Saturday), {{{today %YYYY年第w周}}} shows "2022年第53周", but the actual is "2022年第52周". This cannot be corrected by -1 days.
  4. The above formatting parameters only support returning dates in Chinese and numeric formats, not English date formats (e.g., April 1, 2023).

Usage Examples

1. Time Range

ScenarioTime Macro StartTime Macro End
January this year{{{first day of this year}}} {{{today %yyyy-01-01}}}{{{today %yyyy-01-31}}}
February 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 this year{{{first day of this year}}} {{{today %yyyy-01-01}}}{{{today %yyyy-03-31}}}
Q2 this year{{{first day of this year +3 months}}} {{{today %yyyy-04-01}}}{{{today %yyyy-06-30}}}
Sunday two weeks ago to Saturday 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}}}

2. Time Point

ScenarioTime Macro
Last day of the month before last{{{first day of last month-1 days}}}
Fixed day{{{%2023-02-20}}}
1st of the month of yesterday{{{yesterday %yyyy-MM-01}}}
8th of last month{{{today - 1 months %yyyy-MM-08}}} {{{first day of last month +7 days}}}

3. Text Display (for filter default options, card and subscription titles)

ScenarioTime Macro
2023_Q01{{{today%yyyy_'Q'QQ}}}
Q1 2023{{{today%y年第Q季度}}}, {{{today %y年第qqq}}}
March 15, 2023, Wednesday{{{today %y年M月d日 E}}}
March{{{today %MMM}}}
March (Chinese){{{today %MMMM}}}
First quarter{{{today %qqqq}}}