LookML dashboards are created by LookML developers and stored as version-controlled files. By default, they appear in theLookML dashboards folder of your Looker instance.

To compare and contrast LookML dashboards and user-defined dashboards, see theComparing user-defined and LookML dashboards documentation page.

To create a LookML dashboard, you must have the following Looker permissions:

• see_lookml_dashboards
• develop

Additionally, you must haveaccess to the LookML models for any data you want to use in the dashboard.

Creating a LookML dashboard file

To build a LookML dashboard, begin by creating a dashboard file, which has theextension.dashboard.lookml (although the.lookml portion of the extension is silent within the IDE). The steps to do so are as follows:

1. Turn onDevelopment Mode.
2. In theDevelop menu, navigate to your project.
3. Select theAdd file or folder plus icon at the top of the file browser panel in the Looker IDE to create a LookML dashboard file outside of existing project folders. Or, click a folder's three-dotFolder Options menu tocreate the file inside the folder. ClickCreate Dashboard to create the dashboard file.

1. ACreate File window will appear. Within the window, name the dashboard file in the write-in field and select theCreate button.

Editing LookML dashboard files

When you create a LookML dashboard file, Looker pre-populates the file with several basicdashboard parameters, which implement settings for the entire dashboard. It also pre-populates the file with several sampledashboard element parameters, which are grouped under theelements dashboard parameter, and which define the function and appearance of dashboard tiles, text, and buttons. A newly created.dashboard.lookml file contains dashboard LookML similar to this:

- dashboard: order_analysis  title: Order Analysis  layout: newspaper  preferred_viewer: dashboards-next  tile_size: 100  filters:  elements:    - name: hello_world      type: looker_column

You can edit the dashboard file within the IDE as long as you are in Development Mode.

You have several options for building your dashboard:

• Manual creation: You can manually build a dashboard by using dashboard parameters and dashboard element parameters.
• Copy a user-defined dashboard: You can create a copy of a user-defined dashboard by deleting the pre-populated dashboard LookML from the file,copying the dashboard LookML from a user-defined dashboard, and pasting it into your dashboard file.
• Copy dashboard LookML of elements: You can copy the dashboard LookML from anExplore or aLook and paste it into your dashboard file.

When you're creating a dashboard, keep in mind best practices for dashboard construction. Find information and recommendations about building performant dashboards in theConsiderations when building performant Looker dashboards Best Practices page.

Adding a visualization to an existing LookML dashboard

The easiest way to add a visualization to an existing LookML dashboard is to use theExplore page to build a query that you want to turn into a dashboard element:

1. Once you have created the query and visualization that you want to add to a dashboard, click the Explore'sExplore actions gear menu.

2. SelectGet LookML to expose the LookML.

   

3. AGet LookML window appears. WithDashboard selected in the window, select all the LookML and copy it.

   

From here,paste the LookML into your dashboard LookML file. When editing the dashboard LookML file, be sure to:

• Verify that you are inDevelopment Mode so that you can edit the dashboard file.
• Paste the LookML under the dashboard'selements parameter.
• Use the correct indentation when pasting LookML into the dashboard file. If possible, match the indentation to existing elements already in the dashboard file.

You can adjust the LookML parameters if desired, using the parameters described on thedocumentation pages for each individual element type.

Adding filters

Once you have dashboard elements saved in your dashboard file, you may want to add filters, which let dashboard viewers filter some or all elements on a dashboard. Filters can be useful for many possible reasons, for example:

• Adjusting the time period shown
• Adjusting the specific product category, customer type, etc being shown
• Providing a "lookup" type capability for a client or customer

Be sure to build the type of filter you want. The two types are:

• Filters that you hard-code into the dashboard elements, which dashboard viewers cannot change
• Dashboard filters, which dashboard viewerscan change

Filters hard-coded into dashboard elements

Filters that you hard-code into the dashboard elements, which users cannot change, usually get created automatically in the copy LookML stepfor a visualization orfor a dashboard. In a LookML dashboard, those filters use thefilters dashboard element parameter and look like this:

- name: element_name  # lots of other element parameters here  filters:    dimension_or_measure_name: 'looker filter expression'

Dashboard filters

Dashboard filters let viewers interactively refine the data that is shown in dashboard elements. To create a dashboard filter, follow these steps:

1. Create the dashboard filter by using thefilters parameter within your LookML dashboard file.
2. Apply the filter to individual dashboard elements by using thelisten parameter.

Creating a dashboard filter

Thefilters parameter lets you createvarious types of interactive filters for your dashboard.

To create a dashboard filter that users can interact with, add afilters parameter to your dashboard file. For example, the following sample code creates a LookML dashboard that has the filtersdate andcategory_name:

- dashboard: dashboard_name  title: Dashboard Title  layout: newspaper  filters:  - name: date    title: 'Date Range'    type: date_filter    default_value: 30 days  - name: category_name    type: field_filter    model: ecommerce    explore: product    field: category.name

The code in the previous example creates the following filters:

• date: Adate filter that lets users select a date range. The default value is set to the last 30 days.
• category_name: Afield filter that lets users filter by product category. This filter dynamically generates options that are based on thecategory.name field within the specified LookML model (ecommerce) and Explore (product).

Applying a dashboard filter to dashboard elements

Once you've created a dashboard filter, you can apply that filter to individual dashboard elements by using thelisten parameter. Using thelisten parameter in this way allows the linked elements to be dynamically updated based on the user's selection in the filter.

For example, consider the following sample LookML code for an area chart element:

- name: approved_orders_by_day  type: looker_area  model: ecommerce  explore: orders  dimensions: [orders.created_date]  measures: [orders.count]  filters:    orders.status: 'approved'

Theapproved_orders_by_day chart displays the count of approved orders by day, as the query is based on theorders_created_date dimension and theorders.count measure and has a filter applied,orders.status: 'approved'. This filter is fixed within the element and cannot be modified by dashboard viewers.

To let users filter theapproved_orders_by_day chart by usingthedate filter and thecategory_name filter from the previous example, add thelisten parameter to the dashboard element.

- name: approved_orders_by_day  type: looker_area  model: ecommerce  explore: orders  dimensions: [orders.created_date]  measures: [orders.count]  filters:    orders.status: 'approved'  listen:    category_name: category.name    date: orders.created_date

When a dashboard viewer interacts with thecategory_name filter or thedate filter, theapproved_orders_by_day chart will be automatically updated to reflect the filtered results.

Thelisten parameter uses the syntaxfilter_name: field_name. In the previous example, thecategory_name anddate are the names of filters, andcategory.name andorders.created_date are the fields that will be used to let dashboard viewers provide input to the filter.

A dashboard filter can be applied toany field (of the same data type) in any given element. For example, one element can apply a user's input to the ordercreated date (date: orders.created_date), while another applies it to the ordership date (date: orders.ship_date):

- name: element_one  # lots of other element parameters here  listen:    date: orders.created_date- name: element_two  # lots of other element parameters here  listen:    date: orders.ship_date

Including the dashboard file in a model

For your dashboard to be visible to preview in Development Mode or visible in production, it must be included in the model file on which the dashboard is based by using aninclude statement.

A common practice is to include all LookML dashboards in a model by using a wildcard:

include: "*.dashboard.lookml"

or, if your LookML dashboards appear within a folder in the IDE, use the path to their location

 include: "/path/*.dashboard.lookml"

You can also include a specific dashboard by specifying its filename:

include: "my_dashboard.dashboard.lookml"

Saving, previewing, and publishing the LookML dashboard

To preview the dashboard:

1. Save the.dashboard.lookml file, by clicking theSave Changes button at the top right corner of the file.
2. Include the dashboard in the relevant model file and save the changes to that file.
3. In the.dashboard.lookml file you wish to preview, click the downward arrowSee file actions icon and selectView Dashboard.

You can make further changes to your.dashboard.lookml file, save them, and preview the dashboard again.

Once you are happy with your dashboard, you can publish it to production, which allows other users with the correct permissions to see it. The method for publishing the dashboard is the same as publishing other changes to LookML on your instance, and depends on theversion control settings for your Looker instance.

LookML dashboards folder

Once published, LookML dashboards are saved in theLookML dashboards folder by default. TheLookML dashboards folder is located in theFolders folder in the left navigation. TheLookML dashboards folder is unique from other folders in a few ways:

• You mustinclude a LookML dashboard in at least one model file for it to appear in theLookML dashboards folder.
• To see theLookML dashboards folder, users must have thesee_lookml_dashboards permission.
• To see dashboards within theLookML dashboards folder, users must haveaccess to the LookML model that includes the dashboard.
• To see any given tile within a LookML dashboard, dashboard viewers must haveaccess to the LookML model that the tile is based on.
• To edit a dashboard in theLookML dashboards folder, you must have thedevelop permission on the model that includes the LookML dashboard.
• ToExplore from Here on any given tile within a dashboard, dashboard viewers must have theexplore permission for the model that tile is based on.
• You cannot create a folder inside theLookML dashboards folder.
• InProduction Mode, theLookML dashboards folder's list is paginated (30 dashboards per page). In Development Mode, all LookML dashboards are on a single page.
• Each LookML dashboard is sorted in theLookML dashboards folder according to the LookML dashboard name that is defined in the LookML dashboard code, instead of the LookML dashboard title. As a result, the dashboards may not appear to be sorted alphabetically by title.

Moving LookML dashboards outside of the LookML dashboards folder

If you have thesee_lookml_dashboards anddevelopLooker permissions as well as access to the LookML model a LookML dashboard is included in, you can move a LookML dashboard into any folder for which you have theManage Access, Edit folder access level.

There are two ways to move the dashboard:

• From theLookML dashboards folder, select the dashboard to move, click theMove button at the top of the dashboards section, and select the folder into which you wish to move the dashboard. See theOrganizing and managing content documentation page for more information.
• From theLookML dashboards folder, click the three-dot menu for the dashboard, selectMove from the menu, and select the folder into which you wish to move the dashboard.

If you're in Development Mode, you can't move LookML dashboards outside of theLookML dashboards folder. You can instead use theImport option tocopy the LookML dashboard as a user-defined dashboard to another folder.

A folder that contains both user-defined dashboards and LookML dashboards displays the LookML dashboards in aLookML Dashboard section. From theLookML Dashboard section, you can move a LookML dashboard to another folder or pin a LookML dashboard to a board. However, unlike user-defined dashboards, LookML dashboards cannot be renamed or moved to the trash from a folder.

If the value of a LookML dashboard'sdashboard parameter is changed, the LookML dashboard will automatically move back into theLookML dashboards folder.

Viewing the LookML for an existing LookML dashboard

If you have thesee_lookml permission, you can navigate to the dashboard LookML for an existing LookML dashboard by selectingGo to LookML from a dashboard's three-dotDashboard actions menu:

When you selectGo to LookML, Looker navigates to the dashboard file in which the LookML dashboard is defined.

Extending a LookML dashboard

Once you've created a LookML dashboard, you can extend the dashboard. This lets you create a second dashboard based on the original one, possibly adding or overriding some settings. Then if you change the first dashboard, the second one inherits those changes automatically (unless overridden in the second dashboard). See theReusing code with extends documentation page for more information.

Improving dashboard performance using aggregate awareness

LookML developers may be able to improve LookML dashboard performance by usingaggregate awareness. With aggregate awareness, developers can createaggregate tables under LookMLexplore parameters, which can optimize queries for one or more tiles in a dashboard.

Once you have created and are viewing a LookML dashboard, you can use theGet aggregate table LookML option in the three-dotDashboard actions menu, which is visible if you have thesee_lookml permission.

For more information, see theaggregate_table parameter documentation page.