Docs: Rewrite SQL variables (#13031)

Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
Co-authored-by: Edwin Lim <edwin@posthog.com>
Co-authored-by: PostHog <hey@posthog.com>

contents/docs/data-warehouse/sql/index.mdx

@@ -12,7 +12,7 @@ The [SQL editor](https://us.posthog.com/sql) enables you to directly access all
 
 You create SQL queries out of a list of commands that shape what data, filters, aggregations, and ordering we want to see. 
 
-> SQL queries in PostHog don’t require the trailing semicolon (`;`) of traditional SQL queries.
+> SQL queries in PostHog don't require the trailing semicolon (`;`) of traditional SQL queries.
 
 ### SELECT
 
@@ -112,7 +112,7 @@ WHERE event = '$pageview'
    AND properties.$current_url LIKE '%/blog%'
 ```
 
-To have the insight or dashboard date range selector apply to the insight, include `{filters}` in query like this:
+To have the insight or dashboard date range and other filters apply to the insight, include [`{filters}` variable](/docs/data-warehouse/sql/variables) in your query like this:
 
 ```sql
 SELECT *

contents/docs/data-warehouse/sql/useful-functions.mdx

@@ -58,6 +58,8 @@ FROM events
 WHERE timestamp > now() - interval 1 day
 ```
 
+If you want to access dashboard or insight date filters, you can use the [`filters` variable](/docs/data-warehouse/sql/variables) like `filters.dateRange.from` and `filters.dateRange.to`.
+
 > Read more examples in [How to do time-based breakdowns (hour, minute, real time)](/tutorials/time-breakdowns) and [Using SQL for advanced time and date filters](/tutorials/hogql-date-time-filters).
 
 ### String

contents/docs/data-warehouse/sql/variables.mdx

@@ -8,44 +8,65 @@ availability:
   enterprise: full
 ---
 
-export const WarehouseLight = "https://res.cloudinary.com/dmukukwp6/image/upload/Clean_Shot_2025_02_24_at_14_05_39_2x_5a280bacfd.png"
-export const WarehouseDark = "https://res.cloudinary.com/dmukukwp6/image/upload/Clean_Shot_2025_02_24_at_14_05_53_2x_32a95cbe79.png"
+SQL variables enable you to dynamically set values in your queries. 
 
-SQL variables enable you to create configurable, reusable queries by defining placeholders that can be dynamically replaced with different values.
+## Creating SQL variables
+
+To create a variable, go to the [SQL editor](https://app.posthog.com/sql), click the **Variables** tab, click **Add variable**, and choose your variable type (string, number, date, list, or boolean). Enter the variable name and value(s) and click **Save** and you'll be able to use it in any of your project's queries.
+
+For example, you can create a list type variable with the key `event_names` and add events like `$pageview` and `$autocapture` as values.
+
+<ProductScreenshot
+  imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/Clean_Shot_2025_10_02_at_17_04_16_2x_aac766c379.png"
+  imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/q_auto,f_auto/Clean_Shot_2025_10_02_at_17_04_41_2x_aaefee30c4.png"
+  alt="Creating a variable"
+  classes="rounded"
+/>
 
 ## Using variables in SQL queries
 
-You must first create a variable in the variable sidebar panel. Once created, variables in PostHog SQL are defined using the `{variables.<variable-name>}` syntax. When you write a query with variables, you'll be prompted to provide values for each variable.
-
-
-For example, this query uses a variable to filter events by a specific date range:
+Once created, variables can be used in queries with the `{variables.<variable-name>}` syntax like this:
 
 ```sql
-SELECT 
-    event,
-    count() as count
-FROM events
-WHERE timestamp >= {variables.startdate}
-    AND timestamp <= {variables.enddate}
-GROUP BY event
-ORDER BY count DESC
-LIMIT 10
+select * 
+from events 
+where event = {variables.event_names}
 ```
 
-When you run this query, you'll be prompted to provide values for `startdate` and `enddate`.
+You can set the value for the variable in the same **Variables** tab, on the insight, or on the dashboard once you've created and added an SQL insight to it. For example, below we set the "event names" variable to `$autocapture` on the dashboard. This means every instance of `{variables.event_names}` in the queries on the dashboard is replaced with `$autocapture`. 
 
 <ProductScreenshot
-  imageLight={WarehouseLight}
-  imageDark={WarehouseDark}
-  alt="SQL Editor variable example"
+  imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Clean_Shot_2025_10_02_at_17_12_45_2x_0e6a9a873a.png"
+  imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Clean_Shot_2025_10_02_at_17_12_27_2x_b5f9fcff28.png"
+  alt="Using a variable in a SQL query"
+  classes="rounded"
 />
 
-## Variable types
+## Dashboard filter variables
 
-Variables can be used for various data types:
+Beyond the SQL variables you set up, there are also some variables that are automatically available to you when using SQL insights in a dashboard. You can access the dashboard's filters through the `filters` variable.
 
-- **String**: Text values like event names or property values
-- **Number**: Numeric values for thresholds or limits
-- **Date**: Timestamp values for time-based filtering
-- **List**: List of pre-defined values to select
-- **Boolean**: True/false values for conditional logic
+They include:
+
+- `filters.dateRange.from` - Start date of the dashboard date range
+- `filters.dateRange.to` - End date of the dashboard date range
+- `filters.properties` - Array of property filters applied at the dashboard level
+- `filters.breakdown_filter` - Breakdown configuration from dashboard filters
+- `filters.compare` - Comparison settings if enabled
+- `filters.interval` - Time interval setting from dashboard
+
+For example, to add the dashboard's date range to the query, you can use the `filters.dateRange.from` and `filters.dateRange.to` variables like this:
+
+```sql
+select * 
+from events 
+where event = {variables.event_names}
+and timestamp >= {filters.dateRange.from} and timestamp < {filters.dateRange.to}
+```
+
+<ProductScreenshot
+  imageLight="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Clean_Shot_2025_10_02_at_17_16_57_2x_161c9b6f38.png"
+  imageDark="https://res.cloudinary.com/dmukukwp6/image/upload/w_1600,c_limit,q_auto,f_auto/Clean_Shot_2025_10_02_at_17_17_11_2x_a670c7930a.png"
+  alt="Using dashboard filter variables in a SQL query"
+  classes="rounded"
+/>

contents/docs/product-analytics/dashboards.mdx

@@ -52,10 +52,12 @@ If you already have some insights set up, an alternative approach is to click **
 
 ### Date range overrides
 
-New dashboards are set to 'No date range overide' by default. This means all insights will use the date range applied in their configuration. 
+New dashboards are set to *No date range override* by default. This means all insights use the date range applied in their configuration. 
 
 Changing the date range on a dashboard forces all the insights to use the same date range, but this doesn't impact the date range that's shown when viewing an individual insight.
 
+The date range can be accessed in SQL insights through the [`filters` variable](/docs/data-warehouse/sql/variables) like `filters.dateRange.from` and `filters.dateRange.to`.
+
 ### Dashboard filters
 
 Dashboards also support most of the same [filters](/docs/product-analytics/trends/filters) as individual insights, including:
@@ -77,6 +79,8 @@ Using filters on dashboards is a useful way to compare usage between different t
 
 You could, for example, duplicate a dashboard – click on the '...' menu and click 'Duplicate' – and apply different filters to each version of the dashboard.
 
+Filters can be accessed in SQL insights through the [`filters` variable](/docs/data-warehouse/sql/variables) like `filters.properties` and `filters.breakdown_filter`.
+
 ## Dashboard options
 
 ### Editing the layout