---
sourceDocument: Xanadu Platform Analytics
sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/now-intelligence

 Release :

    - xanadu

ft:locale :

    - en-US

ft:publication_title :

    - Xanadu Platform Analytics

ft:clusterId :

    - par

bundleId :

    - par

workflow :

    - Platform


---

# Use a local data instance with a data visualization

# Use a local data instance with a data visualization {#ariaid-title1}

* Release version: Xanadu
* 
* Updated August 1, 2024
* 
* ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 4 minutes to read

For finer grained control of the data source than you have with preconfigured data sources, create a local data instance. Then bind the local data instance to the dataPassthrough property of the data
visualization.

## Before you begin

Important:  
This is an advanced procedure. Consider carefully whether you need a local data instance or can use a standard data source.

Before proceeding, review [Dynamically expose data in UI Builder pages (advanced feature)](https://www.servicenow.com/docs/access?context=data-resources&version=xanadu&pubname=xanadu-application-development&ft:locale=en-US).

Role required: ui_builder_admin, admin

## Procedure

1. Open the technical dashboard or other UI Builder page in UI Builder.
2. In the Data and scripts drawer, under Data resources, select + Add data resource.  

   ![Add data resource link when there are no data resources yet.]()  
3. In the Select a data resource window, search for <kbd class="ph userinput">Data visualization</kbd>.  
   You get a selection of the data resources you can use.  

4. Select a data resource that matches the type of data you want to show.
5. Read through the information pane and copy or take notes on the configuration details.
6. Select Add.
7. Complete the configuration options that you need for the type of visualization with which you plan to use this data instance.  
   Create and configure a separate local data instance for every type of visualization that you want to use the same data. For example, if you plan to have a bar and a time series that show scores from the same indicator, create two local data instances: one each for bar and time series visualizations, but both on the same indicator.  
   Tip:  
   You can add the data visualization to the page and compare its configuration panel to the options for the local data instance.
8. Copy the `@data` data bind for this data source.  

   <br />

9. Add the desired data visualization component to the page.
10. In the configuration panel for that data visualization, in the Data sources section, turn on Define data manually.
11. For the Data field, select Bind data or use scripts.  

    <br />

12. In the Bind data to Data dialog, under Data types, select Data resource.
13. Double-click in the Add a data output to this area section and paste the data bind to your local data instance into the blue box.
14. Append <kbd class="ph userinput">.output.result</kbd> at the end of the data bind.  
    For example, the completed data bind to the local data instance data_visualization_api_for_table_data_source_1 is `@data.data_visualization_api_for_table_data_source_1.output.result`.  

15. Select Apply.

## Result

You have created a local data instance and bound it to a data visualization. You can now complete the configuration of your data visualization.
**Related tasks**   

* [Create a technical dashboard in UI Builder](https://servicenow-prod.fluidtopics.net/kh7K6HSd1o~EuMbfBoRQkg "Follow the Technical Editor option to create a dashboard using UI Builder. In UI Builder, you can use a wider range of features than the inline editor, including scripting and data binding.")
* [Add a drilldown event to a data visualization in a technical dashboard](https://servicenow-prod.fluidtopics.net/Z1oNn2RmExZLyjlEROqYbw "Technical dashboards do not support preconfigured destinations for drilling down from a data visualization. If you want a viewer to open a more detailed view of the data when they interact with a visualization, configure a custom drilldown event.")
* [Configure an event handler for a Filter component](https://servicenow-prod.fluidtopics.net/YcSy5Ll8pBkxYPTQTrAdMg "On a technical dashboard, configure a special client script-based event handler for a Filter component so it can be followed by any Lists or Data Visualizations. It is not necessary to configure an event handler for filters on inline dashboards.")  
**Related reference**   

* [Technical dashboards compared to inline dashboards](https://servicenow-prod.fluidtopics.net/7XX4XxiQuX4uZe2Y6TUdTA "The inline editor produces dashboard components with events and page properties preconfigured. The technical editor allows for a full range of UIB components but requires more backend configuration.")

## Enable filters to apply to a local data instance {#ariaid-title2}

To enable a viewer to switch between which field values or breakdown elements they see in a data visualization, add filter components to the UI Builder page. For those filters to apply to a local data instance, configure that instance accordingly.

### Before you begin

Role required: ui_builder_admin, admin

### About this task

To enable filters to apply to a local data source, you first have to create a client state parameter named `parFilters` and then add that state parameter to the local data instance.

### Procedure

1. Open the UI Builder page with the local data instance and data visualizations you want to filter.
2. In the Data and scripts drawer, select Client state parameters.
3. Select + Add.
4. In the Edit client state parameters dialog, name the new parameter <kbd class="ph userinput">parFilters</kbd>, assign it type JSON, and set the initial value of <kbd class="ph userinput">{}</kbd>.  

   ![parFilters client state parameter in the Edit client state parameters dialog.]()  
5. Close the Edit client state parameters dialog.
6. In the Data and scripts drawer, under Data resources, select the desired local data instance.
7. In the Edit \<name of local data instance\> dialog, scroll down to the Filter configurations field.
8. Enter <kbd class="ph userinput">@state.parFilters</kbd> into the Filter configurations field and close the data instance editor.
9. In the configuration panel of a data visualization that uses this local data resource, turn on Follow filters in the Data update section.
10. **Optional:** Turn on Show filter icon.
11. Save the UI Builder page.

### What to do next

Add filter components to the UI Builder page and configure them for relevant values from the local data instance.
**Related concepts**   

* [Filters in Platform Analytics](https://servicenow-prod.fluidtopics.net/dLtrHm3CmdIO7YIX95Vpbg "Filter lists and data visualizations on an inline or technical dashboard. Filter by possible data value, by whether the value is true or false, or by date.")

## Enable data caching for a local data instance {#ariaid-title3}

To help reduce the load time of data visualizations, and if real time or very fresh data is not necessary, enable data caching on the data source.

### Before you begin

Role required: ui_builder_admin, admin

### Procedure

1. Open the UI Builder page with the local data instance whose data you want to cache.
2. In the Data and scripts drawer, under Data resources, select the desired local data instance.
3. Scroll down to Use data cache and turn it on.  
   Any data visualization that uses this data source, uses the cache settings on the data source. The data cache settings on the visualization itself are removed from the configuration panel.
4. Set other caching properties as needed.  
   {#enable-caching-local-data-instance__table_k5f_bng_2bc__entry__2}

   | Property | Description |
   |-|-|
   | Cache expiration time | How long the cache, once created, is retained before being updated in the cache refresh job. |
   | Invalidate cache | Use this setting with extra logic you create to invalidate the cache and fetch fresh data. For example, you can add a Button component to the page and script its event handler to invalidate the cache. |
   | Additional key | Enter a string that will contribute to generating the unique hash key for each data cache created on this data instance. Use a unique additional key value for each local data instance. |
   [ ]

   {#enable-caching-local-data-instance__table_k5f_bng_2bc}