Skip to content

Commit 7ff8205

Browse files
mark-plummermark-plummer
authored
Merge pull request #12273 from mark-plummer/6.3
SCAL-232815 - period to date keywords update
2 parents 32d15fc + 2187c9e commit 7ff8205

File tree

2 files changed

+115
-0
lines changed

2 files changed

+115
-0
lines changed

‎software/modules/ROOT/nav.adoc

+1
Original file line numberDiff line numberDiff line change
@@ -643,6 +643,7 @@
643643
*** xref:keywords-da-DK.adoc[Dansk: Danish keyword reference]
644644
*** xref:keywords-de-DE.adoc[Deutsch: German keyword reference]
645645
*** xref:keywords-en-US.adoc[English (American) keyword reference]
646+
**** xref:keywords-to-date.adoc[Period to-date keywords]
646647
*** xref:keywords-es-ES.adoc[Español (España): Spanish keyword reference]
647648
*** xref:keywords-es-US.adoc[Español (Latinoamérica): Spanish keyword reference]
648649
*** xref:keywords-fr-CA.adoc[Français (Canada): French (Canadian) keyword reference]

‎software/modules/ROOT/pages/keywords-to-date.adoc

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
= Period to date keywords
2+
:last_updated: 11/20/2024
3+
:linkattrs:
4+
:author: Mary
5+
:experimental:
6+
:page-layout: default-cloud
7+
:page-aliases:
8+
:description: Learn how to work with period-to-date keywords.
9+
:jira: SCAL-188158, SCAL-205713 (doc enhancement)
10+
11+
12+
The Period-To-Date keywords are filters that apply a time range from the start of the current period and ends at present (*now*). Assume the following:
13+
14+
* the fiscal year starts on January 1st;
15+
* the start of the week starts on Monday;
16+
* the current date is 24th September 2024.
17+
* the current date is excluded from the to date period.
18+
19+
Examples:
20+
21+
* Week-to-Date returns data from 16th September 2024 to 23rd September 2024;
22+
* Month-to-Date returns data from 1st September 2024 to 23rd September 2024;
23+
* Quarter-to-Date returns data from 1st July 2024 to 23rd September 2024;
24+
* Year-to-Date returns data from 1st January 2024 to 23rd September 2024.
25+
26+
== Date Bucket as a Grouping Columns
27+
In ThoughtSpot when a *Date* or *DateTime* column is included in the search, you can select and change the represented column bucket granularity. This could be Daily, Weekly, Monthly, Quarterly, or Yearly. The combination of the Period-To-Date filter and the Date Bucket effects the resulting query plan and results returned.
28+
29+
=== Date Bucket Window is Smaller than Period-To-Date
30+
The Period-To-Date applies the keyword filter to return the range of data. Month-To-Date will return data from 1st of the month to the present date. The Date Bucket Keyword will then break down the result by the date column.
31+
32+
Examples:
33+
34+
* [sales] [month to date] [daily] will return a row of data for each date in the month. If the date were September 23rd, this would be 23 rows of data.
35+
* [sales] [month to date] [weekly] will return a row of data for each week in the month. If the date were September 23rd, this would result in 4 rows of data, where the final week would be a partial week.
36+
37+
=== Date Bucket Window is Equal-To or Larger than Period-To-Date
38+
Where the *Date Bucket* is equal to or larger than the *Period-to-Date* range then the query is re-written as *FOR EACH* period.
39+
40+
Examples:
41+
42+
* [sales] [month to date] [monthly] will return a row for each month for the period 1st Day of the Month to 23rd Day of the Month.
43+
44+
** January: 1st to 23rd;
45+
February: 1st to 23rd;
46+
March: 1st to 23rd;
47+
April: 1st to 23rd;
48+
49+
* [sales] [month to date] [quarterly] will return a row for each quarter for the period 1st Day of the Quarter to 23rd Day of the Quarter.
50+
51+
** Q1: January: 1st to 23rd;
52+
** Q2: April: 1st to 23rd;
53+
** Q3: July: 1st to 23rd;
54+
55+
* [sales] [month to date] [quarterly] will return a row for each quarter for the period 1st Day of the Quarter to 95th Day of the Quarter.
56+
** 2022: September: 1st to 23rd;
57+
** 2023: September: 1st to 23rd;
58+
** 2024: September: 1st to 23rd;
59+
60+
The reason including the *FOR EACH* keyword is that trend analysis provides a more interesting result than a single summary value. Without the *FOR EACH* query plan [sales] [month to date] [yearly] would only return a single month as the data point. With the *FOR EACH* query plan [sales] [month to date] [yearly] returns a data point for each year.
61+
62+
=== Date Bucket Combinations
63+
The same pattern is applied when multiple date bucket keywords are included in the search. If the date buckets are smaller than the Period-to-Date range then the simple filter is applied. When at least one of the buckets is equal to or larger than the Period-to-Date then the for each query pattern is applied.
64+
65+
Examples:
66+
67+
* [sales] [month to date] [daily][weekly] will return a weekly column, daily column and apply the filter for the 1st September to 23 September.
68+
* [sales] [month to date] [daily][monthly] will return a daily column, monthly column where data will be returned for each month from the 1st Day of the Month to 23rd Day of the Month.
69+
70+
71+
== Date Bucket as a Filter
72+
In the majority of scenarios the date bucket keyword will act as a grouping column. However, it is possible for the date bucket to be applied as a filter. The rule that is applied is dependent upon the column of the filter. January is a monthly filter, therefore the monthly FOR EACH rule is applied.
73+
74+
Examples:
75+
76+
* [sales] [month to date ‘january’] will return a single sales value for each January in the dataset for days 1st to 23rd.
77+
78+
== Detailed Keyword
79+
The detailed keyword is not considered a grouping date bucket. Therefore, the inclusion of this keyword does not modify the query behavior from the simple period filter to the for each query plan.
80+
81+
82+
== Not visualized columns
83+
84+
Chart settings include the ability to set tokens as not visualized. A not visualized token does not change the behavior of the query. The To Date logic is defined based upon the tokens that are defined in the base query.
85+
86+
== Using period to date keywords with a calendar
87+
88+
Period-to-date keywords work slightly differently depending on whether you are using the DEFAULT calendar or a custom calendar and whether you’re using ThoughtSpot’s Falcon in-memory database or an external database, like a cloud data warehouse.
89+
90+
When you use the DEFAULT calendar, data is available up to TODAY, whereas when you use a custom calendar it is not.
91+
92+
93+
94+
|===
95+
| |Default calendar |Custom calendar
96+
97+
|Falcon, date
98+
|Includes current date
99+
|Excludes current date
100+
101+
|Falcon, datetime
102+
|Includes current date
103+
|Excludes current date
104+
105+
|External database, date
106+
|Excludes current date
107+
|Excludes current date
108+
109+
|External database, datetime
110+
|Includes current date
111+
|Excludes current date
112+
|===
113+
114+

0 commit comments

Comments
 (0)