home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Looker documentation will be moving to cloud.google.com in mid-2022!
All the information you rely on will be migrated and all docs.looker.com URLs will be redirected to the appropriate page.
Building LookML dashboards

LookML dashboards are created by LookML developers and stored as version-controlled files. By default, they appear in the LookML dashboards folder of your Looker instance. To compare and contrast LookML dashboards and user-defined dashboards, see the Comparing user-defined and LookML dashboards documentation page.

To create a LookML dashboard, you must have:

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

Creating a LookML dashboard file

The steps for building a LookML dashboard are:

  1. In the Develop menu, turn on Development Mode and navigate to your project. If your admin has enabled the Enhanced Navigation Labs feature, the Development Mode toggle is located in the new enhanced left navigation panel.
  2. Click + at the top of the file browser panel in the Looker IDE or click a folder’s three-dot menu to create the file inside the folder, and click Create Dashboard.

  3. Name the dashboard file and select Create.

New LookML dashboard files default to the new dashboard experience by automatically setting the preferred_viewer dashboard parameter to dashboards-next. To render a new LookML dashboard as a legacy dashboard, set preferred_viewer to dashboards instead.

When you’re creating a dashboard, keep in mind best practices for dashboard construction. Find information and recommendations about building performant dashboards in the Considerations when building performant Looker dashboards Help Center article.

LookML dashboards folder

By default, LookML dashboards are saved in the LookML dashboards folder, which is located in the All folders top-level folder. The LookML dashboards folder is unique from other folders in a few ways:

Moving LookML dashboards outside of the LookML dashboards folder

If you have the develop permission on any model, you can move a LookML dashboard into any folder for which you have the Manage Access, Edit folder access level.

If you are in Development Mode, you cannot move LookML dashboards outside of the LookML dashboards folder. You can instead use the Import option to copy the LookML dashboard as a user-defined dashboard to another folder.

A folder that contains both user-defined dashboards and LookML dashboards will display the LookML dashboards in a LookML Dashboard section. From the LookML 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 you change the value of a LookML dashboard’s dashboard parameter, the LookML dashboard will automatically move back into the LookML dashboards folder.

Viewing the LookML for an existing LookML dashboard

If you have the see_lookml permission, you can navigate to the dashboard LookML for an existing LookML dashboard by selecting Go to LookML from a dashboard’s three-dot menu or Go to Dashboard LookML from a legacy dashboard’s gear menu:

When you select Go to Dashboard LookML, Looker navigates to the dashboard file in which the LookML dashboard is defined.

Manually building or modifying a LookML dashboard

Edit the dashboard file header with a name, a title, and your configuration preferences:

- dashboard: business_pulse preferred_viewer: dashboards-next title: Business Pulse layout: grid elements:

See the Dashboard parameters documentation page for a complete listing of parameters that impact the entire dashboard. For more information on parameters that impact specific dashboard elements, see the Dashboard element parameters documentation page.

Creating a LookML copy of a user-defined dashboard

You can copy the LookML of an entire user-defined dashboard, which lets you use the dashboard across Looker instances and across models. Having the dashboard in LookML also lets you use version control for the dashboard, as with other LookML files.

The LookML copy of the dashboard defaults to newspaper layout. You can modify the layout of the LookML dashboard by modifying the layout dashboard parameter.

To create a LookML dashboard from a user-defined dashboard:

  1. Click Browse and navigate to your user-defined dashboard. If your admin has enabled the Enhanced Navigation Labs feature, you can use the new enhanced left navigation panel to navigate to a dashboard.
  2. Select Get LookML from the three-dot menu and choose the Dashboard tab.

  3. In the dashboard LookML window, click Copy to Clipboard.

  4. Within your LookML project, click + at the top of the file browser panel in the Looker IDE or click a folder’s three-dot menu to create the file inside the folder, and click Create Dashboard.

  5. Name the dashboard file and select Create.

  6. Delete the initial contents of the new LookML dashboard file.

  7. Paste the copied LookML from your clipboard into the file and click Save Changes.

If your new dashboard isn’t already included in your model file, be sure to include it.

Adding a visualization to an existing LookML dashboard

The easiest way to add a tile to an existing LookML dashboard is to use the Explore 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’s gear menu.
  2. Select Get LookML to expose the LookML.
  3. With Dashboard selected in the Get LookML modal, select all the LookML and copy it.

From here, paste the LookML into your dashboard LookML file. Here are some tips for editing the dashboard LookML file:

Adding filters

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

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

Filters that you hard-code into the dashboard elements, which users cannot change, usually get created automatically in the copy LookML step for a visualization or for a dashboard. In a LookML dashboard, those filters look like this:

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

If you decide you want filters that a user can change, the first step is to create the filters that they interact with. To do so, add a filters section to your dashboard file, which will look something like this:

- dashboard: dashboard_name # possibly some other dashboard parameters here 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 various options and parameters for these filters are described in more detail in the Dashboard LookML reference. One of the most important things to keep in mind is what type of input you’re expecting from your users. You can assign a type that will accept numbers, dates, or strings. Or you can associate your filter with an underlying LookML field, in which case Looker will automatically select the correct type of input and, if the underlying LookML field is of type:string, provide filter suggestions to your users.

As described in the Dashboard LookML reference, only filters with type: field filter use the explore and field parameters. If you include the explore and field parameters with any other filter type, you’ll get LookML validation errors.

At this point in the process the filters don’t do anything yet!

Once you’ve created your filters, you’ll need to apply them to the proper elements using the listen parameter. The idea is that the element “listens” to one or more filters for user input, then adjusts accordingly. This parameter applies to all element types besides type: text, and details about its usage appear on the documentation pages for each individual visualization type. For a representative example of how listen works, see Area chart parameters for LookML dashboards.

For example, you may have an element that looks like this:

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

You can see that this element already has a filters parameter that restricts the element to approved orders. This can’t be changed by the user.

Suppose you wanted the user to be able to restrict this element to a certain date range, or a certain category, based on the dashboard filters you created. You would need to add a listen parameter like this:

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

If you don’t want users to be able to adjust the date or category, simply don’t add the listen parameter. You only have to add a listen to elements that you want the user to be able to adjust.

You’ll see that the listen syntax works by first writing the name of the filter you created, then writing the name of the field that you want to apply the user input to.

Keep in mind that a dashboard filter can be applied to any field (of the same data type) in any given element. For example, one element can apply a user’s input to the order created date, while another applies it to the order ship date:

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

Including the file in a model

For your dashboard to be visible in the LookML dashboards folder, it must be added using an include statement in the model file on which the dashboard is based.

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

include: "*.dashboard.lookml"

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

include: "my_dashboard.dashboard.lookml"

Saving and previewing the file

Save the file, preview the dashboard, and commit your changes via Git to put the dashboard into Production Mode when you are ready.

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 the Reusing 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 using aggregate awareness. With aggregate awareness, developers can create aggregate tables under LookML explore parameters, which can optimize queries for one or more tiles in a dashboard.

Once you have created a LookML dashboard and are viewing it, you can use the Get Aggregate Table LookML option in the dashboard gear menu, which is visible if you have the see_lookml permission:

For more information, see the aggregate_table parameter documentation page.

Find other information and recommendations about building performant dashboards in the Considerations when building performant Looker dashboards Help Center article.

Top