Dynamic Time Macros
1. Dynamic Time Macros Overview
Dynamic time macros, that is, through the control of time macros, can set dynamic time to meet users' needs for flexible date setting when viewing and analyzing data, allowing dates to automatically change. They can be used in card titles, filter default values, subscriptions and alerts, dataset creation, and many other places.
For specific usage cases of dynamic time macros, it is recommended to visit Time Macro Usage for more information.
2. Dynamic Time Macro Usage Process
2.1 Using Time Macros in Card Editing
Using dynamic time macros in card titles, the usage method is as follows:
a. Enter the card editing page
b. Add 3 curly braces "{{{}}}" and time-related keywords in the card title
Login to experience case Demo Display Dynamic Date in Card Title.
Time macro keywords mainly have 2 types: date type and offset type.
a. Date type, such as today, yesterday, etc., common usage is as follows:
| Keywords | Usage (case insensitive) |
| today | Today |
| yesterday | Yesterday |
| tomorrow | Tomorrow |
| first day of last month | First day of last month. first day can be replaced with last day, meaning last day; last month can be replaced with this month, next month, meaning this month, next month; month can be replaced with year, quarter. |
| Monday last week | Monday of last week. Monday can be replaced with Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday, representing Tuesday to Sunday respectively; last week can be replaced with this week, next week, meaning this week, next week. |
b. Offset type, such as 2 days ago, 2 weeks ago, etc., common usage is as follows:
| Keywords | Usage (case insensitive) |
| today - 1 days | 1 day ago. Today can be replaced with any time point type keyword; days can be replaced with weeks, months, years, representing 1 week ago, 1 month ago, 1 year ago respectively; + can be replaced with -; numbers can be replaced arbitrarily. |
Combining date type and offset type, you can create custom interval time, such as the past 7 days:
According to the needs of analysis scenarios, the past 7 days can also be defined as starting from today: start as today -6 days, end as today.
Login to experience case Demo Custom Quick Date Interval.
Return Date Format
-
Dynamic time macro expressions generally return date type, such as "2021-12-31", and cannot be precise to hours, minutes, and seconds.
-
If needed, you can also format dynamic time macros, such as returning year, month, just add formatting parameters such as "%", "y", "M", "d" after the dynamic time macro.
Specific usage examples are as follows (taking today as 2021-12-31 and 2022-01-01 as examples):
| Parameter | Meaning | Usage Example | Return Value (taking 2021-12-31 as example) | Return Value (taking 2022-01-01 as example) |
| %y | Year of the current time macro corresponding date (natural year) | today %y | 2021 | 2022 |
| %Y | Year of the current time macro corresponding date (calculated by year week) | today %Y | 2022 | 2022 |
| %M | Month of the current time macro corresponding date | today %M | 12 | 1 |
| %d | Day of the current time macro corresponding date in the current month | today %d | 31 | 1 |
| %D | Day of the current time macro corresponding date in the current year | today %D | 365 | 1 |
| %e | Day of the current time macro corresponding date in the current week (Sunday is the first day) | today %e | 6 | 7 |
| %E | Day of the week of the current time macro corresponding date | today %E | Friday | Saturday |
| %w | Week of the current time macro corresponding date in the current year | today %w | 1 | 1 |
| %W | Week of the current time macro corresponding date in the current month | today %W | 5 | 1 |
| %Q/q | Quarter of the current time macro corresponding date | today %q | 4 | 1 |
The above formatting parameters can also be used in combination. Taking March 15, 2023 as an example, if you input "{{{today %y年M月d日 E}}}", you can get "2023年3月15日 周三". Repeated letters can be used to fine-tune the format (for example, adding zeros before numbers). Taking March 15, 2023 as an example, input "{{{today %y-M}}}" to get "2023-3"; input "{{{today %yyyy-MM}}}" to get "2023-03". The structure supported by time macro combination is time point + one offset, with % placed at the end to specify format. At this time, multi-level nesting is not supported, for example: [Last day of yesterday's month] is not supported.
Notes
-
Lowercase w: %w gets the week number of the current year, counting Sunday as the first day of the week, which is different from the internationally common ISO week calculation method. If you want Monday to be the first day of the week, you can try to correct it through -1 days, such as: {{{yesterday -1 days %w}}}.
-
Uppercase Y: %Y represents Week year, the year of the week where the current date is located, and as long as this week spans years, this week will be counted as the next year, which is also different from the internationally common ISO week year. If you need natural year week, you need to use lowercase y.
-
Based on the above two points, the display of cross-year weeks differs greatly from ISO week, please use with caution. For example, for the 2 days of 2021-12-31 and 2022-01-01, {{{today %YYYY年第w周}}} displays as "2022年第1周", while the week dragged to the dimension bar in the card (i.e., ISO week) is actually "2021年第52周"; for 2022-12-31 (Saturday), {{{today %YYYY年第w周}}} displays as "2022年第53周", while the card actually shows "2022年第52周". Similar situations cannot be corrected through -1 days.
-
The above formatting parameters only support returning Chinese and numerical date formats, and do not support returning English date formats (such as April 1,2023).
Login to experience case Demo Set Date Format for Selection Filter.
2.2 Using Time Macros in Dataset Creation Process
In the process of creating datasets, as shown in the figure, click the time macro parameter button to quickly add time macro parameters in the SQL input box. Pre-configured parameters include: yesterday, today, last Monday, last Sunday, first day of last month, last day of last month.
Login to experience case Demo Incremental Data Update
.jpeg)
2.3 Using Time Macros When Setting "Subscriptions"
When setting "Subscriptions", time macros are also supported. Whether sending to email or pushing to DingTalk/WeChat Work, you can use time macros to let the system automatically update the date every day. As shown in the figure:
2.4 Using Time Macros in Filter Default Value Settings
In the process of dynamic query and analysis, filters need to be set. When creating filters, you can customize time macros. The usage method is as follows:
a. Create a filter;
b. In the type selection, select "Date";
c. In the attribute configuration step, "Default Value" can click to check "Custom Time Macro" and input the time macro.
Login to experience case Demo Set Default Value for Date Filter.
.jpeg)
3. Dynamic Time Macro Usage Cases
For specific usage cases of dynamic time macros, it is recommended to visit Time Macro Usage for more information.