User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Dashboard Parameters

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

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 documentation pages for each individual element type.

Example Usage

- dashboard: dashboard_name title: "desired dashboard title" description: "desired dashboard description" extends: name_of_dashboard_being_extended extension: required layout: tile | static | grid | newspaper rows: - elements: [element_name, element_name, …] height: N tile_size: N width: N refresh: N (seconds | minutes | hours | days) auto_run: true | false # DASHBOARD FILTER PARAMETERS filters: - name: filter_name title: "desired filter title" type: field_filter | number_filter | date_filter | string_filter model: model_name explore: explore_name field: view_name.field_name default_value: Looker filter expression allow_multiple_values: true | false required: true | false listens_to_filters: - filter_name field: view_name.field_name # EMBEDDED DASHBOARD PARAMETERS embed_style: background_color: "css_color" show_title: true | false title_color: "css_color" show_filters_bar: true | false tile_background_color: "css_color" tile_text_color: "css_color" # ELEMENTS PARAMETERS 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) Add 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.
refresh (for dashboard) Set the interval on which dashboard elements will automatically refresh.
auto_run Determine whether dashboards run automatically when initially opened or reloaded.
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.
default_value Set a default value for a filter, if desired.
allow_multiple_values Limit users to a single filter value.
required Require that users enter a filter value to run the dashboard.
model (for filters) Specify the model that contains the underlying field of a type: field_filter filter.
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.
listens_to_filters Narrow suggestions for dashboard filters of field_filter based on what the user enters for another dashboard filters of type: field_filter.
Embedded Dashboard Parameters
embed_style Start a section of LookML to define embedded dashboard customizations.
background_color Set a background color of an embedded dashboard.
show_title Specify whether the dashboard title is visible on an embedded dashboard.
title_color Set the color of the title of an embedded dashboard.
show_filters_bar Specify whether the filters bar is visible on an embedded dashboard.
tile_background_color Set the tile background color of an embedded dashboard.
tile_text_color Set the tile text color of an embedded dashboard.
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 on this documentation page.

title can also be used as part of any dashboard element. A representative example of its usage is provided on the documentation page for column chart elements.

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)

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

description can also be used as part of an Explore, as described on this documentation page.

description can also be used as part of a field, as described on this documentation page.

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:

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.

rows

For layout: grid dashboards, the rows parameter starts the section of LookML where you define which elements should go into which rows, as well as the height of each 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 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. The height and width parameters apply to all element types, and details about their usage appear on the documentation pages for each individual visualization type. For a representative example of how height and width work, see Column Chart Parameters for LookML Dashboards.

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. A representative example its usage is provided on the documentation page for column chart elements.

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

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. A representative example of its usage is provided on the documentation page for column chart elements.

The refresh parameter allows a dashboard to automatically reload 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 reloaded. 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 reloads 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. A representative example of its usage is provided on the documentation page for column chart elements.

filters can also be used as part of a measure, described on this documentation page.

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 set up to “listen” for that filter, using the listen parameter. 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 Column Chart Parameters for LookML Dashboards.

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 model: model_name explore: explore_name field: view_name.field_name default_value: Looker filter expression allow_multiple_values: true | false required: true | false listens_to_filters: - filter_name field: view_name.field_name

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. A representative example of its usage is provided on the documentation page for column chart elements.

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. The listen 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 Column Chart Parameters for LookML Dashboards.

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 on this documentation page.

title can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page for column chart elements.

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 on this documentation page.

type can also be used as part of a join, described on this documentation page.

type can also be used as part of a dimension, described on this documentation page.

type can also be used as part of a measure, described on this documentation page.

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

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

default_value

The default_value parameter allows you to specify a default value to use for a filter. This can be helpful by suggesting a reasonable starting point to users. 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"

You can also use filter expressions to create default values. The Looker Filter Expressions page describes this in more detail.

allow_multiple_values

The allow_multiple_values parameter allows you to limit users to a single filter value. When set to true, which is the default, users can select multiple values for the filter. When set to false, users are able to select only a single filter value. See this documentation page for more information.

For example:

filters: - name: Order ID title: Order ID type: field_filter allow_multiple_values: true required: false model: thelookstore explore: orders field: orders.id

required

The required parameter allows you to require that users provide a value for the filter in order to run the dashboard. By default, filters do not require values. If a filter that does not require a value and is left blank, the data simply isn’t restricted by the filter field. If a filter that does require a value and is left blank, the dashboard won’t run.

filters: - name: State title: State type: field_filter required: true

model

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

filters: - name: State title: State type: field_filter default_value: California model: thelookstore explore: users field: users.state

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 on this documentation page.

explore can also be used as part of a dashboard element. A representative example of its usage is provided on the documentation page for column chart elements.

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

listens_to_filters

For dashboard filters of type: field_filter, you can narrow suggestions for the filter based on what the user enters for another filter of type: field_filter. In the following example, the suggestions provided for the State filter will be based on the values from the Order ID filter. Whatever order IDs are selected will have an associated users.state value, and those values will be suggested values for the State filter. See this documentation page for more information.

filters: - name: State title: State type: field_filter model: thelookstore explore: users listens_to_filters: - Order ID field: users.state

embed_style

The embed_style parameter starts the section of LookML where you customize the appearance of an embedded dashboard. embed_style and its associated parameters are supported only on embedded dashboards and are ignored if the dashboard is not embedded.

After you make changes to embed_style, you must deploy your LookML to production in order to see your embed_style settings reflected in the embedded LookML dashboard.

For embedded dashboard attributes below that specify a color, the color value can be a hex string like #2ca6cd or a CSS named color string like mediumblue.

Embedded dashboard customizations have the following form:

embed_style: background_color: "css_color" show_title: true | false title_color: "css_color" show_filters_bar: true | false tile_background_color: "css_color" tile_text_color: "css_color"

background_color

Sets the color of the background of an embedded dashboard.

embed_style: background_color: "#ffffff"

show_title

Specifies whether the embedded dashboard title is visible to users.

embed_style: show_title: false

title_color

Sets the color of the title of an embedded dashboard.

embed_style: title_color: "#008000"

show_filters_bar

Specifies whether the embedded dashboard filters are visible to users.

This parameter affects only the cosmetic appearance of the dashboard, not a user’s ability to access data. Hiding the filters bar does NOT prevent users from changing filters by other means. For information on how to set up secure data access control policies, see the Access Control and Permission Management documentation page.

embed_style: show_filters_bar: true

tile_background_color

Sets the color of the background of all tiles on an embedded dashboard.

embed_style: tile_background_color: "lightyellow"

tile_text_color

Sets the color of text on all tiles on an embedded dashboard.

embed_style: tile_text_color: "crimson"

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 on this documentation page.

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]

Top