Dashboard Parameters

On this Page
Docs Menu

Dashboards can be created in one of two ways. User-defined dashboards are created via the Looker UI, and are described here. Dashboards can also be created using LookML and their overall settings modified as discussed on this page.

Starting in 4.0, you can use New LookML for data modeling. However, LookML dashboards continue to use the YAML-based old LookML language.

A dashboard has several settings that impact the entire dashboard, which are described here. It will also contain a group of data visualizations, which are called “elements”. The LookML for these elements is described on the Visualization LookML page.

Example Usage

- dashboard: dashboard_name title: 'desired dashboard title' description: 'desired dashboard description' layout: tile | static | grid rows: - elements: [element_name, element_name, …] height: N tile_size: N width: N show_applied_filters: true | false refresh: N (seconds | minutes | hours | days) auto_run: true | false filters: - name: filter_name title: 'desired filter title' type: field_filter | number_filter | date_filter | string_filter explore: explore_name field: view_name.field_name default_value: Looker filter expression elements: # One or more element declarations

Parameter Definitions

Parameter Name Description
dashboard Create a dashboard
title (for dashboard) Change the way a dashboard name appears to users
description (for dashboard) ADDED4.18Add a placeholder description to be used if the dashboard is converted to a user-defined dashboard
extends Base the LookML dashboard on another LookML dashboard
extension Require that the dashboard is extended by another dashboard
layout Define the way that the dashboard will place elements
rows Start a section of LookML to define the elements that should go into each row of a layout: grid dashboard
elements (for rows) Define the elements that should go into a row of a layout: grid dashboard
height (for rows) Define the height of a row for a layout: grid dashboard
tile_size Define the size of a tile for a layout: tile dashboard
width (for dashboard) Define the width of the dashboard for a layout: static dashboard
show_applied_filters Determine whether or not filters are shown near the title of each element
refresh (for dashboard) Set the interval on which dashboard elements will automatically refresh
auto_run Determine whether dashboards run automatically when initially opened or re-loaded
Filter Parameters
filters (for dashboard) Start a section of LookML to define dashboard filters
name (for filters) Create a filter
title (for filters) Change the way a filter name appears to users
type (for filters) Determine the type of filter to be used
explore (for filters) Specify the explore that contains the underlying field of a type: field_filter filter
field Specify the underlying field of a type: field_filter filter
default_value Set a default value for a filter, if desired
Element Parameters
elements (for dashboard) Start a section of LookML to define dashboard elements

dashboard

The dashboard parameter declares a new dashboard and specifies a name for the dashboard. It is typically best practice to place each LookML dashboard in its own LookML file, but it is possible to declare multiple dashboards in a single file.

- dashboard: sales_overview

In order to display anything, a dashboard requires at least one element to be added via the elements parameter.

title (for dashboard)

This section refers to the title parameter that is part of a dashboard
title can also be used as part of a dashboard filter, described here
title can also be used as part of a dashboard element, described here

The title parameter lets you change how a dashboard name will appear to users in Spaces, and at the top of the dashboard. If not specified, the title defaults to the name of the dashboard.

Consider this example:

- dashboard: sales_overview title: '1) Sales Overview'

If you did this, instead of the dashboard appearing as Sales Overview, it would appear as 1) Sales Overview.

description (for dashboard)ADDED4.18

This section refers to the description parameter that is part of a dashboard.

description can also be used as part of an explore, described here.
description can also be used as part of a dimension, dimension group, measure, or filter as described here.

The description parameter lets you add a description to the LookML dashboard. This description is displayed only if the dashboard is converted to a user-defined dashboard. If a user-defined dashboard has a description, it is displayed under the dashboard title in the lists of dashboards on the Browse tab. If not specified, the list displays only the dashboard title.

extends

As described on this page the extends parameter enables you to base one LookML dashboard on another LookML dashboard, possibly adding or overriding some settings. The extends parameter accepts the name of another LookML dashboard.

extension

As described on this page, the extension parameter indicates that the dashboard must be extended by another dashboard. This dashboard is never visible to other users but can be used as a template to create other dashboards which are visible to other users. The extension parameter only accepts the value ‘required’. If the extension parameter is not included, extension is not required for the dashboard.

layout

The layout parameter sets the layout method that Looker will use when positioning dashboard elements. It accepts the following values:

  • grid - Dashboard elements will appear with dynamic widths, based on a set of rows you define with the rows, elements, and height parameters.

  • newspaper - Dashboard elements will appear in a 12 column grid with fixed height rows. Elements are configurable along this grid, specified by row, col, width and height. This is the layout option used when converting a user-defined dashboard to a LookML dashboard.

  • static - Dashboard elements will appear in the order they are listed in the LookML file. Each dashboard element must be positioned manually by using the top and left parameter. Note that when converting a user-defined dashboard to a LookML dashboard, a “newspaper” layout is converted using layout: static and then defining the top and left values for each tile.

  • tile - Dashboard elements will appear in the order they are listed in the LookML file. The width of the dashboard is dynamic, and is based on the width of the browser. The dashboard elements will dynamically position themselves within the browser to fill the available space.

rows

For layout: grid dashboards, the rows parameter starts the section of LookML where you define which elements should go into which rows, and if desired, the height of that row. Within each row, each element has the same width. If you do not list an element in this section it will not appear on the dashboard.

- dashboard: sales_overview layout: grid rows: - elements: [element_name, element_name, …] height: 200 - elements: [element_name, element_name, …] height: 300

elements

The elements parameter takes a list of dashboard element names, separated by commas. Each elements declaration creates a new row in the dashboard. The elements that are placed into a row will all have the same width. So, if you place 2 elements in a row, they will each take 50% of the available space. If you place 4 elements into a row, they will each take 25% of the available space, and so on.

height

The height parameter is optional, and defines the height of a row in pixels. The default value is 300.

tile_size

For layout: tile and layout: static dashboards, the unit that is used to size and position elements is tile size. You define tile_size in pixels, and the default value is 160. For example:

- dashboard: sales_overview layout: tile tile_size: 100

In this situation a dashboard element with height 5 and width 3 will be 500 pixels high, and 300 pixels wide. See the dashboard element reference for more information about setting the height and width.

width

This section refers to the width parameter that is part of a dashboard
width can also be used as part of a dashboard element, described here

For layout: static dashboards, the width parameter defines the total dashboard width that you plan to use in pixels. The width parameter will not restrict the dashboard to a certain size if you define too large of an element, or too many elements in a row. Rather, the width setting helps to keep the dashboard centered on the screen. If you do not set a width, the default is 1200.

- dashboard: sales_overview layout: static width: 800

show_applied_filters

The show_applied_filters parameter allows you to prevent dashboard filter information from showing up near the title of each dashboard element. The filter information can be hidden with:

- dashboard: sales_overview show_applied_filters: false

The default behavior is true.

refresh

This section refers to the refresh parameter that is part of a dashboard
refresh can also be used as part of a dashboard element, described here

The refresh parameter allows a dashboard to automatically re-load on some periodic basis, thereby retrieving fresh data. This is often helpful in settings where a dashboard is constantly displayed, such as on an office TV. Note that the dashboard must be open in a browser window for this parameter to have an effect. This setting does not run in the background to “pre-warm” the dashboard cache.

The refresh rate can be any number (without decimals) of seconds, minutes, hours or days. For example:

- dashboard: sales_overview refresh: 2 hours

Use caution when setting short refresh intervals. Since dashboards can contain many queries, some of which may be resource intensive, certain dashboards may strain your database more than desired.

auto_run

The auto_run parameter determines whether or not a dashboard will run when it is initially opened or re-loaded. The default value is true. When set to false, users will need to press a Run button to load the dashboard. For example, a dashboard like this will automatically run when opened:

- dashboard: sales_overview auto_run: true

Regardless of the auto_run setting, users must always click a Run button after changing filter values. This helps to prevent unwanted re-loads when a user pauses during a filter change, or wants to change multiple filters at the same time.

filters

This section refers to the filters parameter that is part of a dashboard
filters can also be used as part of a dashboard element, described here
filters can also be used as part of a measure, described here

The filters parameter starts the section of LookML where you define dashboard filters. Filters appear at the top of the dashboard and allow users to change the data behind dashboard elements. In order for a filter to impact an element, the element must be setup to “listen” for that filter, using the listen parameter. When filters are applied to an element in this manner, it’s important for the filter type to match the dimension or measure type that is listening for the filter (see Creating a LookML Dashboard for more details). Filters have the form:

filters: - name: filter_name title: 'desired filter title' type: field_filter | number_filter | date_filter | string_filter explore: explore_name field: view_name.field_name default_value: Looker filter expression

name

This section refers to the name parameter that is part of a dashboard filter
name can also be used as part of a dashboard element, described here

Each name declaration creates a new dashboard filter, and assigns a name to it. The name will be referenced in the listen parameter of elements that should be impacted by the filter.

filters: - name: order_date

title (for filters)

This section refers to the title parameter that is part of a dashboard filter
title can also be used as part of a dashboard, described here
title can also be used as part of a dashboard element, described here

The title parameter allows you to change how a filter name will appear to users at the top of a dashboard. If not specified, the title defaults to the name of the filter.

Consider this example:

filters: - name: order_date title: 'Order Date(s)'

If you did this, instead of the filter appearing as Order Date, it would appear as Order Date(s).

type

This section refers to the type parameter that is part of a dashboard filter
type can also be used as part of a dashboard element, described here
type can also be used as part of a join, described here
type can also be used as part of a dimension, described here
type can also be used as part of a measure, described here

The type parameter specifies the type of input that will be placed in the filter. While any type of input (such as a date) could be written into the type: string_filter filter, being more specific provides a more tailored filter widget to the user. The 4 types of filter are:

  • field_filter - Should generally be your default choice, when you can specify an underlying dimension or measure from which to autosuggest
  • number_filter - Allows the user to input a number / integer value or expression
  • date_filter - Allows the user to input a date value or expression
  • string_filter - Allows the user to input freeform text

field_filter

Suggests options to choose from, changes its presentation to users based on the underlying field you specify.

This should be your go-to filter type in situations where you want to make suggestions to users as they interact with the filter. The dimension from which suggestions will be pulled is defined by using the explore and field parameters.

Please note that suggestions may not work if the field comes from a derived table, if sql_always_where is used on the explore, or if the field is a measure.

filters: - name: order_date type: field_filter explore: orders field: orders.order_date # must be of the form view_name.dimension_name

number_filter

Does not make suggestions, allows user to enter an integer / number value or expression.

filters: - name: order_value type: number_filter

date_filter

Does not make suggestions, allows user to enter a date value or expression.

filters: - name: order_date type: date_filter

string_filter

Does not make suggestions, allows user to enter freeform text.

filters: - name: customer_name type: string_filter

filter DEPRECATED3.10

Replaced by string_filter, does not make suggestions, allows user to enter freeform text.

filters: - name: customer_name type: filter

suggest_filter DEPRECATED3.14

Replaced by field_filter, suggests options to choose from based on a dimension you specify.

filters: - name: order_date type: suggest_filter explore: orders dimension: orders.order_date # must be of the form view_name.dimension_name

explore

This section refers to the explore parameter that is part of a dashboard filter
explore can also be used as part of a model, described here
explore can also be used as part of a dashboard element, described here

For dashboard filters of type: field_filter, you need to define a field from which the filter will pull suggestions. The explore parameter specifies which explore contains the field you want to use.

filters: - name: order_date type: field_filter explore: orders field: orders.order_date

field

For dashboard filters of type: field_filter, you need to define a field from which the filter will pull suggestions. The field parameter specifies which field you want to use. It is important to use the fully scoped field name. In other words, use view_name.field_name, not just field_name.

filters: - name: order_date type: field_filter explore: orders field: orders.order_date

default_value

The default_value parameter allows you to specify a default value to use for a filter. This can be helpful to suggest a reasonable starting point to users. You should make sure to match the default value with the type of filter being used. For example:

filters: - name: order_value type: number_filter default_value: '50 to 100' - name: order_date type: date_filter default_value: 'last 30 days' - name: customer_name type: string_filter default_value: 'John Doe'

The types of values that you can write for a default value are described in more detail on the Looker Filter Expressions page.

elements

This section refers to the elements parameter that is part of a dashboard
elements can also be used as part of a dashboard row, described here

The elements parameter starts the section of LookML where you define the elements that will make up a dashboard. There are many, many parameters that can define the appearance of a dashboard element. They are described in more detail on the Visualization LookML page.

- dashboard: sales_overview layout: tile elements: - name: order_count type: single_value model: acme_company explore: orders measures: [orders.count]
Still have questions?
Go to Discourse - or - Email Support
Top