Merge pull request #18617 from newrelic/nb-extra-release-template-var…

…iables

nb extra release template variables

src/content/docs/query-your-data/explore-query-data/dashboards/dashboard-template-variables.mdx

@@ -2,19 +2,21 @@
 title: "Template variables: dynamically filter dashboards"
 tags:
   - Dashboards
+  - Template variables
 metaDescription: 'For New Relic custom dashboards: use template variables to allow your dashboard users to dynamically filter your dashboard views.'
 redirects:
 freshnessValidatedDate: never
 ---
 
-For custom dashboards, you can use <DNT>**template variables**</DNT> to dynamically filter charts and other widgets. Template variables help make your dashboards more useful, and help you more easily create dashboards you can reuse for different use cases.
+For custom dashboards, you can use <DNT>**template variables**</DNT> to dynamically filter charts and other widgets. Template variables make your dashboards more useful and help you more easily create dashboards that you can reuse for different use cases.
 
 ## Why use template variables? [#defined]
 
 Template variables are a powerful and dynamic way of filtering an entire dashboard based on specific metadata values a dashboard creator chooses. The benefits of using template variables are:
 
-* They make dashboards easier to use: your users don't have to understand the structure of the data, but can simply choose from various filter options you've set.
-* They allow you to create reusable dashboard templates, which you can then duplicate and adjust for many other uses.
+* They make dashboards easier to use: Your users don't have to understand the structure of the data; they can simply choose from the various filter options you've set.
+
+* They allow you to create reusable dashboard templates that you can then duplicate and customize for many other uses.
 
 Here's an example of a dashboard with several template variables, which you can see at the top of the dashboard.
 
@@ -24,13 +26,59 @@ Here's an example of a dashboard with several template variables, which you can
   src="/images/dashboards_screenshot-full_with-template-variables.webp"
 />
 
+<figcaption>
+    Go to <DNT>**[one.newrelic.com > All capabilities](https://one.newrelic.com/all-capabilities) > Dashboards**</DNT>
+</figcaption>
+
+
 With template variables, you can set up a wide variety of variables and filters to create the dashboard experience you need. Examples of experiences you can create:
 
 * A dropdown to choose an app name
 * A dropdown to choose specific regions
 * A dropdown to select specific durations or other numeric values
 * Filters that use free text fields to find matching strings
 
+Furthermore, you can now decide if you want to include the variable or not without having to modify your queries. See the [Include variable](/docs/query-your-data/explore-query-data/dashboards/dashboard-template-variables/#include-variable) section for details. 
+
+## Include and exclude variables [#include-variable]
+
+The <DNT>**Include variable**</DNT> toggle allows you to set a desired value and include or exclude that value in your dashboards. See the [template variables](/docs/query-your-data/explore-query-data/dashboards/dashboard-template-variables/#create-variables) section for more info.
+
+For example, you may be investigating an issue that is not specific to any particular value within a variable. In such cases, the variable's existing values might be limiting query results, even when selecting all possible options. To address this, you can exclude the variable from the query. This effectively removes the variable's condition and replaces it with a neutral boolean value (true or false), ensuring query validity and returning comprehensive results.  
+
+### Example
+
+Consider a query that filters results based on a `countryCode` variable. If you want to view data for all countries without filtering, you can exclude the variable:
+
+Original query:
+
+    ```sql
+    FROM PageAction 
+    SELECT count(*) AS 'views' 
+    WHERE countryCode IN ({{countryCode}}) and appName = 'Test App' FACET countryCode
+    ```
+
+Query with an excluded variable:
+
+  ```sql
+    FROM PageAction 
+    SELECT count(*) AS 'views' 
+    WHERE true and appName = 'Test App' FACET countryCode
+  ```
+
+This feature is particularly useful when: 
+
+* The variable has more values than the maximum allowed (for instance, 5000 max results for uniques by default) or a very high number of values. Choosing to disable the variable by default will deliver considerable performance improvements.
+
+* The data source for the variable differs from the database you're querying. 
+In these cases, selecting all values from the database using "Select all" isn't sufficient. By excluding the variable, you can retrieve all values from the database.
+
+Limitations on include variable: 
+
+* When used in FACET cases, the condition is replaced with true and converts it to an always-true condition. 
+
+* When used in other contexts like functions or with the SELECT statement, you'll get the following error: `"Unknown function Disable_variable()"`. This is because the disable variable function isn't implemented for these specific cases yet.
+
 ## Requirements and limitations [#requirements]
 
 Template variables can only be used in the context of making widgets for custom dashboards. See [NRQL variables](/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/#with-as-nrql-var) for using variables in a NRQL query.
@@ -60,12 +108,12 @@ We'll walk you through creating a template variable, and then we'll give you a f
 
 Creating a template variable consists of two steps.
 
-<CollapserGroup>
-  <Collapser
-    id="step1"
-    title="Step 1. Define the template variable"
-  >
-    First, you'll define a template variable. This is the variable that you'll use in a NRQL query to create a widget.
+<Steps>
+    <Step>
+
+    ### Define the template variable [#step1]
+
+First, you'll define a template variable. This is the variable that you'll use in a NRQL query to create a widget.
 
     To define a variable:
 
@@ -185,9 +233,14 @@ Creating a template variable consists of two steps.
           </td>
 
           <td>
-            Optional. These are the defaults value that the dashboard will filter on. For example, if you used the `country` query above, you could input `ES` as the default value and the dashboard would automatically filter to that value. You can also select all possibilities.
+            Optional. These are the default values that the dashboard will filter on. For example, if you used the `country` query above, you could input `ES` as the default value and the dashboard would automatically filter to that value. You can also select all possibilities.
 
             To use multiple values on a `WHERE` clause you need to use [`IN`](/docs/query-your-data/nrql-new-relic-query-language/get-started/nrql-syntax-clauses-functions/#sel-where) instead of `=`.
+            
+            The ** Include variable** toggle will determine the default configuration, include or exclude, for that variable in the dashboard. This configuration can be modified by the user viewing the dashboard by using the ** Include variable** toggle in the variable dropdown menu. The user selected configuration will be valid for the duration of the session. 
+            <Callout variant="important">
+            Note that you can only configure default values when the toggle is set to include variable. Once you select the default values you can switch the toggle so the variable is not included by default. The default values will be preselected when any user turns the toggle to include the variable from the variable dropdown menu.
+            </Callout>
           </td>
         </tr>
 
@@ -217,12 +270,12 @@ Creating a template variable consists of two steps.
     />
 
     Once you've defined your template variable, you can add a widget that uses your created template variable.
-  </Collapser>
 
-  <Collapser
-    id="step2"
-    title="Step 2. Create widgets that use the template variable"
-  >
+        
+    </Step>
+    <Step>
+    ### Create widgets that use the template variable [#step2]
+
     Once you've configured a template variable, you'll need widgets on a dashboard that use the variable that you've defined in their query.
 
     To create a widget:
@@ -240,7 +293,9 @@ Creating a template variable consists of two steps.
        Following our example mentioned in step 1:
 
        ```sql
-       SELECT countryCode FROM PageAction WHERE countryCode IN ({{countryCode}})
+       SELECT countryCode 
+       FROM PageAction 
+       WHERE countryCode IN ({{countryCode}})
        ```
 
        <img
@@ -254,12 +309,14 @@ Creating a template variable consists of two steps.
        Instead, the following list of NRQL clauses will not accept template variables as arguments: `AS`, `COMPARE WITH`, `LIMIT`, `OFFSET`, `SINCE`, `SLIDE BY`, `TIMESERIES`, `UNTIL` and `WITH...`.
 
     5. Click <DNT>**Save**</DNT>
-  </Collapser>
-</CollapserGroup>
+
+    </Step>
+</Steps>
 
 When you're done defining a template variable and adding a widget that references that variable, you can verify it's working as expected by choosing different options from the template variable bar and seeing if the widget changes based on your selection.
 
 Here's an example of the resulting widget, on the right, with the `country` dropdown to the left.
+
 <img title="Country template variable example" alt="Country template variable example" src="/images/dashboards_screenshot-crop_country-variable-example.webp"/>
 
 ## Rules for writing a query-type template variable [#query-variable-rules]

src/content/whats-new/2024/09/whats-new-09-07-include-variable.md

@@ -0,0 +1,32 @@
+---
+title: 'Filter dashboards faster with template variable toggle'
+summary: 'Template variables can now be included or excluded from your dashboard widgets'
+releaseDate: '2024-09-10'
+learnMoreLink: 'https://docs.newrelic.com/docs/query-your-data/explore-query-data/dashboards/dashboard-template-variables/#include-variable'
+---
+
+
+[Template variables](https://docs.newrelic.com/whats-new/2022/11/whats-new-11-30-dashboard-template-variables/) allow you to dynamically filter charts and widgets in your custom dashboards, making dashboards more adaptable for various use cases.
+Now, you have more flexibility when configuring variables with the **Include variable** toggle. It allows you to exclude variables that have been added to one or more widgets in a dashboard. You do not need to modify any queries.
+
+<iframe width="560" height="315" src="https://fast.wistia.net/embed/iframe/vr5sy04mpf" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+
+
+## How it works
+
+Previously, when you used variables in widgets, your queries were limited to the values defined for that variable, which could be limiting in certain scenarios, such as missing values. This could result in incomplete data being shown in charts, even if you used the **Select all** values. Alternatively, a variable may have a very large number of values. Choosing to disable the variable by default will provide significant performance improvements.
+
+Now, when you choose to exclude a variable, it's removed from the query and the condition is replaced with a neutral boolean value (either true or false). This ensures that your query remains valid and returns results for your dashboard. By excluding the variable, you can retrieve all values from the database.
+
+
+## How to configure variable exclusion
+
+1. In your dashboard, click the edit <Icon name="fe-edit-2"/> button.
+2. Then select **+ Add variable** or click on a variable, and select **Edit**.
+3. Now, you'll be able to see a toggle option to **Include variable**.
+
+
+![Configure variable options](/images/include_variable1.webp "Configure variable options")
+Users viewing a dashboard can include the variable again through the variable dropdown menu. This will allow the user to select specific values for that variable to filter their dashboard.
+
+![Include variable toggle](/images/include_variable2.webp "Include variable toggle")