From 71862e2e5f5fe7c1555415f3c34cfd6391a7e7a3 Mon Sep 17 00:00:00 2001
From: Jeff Bruemmer <jeff.bruemmer@gmail.com>
Date: Tue, 6 Dec 2022 10:21:24 -0500
Subject: [PATCH] docs - add limitations, formatting (#26963)
---
.../expressions/converttimezone.md | 71 ++++++++++++-------
.../query-builder/expressions/datetimeadd.md | 31 ++++----
.../query-builder/expressions/datetimediff.md | 62 ++++++++++------
3 files changed, 101 insertions(+), 63 deletions(-)
diff --git a/docs/questions/query-builder/expressions/converttimezone.md b/docs/questions/query-builder/expressions/converttimezone.md
index d56a10bc1c4..cbfd67d6e2b 100644
--- a/docs/questions/query-builder/expressions/converttimezone.md
+++ b/docs/questions/query-builder/expressions/converttimezone.md
@@ -7,7 +7,7 @@ title: ConvertTimezone
`convertTimezone` shifts a timestamp into a specified time zone by adding or subtracting the right interval from the timestamp.
| Syntax | Example |
-|-----------------------------------------------------------------------|-----------------------------------------------------------------------------------|
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `convertTimezone(column, target, source)` | `convertTimezone("2022-12-28T12:00:00", "Canada/Pacific", "Canada/Eastern")` |
| Shifts a timestamp from the source time zone to the target time zone. | Returns the value `2022-12-28T09:00:00`, displayed as `December 28, 2022 9:00 AM` |
@@ -18,17 +18,20 @@ For example, if you're tracking user logins over time, you probably won't run yo
## Parameters
`column` can be any of:
+
- The name of a timestamp column,
- a custom expression that returns a [timestamp](#accepted-data-types), or
- a string in the format `"YYYY-MM-DD` or `"YYYY-MM-DDTHH:MM:SS"`.
`target`:
+
- The name of the time zone you want to assign to your column.
`source`:
+
- The name of your column's current time zone.
- Required for columns or expressions with the data type `timestamp without time zone`.
-- Optional for columns or expressions with the data type `timestamp with time zone`.
+- Optional for columns or expressions with the data type `timestamp with time zone`.
- For more info, see [Accepted data types](#accepted-data-types).
We support [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) time zone names (such as "Canada/Eastern" instead of "EST").
@@ -37,11 +40,11 @@ We support [tz database](https://en.wikipedia.org/wiki/List_of_tz_database_time_
Let's say that you have some time series data that's stored in one or more time zones (**Source Time**). You want to create custom reporting dates for a team that lives in EST.
-| Source Time | Team Report Time (EST) |
-|------------------------------------|------------------------------|
-| December 28, 2022, 10:00:00 | December 28, 2022, 07:00:00 |
-| December 28, 2022, 21:00:00 | December 28, 2022, 19:00:00 |
-| December 27, 2022, 08:00:00 | December 27, 2022, 05:00:00 |
+| Source Time | Team Report Time (EST) |
+| --------------------------- | --------------------------- |
+| December 28, 2022, 10:00:00 | December 28, 2022, 07:00:00 |
+| December 28, 2022, 21:00:00 | December 28, 2022, 19:00:00 |
+| December 27, 2022, 08:00:00 | December 27, 2022, 05:00:00 |
If **Source Time** is stored as a `timestamp with time zone` or a `timestamp with offset`, you only need to provide the `target` time zone:
@@ -58,6 +61,7 @@ convertTimezone([Source Time], 'EST', 'UTC')
It's usually a good idea to label `convertTimezone` columns with the name of the target time zone (or add the target time zone to the metadata of a model). We promise this will make your life easier when someone inevitably asks why the numbers don't match.
If you're not getting the results that you expect:
+
- Check if you have the right [source time zone](#choosing-a-source-time-zone).
- Ask your database admin about `timestamp with time zone` vs. `timestamp without time zone` (for more info, see [Accepted data types](#accepted-data-types)).
@@ -65,12 +69,12 @@ If you're not getting the results that you expect:
When you're doing time zone conversions, make sure you know the source time zone that you're working with. Different columns (and even different rows) in the same table, question, or model can be in different "source" time zones.
-| Possible source time zone | Description | Example |
-|-------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
-| Client time zone | Time zone where an event happened. | A web analytics service might capture data in the local time zone of each person who visited your website. |
-| Database time zone | Time zone metadata that's been added to timestamps in your database. | It's a common database practice to store all timestamps in UTC. |
-| No time zone | Missing time zone metadata | Databases don't _require_ you to store timestamps with time zone metadata. |
-| Metabase report time zone | Time zone that Metabase uses to _display_ timestamps. | Metabase can display dates and times in PST, even if the dates and times are stored as UTC in your database. |
+| Possible source time zone | Description | Example |
+| ------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| Client time zone | Time zone where an event happened. | A web analytics service might capture data in the local time zone of each person who visited your website. |
+| Database time zone | Time zone metadata that's been added to timestamps in your database. | It's a common database practice to store all timestamps in UTC. |
+| No time zone | Missing time zone metadata | Databases don't _require_ you to store timestamps with time zone metadata. |
+| Metabase report time zone | Time zone that Metabase uses to _display_ timestamps. | Metabase can display dates and times in PST, even if the dates and times are stored as UTC in your database. |
For example, say you have a table with one row for each person who visited your website. It's hard to tell, just from looking at `December 28, 2022, 12:00 PM`, whether the "raw" timestamp is:
@@ -82,13 +86,13 @@ For more gory details, see [Limitations](#limitations).
## Accepted data types
-| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `convertTimezone` |
-| ----------------------- | -------------------- |
-| String | ⌠|
-| Number | ⌠|
-| Timestamp | ✅ |
-| Boolean | ⌠|
-| JSON | ⌠|
+| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `convertTimezone` |
+| ------------------------------------------------------------------------------------------------ | ---------------------------- |
+| String | ⌠|
+| Number | ⌠|
+| Timestamp | ✅ |
+| Boolean | ⌠|
+| JSON | ⌠|
We use "timestamp" and "datetime" to talk about any temporal data type that's supported by Metabase.
@@ -97,7 +101,7 @@ If your timestamps are stored as strings or numbers in your database, an admin c
To use `convertTimezone` without running into errors or pesky undetectable mistakes, you should know that there are a few varieties of `timestamp` data types:
| Data type | Description | Example |
-|-------------------------------|-------------------------------------------|------------------------------------------------------|
+| ----------------------------- | ----------------------------------------- | ---------------------------------------------------- |
| `timestamp with time zone` | Knows about location. | `2022-12-28T12:00:00 AT TIME ZONE 'America/Toronto'` |
| `timestamp with offset` | Knows about the time difference from UTC. | `2022-12-28T12:00:00-04:00` |
| `timestamp without time zone` | No time zone info. | `2022-12-28T12:00:00` |
@@ -108,15 +112,28 @@ Note that the first part of the timestamp is in UTC (same thing as GMT). The tim
## Limitations
+`convertTimezone` is currently unavailable for the following databases:
+
+- Amazon Athena
+- Druid
+- Google Analytics
+- H2
+- MongoDB
+- Presto
+- SparkSQL
+- SQLite
+
+### Notes on source time zones
+
Metabase displays timestamps without time zone or offset information, which is why you have to be so careful about the [source time zone](#choosing-a-source-time-zone) when using `convertTimezone`.
-The Metabase report time zone only applies to `timestamp with time zone` or `timestamp with offset` data types. For example:
+The Metabase report time zone only applies to `timestamp with time zone` or `timestamp with offset` data types. For example:
-| Raw timestamp | Report time zone | Displayed As |
-|------------------------------------------|-------------------|------------------------|
-| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
-| `2022-12-28T12:00:00-06:00` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
-| `2022-12-28T12:00:00` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
+| Raw timestamp | Report time zone | Displayed As |
+| ---------------------------------------- | ---------------- | ---------------------- |
+| `2022-12-28T12:00:00 AT TIME ZONE 'CST'` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
+| `2022-12-28T12:00:00-06:00` | 'Canada/Eastern' | Dec 28, 2022, 7:00 AM |
+| `2022-12-28T12:00:00` | 'Canada/Eastern' | Dec 28, 2022, 12:00 AM |
The Metabase report time zone will not apply to the output of a `convertTimezone` expression. For example:
diff --git a/docs/questions/query-builder/expressions/datetimeadd.md b/docs/questions/query-builder/expressions/datetimeadd.md
index e480fe9c284..6eecd449911 100644
--- a/docs/questions/query-builder/expressions/datetimeadd.md
+++ b/docs/questions/query-builder/expressions/datetimeadd.md
@@ -6,19 +6,21 @@ title: DatetimeAdd
`datetimeAdd` takes a datetime value and adds some unit of time to it. This function is useful when you're working with time series data that's marked by a "start" and an "end", such as sessions or subscriptions data.
-| Syntax | Example |
-|-------------------------------------------------------------------------------------|----------------------------------------|
-| `datetimeAdd(column, amount, unit)` | `datetimeAdd("2021-03-25", 1, "month")`|
-| Takes a timestamp or date value and adds the specified number of time units to it. | `2021-04-25` |
+| Syntax | Example |
+| ---------------------------------------------------------------------------------- | --------------------------------------- |
+| `datetimeAdd(column, amount, unit)` | `datetimeAdd("2021-03-25", 1, "month")` |
+| Takes a timestamp or date value and adds the specified number of time units to it. | `2021-04-25` |
## Parameters
`column` can be any of:
+
- The name of a timestamp column,
- a custom expression that returns a [datetime](#accepted-data-types), or
- a string in the format `"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"`(as shown in the example above).
`unit` can be any of:
+
- "year"
- "quarter"
- "month"
@@ -28,6 +30,7 @@ title: DatetimeAdd
- "millisecond"
`amount`:
+
- A whole number or a decimal number.
- May be a negative number: `datetimeAdd("2021-03-25", -1, "month")` will return `2021-04-25`.
@@ -36,7 +39,7 @@ title: DatetimeAdd
Let's say you're a coffee connoisseur, and you want to keep track of the freshness of your beans:
| Coffee | Opened On | Finish By |
-|------------------------|-------------------|-------------------|
+| ---------------------- | ----------------- | ----------------- |
| DAK Honey Dude | October 31, 2022 | November 14, 2022 |
| NO6 Full City Espresso | November 7, 2022 | November 21, 2022 |
| Ghost Roaster Giakanja | November 27, 2022 | December 11, 2022 |
@@ -60,21 +63,21 @@ Unfortunately, Metabase doesn't currently support functions like `today`. If you
The result should give you a **Today** column that's non-empty if today's date falls inside the coffee freshness window:
-| Coffee | Opened On | Finish By | Today |
-|------------------------|-------------------|-------------------|-------------------|
+| Coffee | Opened On | Finish By | Today |
+| ---------------------- | ----------------- | ----------------- | ----------------- |
| DAK Honey Dude | October 31, 2022 | November 14, 2022 | November 11, 2022 |
| NO6 Full City Espresso | November 7, 2022 | November 21, 2022 | November 11, 2022 |
| Ghost Roaster Giakanja | November 27, 2022 | December 11, 2022 | |
## Accepted data types
-| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `datetimeAdd` |
-| ----------------------- | -------------------- |
-| String | ⌠|
-| Number | ⌠|
-| Timestamp | ✅ |
-| Boolean | ⌠|
-| JSON | ⌠|
+| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `datetimeAdd` |
+| ------------------------------------------------------------------------------------------------ | ------------------------ |
+| String | ⌠|
+| Number | ⌠|
+| Timestamp | ✅ |
+| Boolean | ⌠|
+| JSON | ⌠|
We use "timestamp" and "datetime" to talk about any temporal data type that's supported by Metabase.
diff --git a/docs/questions/query-builder/expressions/datetimediff.md b/docs/questions/query-builder/expressions/datetimediff.md
index 160dd085ca8..395697e1b9f 100644
--- a/docs/questions/query-builder/expressions/datetimediff.md
+++ b/docs/questions/query-builder/expressions/datetimediff.md
@@ -6,36 +6,54 @@ title: DatetimeDiff
`datetimeDiff` gets the amount of time between two datetime values, using the specified unit of time. Note that the difference is calculated in _whole_ units (see the example below).
-| Syntax | Example |
-|-----------------------------------------------------------------------------------------------------------|---------------------------------------------------------------|
-| `datetimeDiff(datetime1, datetime2, unit)` | `datetimeDiff("2022-02-01", "2022-03-01", "month")` |
-| Gets the difference between two datetimes (datetime2 minus datetime 1) using the specified unit of time. | `1` |
+| Syntax | Example |
+| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------- |
+| `datetimeDiff(datetime1, datetime2, unit)` | `datetimeDiff("2022-02-01", "2022-03-01", "month")` |
+| Gets the difference between two datetimes (datetime2 minus datetime 1) using the specified unit of time. | `1` |
## Parameters
`datetime1` and `datetime2` can be:
+
- The name of a timestamp column,
- a custom expression that returns a [datetime](#accepted-data-types), or
- a string in the format `"YYYY-MM-DD"` or `"YYYY-MM-DDTHH:MM:SS"` (as shown in the example above).
`unit` can be any of:
+
- "year"
-- "quarter"
- "month"
- "day"
- "hour"
- "second"
- "millisecond"
+## Limitations
+
+`datetimeDiff` is currently unavailable for the following databases:
+
+- Amazon Athena
+- Druid
+- Google Analytics
+- H2
+- MongoDB
+- Oracle
+- Presto
+- Redshift
+- SparkSQL
+- SQLite
+- SQL Server
+- Vertica
+
## Calculating age
Let's say you're a cheesemaker, and you want to keep track of your ripening process:
-| Cheese | Aging Start | Aging End | Mature Age (Months) |
-|-------------------|------------------|------------------|-----------------------|
-| Provolone | January 19, 2022 | March 17, 2022 | 1 |
-| Feta | January 25, 2022 | May 3, 2022 | 3 |
-| Monterey Jack | January 27, 2022 | October 11, 2022 | 8 |
+| Cheese | Aging Start | Aging End | Mature Age (Months) |
+| ------------- | ---------------- | ---------------- | ------------------- |
+| Provolone | January 19, 2022 | March 17, 2022 | 1 |
+| Feta | January 25, 2022 | May 3, 2022 | 3 |
+| Monterey Jack | January 27, 2022 | October 11, 2022 | 8 |
**Mature Age (Months)** is a custom column with the expression:
@@ -54,11 +72,11 @@ Metabase doesn't currently support datetime functions like `today`. To calculate
The result should give you a **Today** column that's non-empty if today's date is on or after the **Aging Start** date.
-| Cheese | Aging Start | Aging End | Mature Age (Months) | Today | Current Age (Months) |
-|-------------------|------------------|------------------|-----------------------|--------------------|-----------------------|
-| Provolone | January 19, 2022 | March 17, 2022 | 1 | September 19, 2022 | 8 |
-| Feta | January 25, 2022 | May 3, 2022 | 3 | September 19, 2022 | 7 |
-| Monterey Jack | January 27, 2022 | October 11, 2022 | 8 | September 19, 2022 | 7 |
+| Cheese | Aging Start | Aging End | Mature Age (Months) | Today | Current Age (Months) |
+| ------------- | ---------------- | ---------------- | ------------------- | ------------------ | -------------------- |
+| Provolone | January 19, 2022 | March 17, 2022 | 1 | September 19, 2022 | 8 |
+| Feta | January 25, 2022 | May 3, 2022 | 3 | September 19, 2022 | 7 |
+| Monterey Jack | January 27, 2022 | October 11, 2022 | 8 | September 19, 2022 | 7 |
Then, you can calculate **Current Age (Months)** like this:
@@ -68,13 +86,13 @@ datetimeDiff([Aging Start], [Today], "month")
## Accepted data types
-| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `datetimeDiff` |
-| ----------------------- | -------------------- |
-| String | ⌠|
-| Number | ⌠|
-| Timestamp | ✅ |
-| Boolean | ⌠|
-| JSON | ⌠|
+| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `datetimeDiff` |
+| ------------------------------------------------------------------------------------------------ | ------------------------- |
+| String | ⌠|
+| Number | ⌠|
+| Timestamp | ✅ |
+| Boolean | ⌠|
+| JSON | ⌠|
We use "timestamp" and "datetime" to talk about any temporal data type that's supported by Metabase.
--
GitLab