Dynamic Time Macro

Overview

Dynamic time macros allow you to configure dynamic dates through time macro expressions. They meet the need for flexible date settings while viewing and analyzing data, so that dates can change automatically. They can be used in multiple places, including card titles, default filter values, subscriptions and alerts, and dataset creation.

For specific use cases of dynamic time macros, see Time Macro Usage.

Steps

Use Time Macros in Card Editing

To use a dynamic time macro in a card title:

a. Open the card editing page.

b. Add three curly braces {{{}}} and a time keyword in the card title.

Time macro keywords mainly fall into two categories: date types and offset types.

a. Date types, such as today and yesterday. Common usages are as follows:

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 mean the last day; `last month` can be replaced with `this month` or `next month`; and `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`.

b. Offset types, such as 2 days ago or 2 weeks ago. Common usages are as follows:

Keyword	Usage (case-insensitive)
today - 1 days	1 day ago. `today` can be replaced with any date-type keyword; `days` can be replaced with `weeks`, `months`, or `years`; `+` can be replaced with `-`; and the number can be changed as needed.

By combining date types and offset types, you can create custom time ranges, such as the most recent 7 days:{{{yesterday - 6 days}}}

Depending on the analytical scenario, the most recent 7 days can also be defined as starting from today: the start is today - 6 days and the end is today.

Returned Date Formats

Dynamic time macro expressions generally return dates such as 2021-12-31, and do not support hour-minute-second precision.
If needed, you can also format dynamic time macros to return only the year or month by adding formatting parameters such as %, y, M, and d after the expression.

Examples are shown below, assuming today is 2021-12-31 or 2022-01-01:

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

These formatting parameters can also be combined. For example, if the date is March 15, 2023, entering {{{today %y年M月d日 E}}} returns 2023年3月15日 Wednesday. Repeated letters can be used to fine-tune the format, such as padding numbers with leading zeros. For example, {{{today %y-M}}} returns 2023-3, while {{{today %yyyy-MM}}} returns 2023-03. The supported structure for combined time macros is time point + one offset, with % placed at the end to specify the format. Multi-level nesting is not supported.

Notes

Lowercase w: %w counts the week number of the year with Sunday as the first day of the week, which differs from the internationally common ISO week standard. If you need Monday to be treated as the first day of the week, try correcting it with -1 days, for example: {{{yesterday -1 days %w}}}.
Uppercase Y: %Y represents the week year. It returns the year of the week containing the current date, and if the week spans two years, that week is counted as part of the next year. This also differs from the common ISO week year. If you need the calendar year, use lowercase y.
Based on the two points above, the display of cross-year weeks can differ significantly from ISO weeks, so use it with caution.
The formatting parameters above support only Chinese and numeric date formats. They do not support English date formats such as April 1, 2023.

Use Time Macros During Dataset Creation

During dataset creation, as shown below, click the time macro parameter button to quickly add a time macro parameter to the SQL input box. The preset parameters include yesterday, today, last Monday, last Sunday, the first day of last month, and the last day of last month.

Use Time Macros When Configuring Subscriptions

When configuring a Subscription, time macros are also supported. Whether the result is sent by email or pushed to DingTalk or WeCom, time macros can be used to let the system automatically update the date every day, as shown below:

Use Time Macros in Filter Default Values

During dynamic querying and analysis, you may need to configure filters. When creating a filter, you can define a custom time macro as follows:

a. Create a filter.

b. In the type selector, choose Date.

c. In the property configuration section, under Default Value, select Custom Time Macro and enter the macro expression.