diff --git a/docs/questions/query-builder/expressions-list.md b/docs/questions/query-builder/expressions-list.md index 43d9795e9528d530a93d796847613c65a4bf0675..7b7453c22dbf5dbdad12bd2e88ba3f9df52a2ee3 100644 --- a/docs/questions/query-builder/expressions-list.md +++ b/docs/questions/query-builder/expressions-list.md @@ -32,8 +32,8 @@ For an introduction to expressions, check out [Writing expressions in the notebo - [coalesce](./expressions/coalesce.md) - [concat](./expressions/concat.md) - [contains](#contains) - - [datetimeAdd](#datetimeadd) - - [datetimeSubtract](#datetimesubtract) + - [datetimeAdd](./expressions/datetimeadd.md) + - [datetimeSubtract](./expressions/datetimesubtract.md) - [day](#day) - [endswith](#endswith) - [exp](#exp) @@ -268,7 +268,7 @@ Example: `contains([Status], "Class")`. If `Status` were "Classified", the expre Related: [regexextract](#regexextract). -### datetimeAdd +### [datetimeAdd](./expressions/datetimeadd.md) Adds some unit of time to a date or timestamp value. @@ -280,7 +280,7 @@ Syntax: `datetimeAdd(column, amount, unit)`. Example: `datetimeAdd("March 25, 2021, 12:52:37", 1, "month")` would return `April 25, 2021, 12:52:37`. -### datetimeSubtract +### [datetimeSubtract](./expressions/datetimesubtract.md) Subtracts some unit of time from a date or timestamp value. diff --git a/docs/questions/query-builder/expressions/concat.md b/docs/questions/query-builder/expressions/concat.md index 865795e4a51a3faef9f598b69b999fc8a46ec4da..3e8e98d0ad82a341c4a0119ed28173a14f72c2b5 100644 --- a/docs/questions/query-builder/expressions/concat.md +++ b/docs/questions/query-builder/expressions/concat.md @@ -93,4 +93,4 @@ concat([City], ", ", [Country]) ## Further reading - [Custom expressions documentation](../expressions.md) -- [Custom expressions tutorial](https://www.metabase.com/learn/questions/) \ No newline at end of file +- [Custom expressions tutorial](https://www.metabase.com/learn/questions/custom-expressions) \ No newline at end of file diff --git a/docs/questions/query-builder/expressions/datetimeadd.md b/docs/questions/query-builder/expressions/datetimeadd.md new file mode 100644 index 0000000000000000000000000000000000000000..9ac5206c9e0782c879dfabdb65b5f76b5d5fdd52 --- /dev/null +++ b/docs/questions/query-builder/expressions/datetimeadd.md @@ -0,0 +1,149 @@ +--- +title: DatetimeAdd +--- + +# 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("March 25, 2021, 12:52:37", 1, "month")`| +| Takes a timestamp or date value and adds the specified number of time units to it. | `April 25, 2021, 12:52:37` | + +## Parameters + +- Units can be any of: "year", "quarter", "month", "day", "hour", "second", or "millisecond". +- Amounts can be negative: `datetimeAdd("March 25, 2021, 12:52:37", -1, "month")` will return `February 25, 2021, 12:52:37`. + +## Calculating an end date + +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 | 2022-10-31 | 2022-11-14 | +| NO6 Full City Espresso | 2022-11-07 | 2022-11-21 | +| Ghost Roaster Giakanja | 2022-11-27 | 2022-12-11 | + +Here, **Finish By** is a custom column with the expression: + +``` +datetimeAdd([Opened On], 14, 'day') +``` + +You can use the [`between`](../expressions-list.md#between) or [`interval`](../expressions-list.md#interval) expressions to check if a given date falls between your start and end datetimes. + +## 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 | ⌠| + +This table uses `timestamp` and `datetime` interchangeably---just make sure that your dates and times aren't stored as string or a number data types in your database. + +## Limitations + +You can use `datetimeAdd` to _calculate_ relative dates given a column of date values, but unfortunately Metabase doesn't currently let you _generate_ a relative date (such as today's date). + +For example, if you want to check if today's date falls between **Opened On** and **Finish By** in the [Coffee example](#calculating-an-end-date): + +- Ask your database admin if there's table in your database that stores dates for reporting (sometimes called a date dimension table). +- Create a new question using the date dimension table, with a filter for "Today". +- Turn the "Today" question into a model. +- Create a left join between **Coffee** and the "Today" model on `[Opened On] <= [Today]` and `[Finish By] >= [Today]`. + +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 | +|------------------------|------------|------------|------------| +| DAK Honey Dude | 2022-10-31 | 2022-11-14 | 2022-11-10 | +| NO6 Full City Espresso | 2022-11-07 | 2022-11-21 | 2022-11-10 | +| Ghost Roaster Giakanja | 2022-11-27 | 2022-12-11 | | + +## Related functions + +This section covers functions and formulas that work the same way as the Metabase `datetimeAdd` expression, with notes on how to choose the best option for your use case. + +**[Metabase expressions](../expressions-list.md)** + +- [datetimeSubtract](#datetimesubtract) + +**Other tools** + +- [SQL](#sql) +- [Spreadsheets](#spreadsheets) +- [Python](#python) + +### datetimeSubtract + +`datetimeSubtract` and `datetimeAdd` are interchangeable, since you can use a negative number for `amount`. It's generally a good idea to avoid double negatives (such as subtracting a negative number). + +``` +datetimeSubtract([Opened On], -14, "day") +``` + +does the same thing as + +``` +datetimeAdd([Opened On], 14, 'day') +``` + +### SQL + +When you run a question using the [query_builder](https://www.metabase.com/glossary/query_builder), Metabase will convert your graphical query settings (filters, summaries, etc.) into a query, and run that query against your database to get your results. + +If our [coffee sample data](#calculating-an-end-date) is stored in a PostgreSQL database: + +```sql +SELECT opened_on + INTERVAL '14 days' AS finish_by +FROM coffee +``` + +is equivalent to the Metabase `datetimeAdd` expression: + +``` +datetimeAdd([Opened On], 14, 'day') +``` + +### Spreadsheets + +If our [coffee sample data](#calculating-an-end-date) is in a spreadsheet where "Opened On" is in column A with a date format, the spreadsheet function + +``` +A:A + 14 +``` + +produces the same result as + +``` +datetimeAdd([Opened On], 14, 'day') +``` + +Most spreadsheet tools require use different functions for different time units (for example, you'd use a different function to add "months" to a date). `datetimeAdd` makes it easy for you to convert all of those functions to a single consistent syntax. + +### Python + +Assuming the [coffee sample data](#calculating-an-end-date) is in a `pandas` dataframe column called `df`, you can import the `datetime` module and use the `timedelta` function: + +``` +df['Finish By'] = df['Opened On'] + datetime.timedelta(days=14) +``` + +is equivalent to + +``` +datetimeAdd([Opened On], 14, 'day') +``` + +## Further reading + +- [Custom expressions documentation](../expressions.md) +- [Custom expressions tutorial](https://www.metabase.com/learn/questions/custom-expressions) +- [Time series comparisons](https://www.metabase.com/learn/questions/time-series-comparisons) +- [How to compare one time period to another](https://www.metabase.com/learn/dashboards/compare-times) +- [Working with dates in SQL](https://www.metabase.com/learn/sql-questions/dates-in-sql) diff --git a/docs/questions/query-builder/expressions/datetimesubtract.md b/docs/questions/query-builder/expressions/datetimesubtract.md new file mode 100644 index 0000000000000000000000000000000000000000..6e23feac7e841c8d8c9952bd92d9b7fb7e16d19c --- /dev/null +++ b/docs/questions/query-builder/expressions/datetimesubtract.md @@ -0,0 +1,149 @@ +--- +title: DatetimeSubtract +--- + +# DatetimeSubtract + +`datetimeSubtract` takes a datetime value and subtracts some unit of time from it. You might want to use this function when working with time series data that's marked by a "start" and an "end", such as sessions or subscriptions data. + +| Syntax | Example | +|-------------------------------------------------------------------------------------------|-----------------------------------------------------------| +| `datetimeSubtract(column, amount, unit)` | `datetimeSubtract("March 25, 2021, 12:52:37", 1, "month")`| +| Takes a timestamp or date value and subtracts the specified number of time units from it. | `February 25, 2021, 12:52:37` | + +## Parameters + +- Units can be any of: "year", "quarter", "month", "day", "hour", "second", or "millisecond". +- Amounts can be negative: `datetimeSubtract("March 25, 2021, 12:52:37", -1, "month")` will return `April 25, 2021, 12:52:37`. + +## Calculating a start date + +Let's say you're planning a fun night out. You know it takes 30 minutes to get from place to place, and you need to figure out what time you have to leave to get to each of your reservations: + +| Event | Arrive By | Depart At | +|---------|---------------------|---------------------| +| Drinks | 2022-11-12 18:30:00 | 2022-11-12 18:00:00 | +| Dinner | 2022-11-12 20:00:00 | 2022-11-12 19:30:00 | +| Dancing | 2022-11-13 00:00:00 | 2022-11-12 23:30:00 | + +Here, **Depart At** is a custom column with the expression: + +``` +datetimeSubtract([Arrive By], 30, "minute") +``` + +You can use the [`between`](../expressions-list.md#between) or [`interval`](../expressions-list.md#interval) expressions to check if a given date falls between your start and end datetimes. + +## Accepted data types + +| [Data type](https://www.metabase.com/learn/databases/data-types-overview#examples-of-data-types) | Works with `datetimeSubtract` | +| ----------------------- | -------------------- | +| String | ⌠| +| Number | ⌠| +| Timestamp | ✅ | +| Boolean | ⌠| +| JSON | ⌠| + +This table uses `timestamp` and `datetime` interchangeably---just make sure that your dates and times aren't stored as string or a number data types in your database. + +## Limitations + +You can use `datetimeSubtract` to calculate relative dates given a column of date values, but unfortunately Metabase doesn't currently let you _generate_ a relative date (such as today's date). + +What if you want to check if today's date falls between **Arrive By** and **Depart At** in our [events example](#calculating-a-start-date)? + +1. Ask your database admin if there's table in your database that stores datetimes for reporting (sometimes called a date dimension table). +2. Create a new question using the date dimension table, with a filter for "Today". +3. Turn the "Today" question into a model. +4. Create a left join between **Events** and the "Today" model on `[Arrive By] <= [Today]` and `[Depart At] >= [Today]`. + +The result should give you an **Today** column that's non-empty for events that are happening while the night is still young: + +| Event | Arrive By | Depart At | Today | +|---------|---------------------|---------------------|---------------------| +| Drinks | 2022-11-12 18:30:00 | 2022-11-12 18:00:00 | 2022-11-12 00:00:00 | +| Dinner | 2022-11-12 20:00:00 | 2022-11-12 19:30:00 | 2022-11-12 00:00:00 | +| Dancing | 2022-11-13 00:00:00 | 2022-11-12 23:30:00 | | + +## Related functions + +This section covers functions and formulas that work the same way as the Metabase `datetimeSubtract` expression, with notes on how to choose the best option for your use case. + +**[Metabase expressions](../expressions-list.md)** + +- [datetimeAdd](#datetimeadd) + +**Other tools** + +- [SQL](#sql) +- [Spreadsheets](#spreadsheets) +- [Python](#python) + +### datetimeAdd + +`datetimeSubtract` and `datetimeAdd` are interchangeable, since you can use a negative number for `amount`. We could use either expression for our [events example](#calculating-a-start-date), but you should try to avoid "double negatives" (such as subtracting a negative number). + +``` +datetimeAdd([Arrive By], -30, "minute") +``` + +does the same thing as + +``` +datetimeSubtract([Arrive By], 30, "minute") +``` + +### SQL + +When you run a question using the [query builder](https://www.metabase.com/glossary/query_builder), Metabase will convert your graphical query settings (filters, summaries, etc.) into a query, and run that query against your database to get your results. + +If our [events sample data](#calculating-a-start-date) is stored in a PostgreSQL database: + +```sql +SELECT arrive_by - INTERVAL '30 minutes' AS depart_at +FROM events +``` + +is equivalent to the Metabase `datetimeSubtract` expression: + +``` +datetimeSubtract([Arrive By], 30, "minute") +``` + +### Spreadsheets + +Assuming the [events sample data](#calculating-a-start-date) is in a spreadsheet where "Arrive By" is in column A with a datetime format, the spreadsheet function + +``` +A:A - 30/(60*24) +``` + +produces the same result as + +``` +datetimeSubtract([Arrive By], 30, "minute") +``` + +Most spreadsheets require you to use different calculations for different time units (for example, you'd need to use a different calculation to subtract "days" from a date). `datetimeSubtract` makes it easy for you to convert all of those functions to a single consistent syntax. + +### Python + +If our [events sample data](#calculating-a-start-date) is in a `pandas` dataframe column called `df`, you can import the `datetime` module and use the `timedelta` function: + +``` +df['Depart At'] = df['Arrive By'] - datetime.timedelta(minutes=30) +``` + +is equivalent to + +``` +datetimeSubtract([Arrive By], 30, "minute") +``` + +## Further reading + +- [Custom expressions documentation](../expressions.md) +- [Custom expressions tutorial](https://www.metabase.com/learn/questions/custom-expressions) +- [Time series comparisons](https://www.metabase.com/learn/questions/time-series-comparisons) +- [How to compare one time period to another](https://www.metabase.com/learn/dashboards/compare-times) +- [Working with dates in SQL](https://www.metabase.com/learn/sql-questions/dates-in-sql) \ No newline at end of file diff --git a/docs/questions/query-builder/expressions/regexextract.md b/docs/questions/query-builder/expressions/regexextract.md index 93085331781beb14a0f5cfba63285b94d8fc792c..bfab1d90d1355131bd97a17c9b9533dc2f05ef95 100644 --- a/docs/questions/query-builder/expressions/regexextract.md +++ b/docs/questions/query-builder/expressions/regexextract.md @@ -137,4 +137,4 @@ regexextract([URL], "^[^?#]+\?utm_campaign=(.*)") ## Further reading - [Custom expressions documentation](../expressions.md) -- [Custom expressions tutorial](https://www.metabase.com/learn/questions/) +- [Custom expressions tutorial](https://www.metabase.com/learn/questions/custom-expressions) diff --git a/docs/questions/query-builder/expressions/substring.md b/docs/questions/query-builder/expressions/substring.md index efb5f43e8d679ecd7c51e14a1e77567a92b43cb8..be8b2ce135b54fb6652a9af53b6d0d4005dcdc17 100644 --- a/docs/questions/query-builder/expressions/substring.md +++ b/docs/questions/query-builder/expressions/substring.md @@ -149,4 +149,4 @@ substring([Mission ID], 9, 3) ## Further reading - [Custom expressions documentation](../expressions.md) -- [Custom expressions tutorial](https://www.metabase.com/learn/questions/) +- [Custom expressions tutorial](https://www.metabase.com/learn/questions/custom-expressions)