This page demonstrates how to add and customize a LookML dashboard element oftype: looker_donut_multiples with LookML dashboard parameters in adashboard.lkml file.

For information about building a donut multiples chart through the Looker UI, see theDonut multiples chart options documentation page.

Example usage

## BASIC PARAMETERSname: element_nametitle: 'Element Title'type: looker_donut_multiplesheight: Nwidth: Ntop: Nleft: Nrow: Ncol: Nrefresh: N (seconds | minutes | hours | days)note:  text: 'note text'  state: collapsed | expanded  display: above | below | hover## QUERY PARAMETERSmodel: model_nameexplore: explore_namedimensions: [view_name.field_name, view_name.field_name, …]measures: [view_name.field_name, view_name.field_name, …]sorts: [view_name.field_name asc | desc, view_name.field_name, …]pivots: [view_name.field_name, view_name.field_name, …]limit: Ncolumn_limit: Nfilters:  view_name.field_name: 'Looker filter expression' | 'filter value'listen:  dashboard_filter_name: dimension_or_measure_namequery_timezone: 'specific timezone' | user_timezonemerged_queries:- 'primary query definition'- 'next source query definition'  join_fields:  - field_name: view_name.field_name    source_field_name: view_name.field_name## PLOT PARAMETERSshow_value_labels: true | falsefont_size: Ncharts_across: Nhide_legend: true | falsehidden_fields: [view_name.field_name, view_name.field_name, …]## SERIES PARAMETERScolors: [css_color, css_color, …]series_colors:  series_name: css_color  # Possibly more series color assignmentsseries_labels:  'Series Name': desired series label  # Possibly more series label assignments

Parameter definitions

Basic parameters

When defining a LookML dashboard element, you must specify values for at least thename andtype basic parameters. Other basic parameters liketitle,height, andwidth affect the appearance and position of an element on a dashboard.

name

This section refers to thename parameter that is part of adashboard element.

name can also be used as part of a dashboard filter, described on theDashboard parameters documentation page.

Eachname declaration creates a new dashboard element and assigns it a name. Element names must be unique. Names are sometimes referenced in theelements parameter when you're usinglayout: grid dashboards.

- name: orders_by_date

title

This section refers to thetitle parameter that is part of adashboard element.

title can also be used as part of a dashboard, described on theDashboard parameters documentation page.

title can also be used as part of a dashboard filter, described on theDashboard parameters documentation page.

Thetitle parameter lets you change how an element's name will appear to users. If unspecified, the title defaults to the elementname.

Consider this example:

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

If you used this format, instead of the element appearing asSales Overview, it would appear as1) Sales Overview.

type

This section refers to thetype parameter that is part of adashboard element.

type can also be used as part of a dashboard filter, described on theDashboard parameters documentation page.

type can also be used as part of a join, described on thetype (for joins) parameter documentation page.

type can also be used as part of a dimension, described on theDimension, filter, and parameter types documentation page.

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

Thetype parameter determines the type of visualization to be used in the element.

- name: element_name  type: text | looker_grid | table | single_value | looker_single_record |        looker_column | looker_bar | looker_scatter | looker_line | looker_area |        looker_pie | looker_donut_multiples | looker_funnel | looker_timeline |        looker_map | looker_google_map | looker_geo_coordinates | looker_geo_choropleth | looker_waterfall | looker_wordcloud | looker_boxplot

See thetype (for LookML dashboards) documentation page for an overview of the different types of LookML dashboard elements.

height

This section refers to theheight parameter that is part of adashboard element.

height can also be used as part of a dashboard row, described on theDashboard parameters documentation page.

For dashboards withtile orstatic layouts

Theheight parameter defines the height of an element, in units oftile_size (which is defined in pixels), forlayout: tile andlayout: static dashboards.

For example, the following code specifiestile_size: 100 andheight: 4, making theorders_by_date element 400 pixels in height.

- dashboard: sales_overview  tile_size: 100  ...  elements:  - name: orders_by_date    height: 4    ...

For dashboards withnewspaper layout

Theheight parameter defines the height of an element, in units ofrow, forlayout: newspaper dashboards.

A dashboard with newspaper layout defaults to an element height of 6 rows, or about 300 pixels. The minimum height is 1 row for dashboards with apreferred viewer parameter set todashboards-next. The minimum height is 2 rows for dashboards with apreferred viewer parameter set todashboards.

For example, the following code sets an element to be 12 rows tall, or twice as tall as other elements that are set to the default:

- dashboard: sales_overview  layout: newspaper  ...  elements:  - name: orders_by_date    height: 12    ...

width

This section refers to thewidth parameter that is part of adashboard element.

width can also be used as part of a dashboard, described on theDashboard parameters documentation page.

Thewidth parameter defines the width of an element, in units oftile_size, forlayout: tile andlayout: static dashboards.

For example, the following code specifiestile_size: 100 andwidth: 4, making theorders_by_date element 400 pixels in width.

- dashboard: sales_overview  tile_size: 100  ...  elements:  - name: orders_by_date    width: 4    ...

Thewidth parameter defines the width of an element, in units of columns, forlayout: newspaper dashboards.

A dashboard with newspaper layout defaults to a width of 24 columns.

For example, the following code sets the element to half the width of the dashboard:

- dashboard: sales_overview  layout: newspaper  ...  elements:  - name: orders_by_date    width: 12    ...

top

Thetop parameter defines the top-to-bottom position of an element, in units oftile_size, forlayout: static dashboards.

For example, the following code specifiestile_size: 100 andtop: 4, positioning the top edge of theorders_by_date element 400 pixels from the top of the dashboard.

- dashboard: sales_overview  tile_size: 100  ...  elements:  - name: orders_by_date    top: 4    ...

left

Theleft parameter defines the left-to-right position of an element, in units oftile_size, forlayout: static dashboards.

For example, the following code specifiestile_size: 100 andleft: 4, positioning the left edge of theorders_by_date element 400 pixels from the left side of the dashboard.

- dashboard: sales_overview  tile_size: 100  ...  elements:  - name: orders_by_date    left: 4    ...

row

Forlayout: newspaper dashboards, therow parameter defines the row that the top edge of an element is placed on.

A dashboard begins with row 0 at the top of the dashboard. A dashboard with newspaper layout defaults to an element height of 6 rows, meaning the dashboard elements at the top of a dashboard (row: 0) would default to taking up rows 0-5.

Each row is 50 pixels tall, which means the default element height of 6 rows is 300 pixels.

For example, the following code sets an element to be set on the second row of elements in the dashboard, assuming elements are set at the default height:

- dashboard: sales_overview  layout: newspaper  ...  elements:  - name: orders_by_date    row: 6    ...

col

Forlayout: newspaper dashboards, thecol parameter defines the column that the left edge of the element is placed on.

Dashboards are divided into 24 columns. A dashboard begins with column 0 at the left of the dashboard. A dashboard with newspaper layout defaults to an element width of 8 columns, meaning the dashboard elements at the left of a dashboard (col: 0) would default to taking up columns 0-7.

For example, the following code sets an element to be set in the third column of elements in the dashboard:

- dashboard: sales_overview  layout: newspaper  ...  elements:  - name: orders_by_date    col: 16    ...

refresh

This section refers to therefresh parameter that is part of adashboard element.

refresh can also be used as part of a dashboard, described on theDashboard parameters documentation page.

Therefresh parameter allows an element to reload automatically 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:

- name: orders_by_date  refresh: 2 hours

Use caution when setting short refresh intervals. If the query behind the element is resource-intensive, certain elements may strain your database more than desired.

note

You can add descriptive notes to elements like this:

- name: element_name  note:    text: 'note text'    state: collapsed | expanded    display: above | below | hover

note has the subparameterstext,state, anddisplay.

text

Thetext subparameter specifies the text displayed in the note. The text can belocalized.

state

Thestate subparameter determines whether the note will becollapsed orexpanded if it is too big to fit on a single row within the element's width. If you choosecollapsed and the note is too long, the note will end in a clickable ellipsis (...) that can be used to read the full note.

display

Thedisplay subparameter determines where the note is displayed on an element.above places the note at the top of an element,below places it at the bottom of an element, andhover requires the user to hover their mouse over the element to see the note.

Query parameters

When defining a LookML dashboard element oftype: looker_donut_multiples, you must specify values for at least themodel andexplore query parameters. Your query must also include at least one value each for thedimensions,measures, andpivots parameters. You can also use the other query parameters to control the way data is displayed in a dashboard element.

model

Themodel parameter defines the model to use for the element query. If unspecified, it will default to the model where the dashboard resides.

- name: orders_by_date  model: ecommerce

Themodel parameter acceptsLookML constants. You can define a constant in themanifest file for your project, then use the syntax"@{constant_name}" to set the constant as the value formodel. Using a constant lets you define the name of a model in one place, which is particularly useful if you're updating the name of a model that is used by multiple dashboard elements.

For more information and an example of using constants with LookML dashboards, see theconstant parameter documentation page.

explore

This section refers to theexplore parameter that is part of adashboard element.

explore can also be used as part of a model, described on theexplore parameter documentation page.

explore can also be used as part of a dashboard filter, described on theDashboard parameters documentation page.

Theexplore parameter defines the Explore to use for the element query.

- name: orders_by_date  explore: order

Theexplore parameter acceptsLookML constants. You can define a constant in themanifest file for your project, then use the syntax"@{constant_name}" to set the constant as the value forexplore. Using a constant lets you define the name of an Explore in one place, which is particularly useful if you're updating the name of an Explore that is used by multiple dashboard elements.

For more information and an example of using constants with LookML dashboards, see theconstant parameter documentation page.

dimensions

Thedimensions parameter defines the dimension or dimensions to use for the element query. Use the syntaxview_name.dimension_name to specify the dimension. Don't includedimensions if the query doesn't have any.

## single dimension example- name: orders_by_date  dimensions: order.order_date## multiple dimension example- name: orders_by_date  dimensions: [order.order_date, customer.name]

measures

Themeasures parameter defines the measure or measures to use for the element query. Use the syntaxview_name.measure_name to specify the measure. Don't includemeasures if the query doesn't have any.

## single measure example- name: orders_by_date  measures: order.count## multiple measure example- name: orders_by_date  measures: [order.count, order_item.count]

sorts

Thesorts parameter defines the sorts to be used for the element query. The primary sort is listed first, then the secondary sort, and so on. Use the syntaxview_name.field_name to specify the dimension or measure. Don't includesorts if you want to use Looker's default sort order. Descending sorts are suffixed withdesc; ascending sorts don't need a suffix.

## single sort example- name: orders_by_date  sorts: order.order_date desc## multiple sort example- name: orders_by_date  sorts: [order.order_date desc, customer.name]

pivots

Thepivots parameter defines the dimensions that should be pivoted for the element query. Use the syntaxview_name.dimension_name to specify the dimension. Don't includepivots if the query doesn't have any.

## single pivot example- name: orders_by_date  pivots: customer.gender## multiple pivot example- name: orders_by_date  pivots: [customer.gender, customer.age_tier]

limit

Thelimit parameter defines the row limit that should be used for the element query. The limit applies to the number of rowsbefore any pivots are applied.

- name: orders_by_date  limit: 100

filters

This section refers to thefilters parameter that is part of adashboard element.

filters can also be used as part of a dashboard, described on theDashboard parameters documentation page.

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

Thefilters parameter defines the non-changeable filters that should be used for the element's query. If you would like filters that a usercan change in the dashboard, you should set up the filters usingfilters for dashboards, then apply them to the elements usinglisten.

The syntax forfilters is:

- name: element_name  filters:    orders.created_date: 2020/01/10 for 3 days    orders.status: Shipped    # You can create multiple filter statements

Each filter can accept a Lookerfilter expression or a value constant. You can also use the_localization or_user_attributes Liquid variables in the filter expression for flexible filter values.

listen

Dashboard filters let viewers interactively refine the data that is shown in dashboard elements. Define dashboard filters with thefilters parameter for LookML dashboards. Then, use thelisten parameter to link dashboard elements to the dashboard filter.

The syntax forlisten is as follows:

- name: element_name  listen:    filter_name_goes_here: dimension or measure on which to apply                           the filter using view_name.field_name syntax    # You can add more than one listen statement

Add thelisten parameter to an element, and then provide the name of the filter followed by a colon and a reference to the field to which the filter should apply, using theview_name.field_name syntax. For example, you might create a filter calledDate that requires a user to enter a date into the filter field in the UI. You could then apply the value that the user enters to theorders_by_date element like this:

- dashboard: sales_overview  ...  filters:  - name: date    type: date_filter  elements: - name: orders_by_date    listen:      date: order.order_date    ...

For additional examples of using thefilters parameter and thelisten parameter to apply dashboard filters to individual dashboard elements, seeBuilding LookML dashboards.

query_timezone

Thequery_timezone parameter specifies the time zone in which the query will be run. The time zone options are shown on theValues fortimezone documentation page. If you want the query to run using the viewer's time zone, you can assign the value asuser_timezone.

- name: orders_by_date  query_timezone: America/Los Angeles

- name: orders_by_customer  query_timezone: user_timezone

merged_queries

Themerged_queries parameter lets youcombine the results of multiple queries into a single dashboard element. Define each source query within the element'smerged_queries parameter and use thejoin_fieldssubparameter to specifyhow the results should be merged.

The following sample LookML code creates a merged resultselement oftype: looker_grid. In this example, themerged_queries parameter is used to create a dashboard element that combines data from two separate queries into a single table chart:

- name: merged_results_element  title: Merged Results Tile  type: looker_grid  merged_queries:  - model: ecommerce    explore: users    type: table    fields: [users.state, users.count, users.city]    sorts: [users.count desc 0]    limit: 5000    column_limit: 50    query_timezone: UTC    listen:    - State: users.state  - model: ecommerce    explore: users    type: table    fields: [users.state, users.city]    sorts: [users.state]    limit: 500    column_limit: 50    query_timezone: UTC    join_fields:    - field_name: users.state      source_field_name: users.state    - field_name: users.city      source_field_name: users.city    listen:    - State: users.state

In this example, the dashboard element combines data from two source queries that are based on theusers Explore in theecommerce model. The primary query includes theusers.state,users.count, andusers.city fields, and it sorts the results by theusers.count field. The second source query includes theusers.state andusers.city fields and sorts the results by theusers.state field.

Thejoin_field parameter merges the source queries based on matching values in theusers.state andusers.city fields.

Thelisten parameter applies aState filter to both queries, which lets dashboard viewers refine the query results that are displayed in the dashboard tile by selecting a specific state.

Example: Merging company data

Suppose you want to create a merged query that combines information about companies from two different Explores:company_info andcompanies. You want to join the queries on theipo.stock_symbol,companies.name, andcompanies.contact_email fields from each Explore to create a query that returns results for company name, company contact email, IPO year, stock symbol, number of employees, and job count. You can define the merged query element in LookML as follows:

- name: merged_results_element  title: Merged Results Tile  merged_queries:  - model: market_research    explore: company_info    fields: [companies.name, companies.contact_email, ipo.public_year, ipo.stock_symbol]    filters:      companies.contact_email: "-NULL"      ipo.valuation_amount: NOT NULL    sorts: [ipo.public_year desc]  - model: company_data    explore: companies    fields: [companies.name, ipo.stock_symbol, companies.contact_email,      companies.number_of_employees, jobs.job_count]    filters:      companies.number_of_employees: NOT NULL      ipo.stock_symbol: "-NULL"      companies.contact_email: "-NULL"    sorts: [jobs.job_count desc]    join_fields:    - field_name: ipo.stock_symbol      source_field_name: ipo.stock_symbol    - field_name: companies.name      source_field_name: companies.name    - field_name: companies.contact_email      source_field_name: companies.contact_email

Applying filters to merged query elements

Theprevious example of a merged query element demonstrates how to apply hard-coded filters directly within each source query by using thefilters parameter. For example, the filterscompanies.contact_email: "-NULL" andipo.valuation_amount: NOT NULL in the primary query restrict the results to companies that have valid contact emails and valuations. These query-level filters pre-filter the data before merging the queries and cannot be changed by the user.

You can also applydashboard filters to merged query elements by using thelisten parameter within the definition of each source query. For example, suppose you have a dashboard filter namedIndustry that you defined at the dashboard level by using thefilters parameter for LookML dashboards:

filters:- name: Industry  title: Industry  type: field_filter  ui_config:    type: dropdown_menu    display: inline  model: market_research  explore: company_info  field: companies.industry

To apply theIndustry filter to thecompanies.industry field in both source queries, add thelisten parameter to each of the merged query's source query definitions as follows:

listen:  Industry: companies.industry

For example, the following sample code adds theIndustry filter to both source queries in the merged results element from the previous example.

- name: merged_results_element  title: Merged Results Tile  merged_queries:  - model: market_research    explore: company_info    fields: [companies.name, companies.contact_email, ipo.public_year, ipo.stock_symbol]    filters:      companies.contact_email: "-NULL"      ipo.valuation_amount: NOT NULL    sorts: [ipo.public_year desc]    listen:      Industry: companies.industry  - model: company_data    explore: companies    fields: [companies.name, ipo.stock_symbol, companies.contact_email,      companies.number_of_employees, jobs.job_count]    filters:      companies.number_of_employees: NOT NULL      ipo.stock_symbol: "-NULL"      companies.contact_email: "-NULL"    sorts: [jobs.job_count desc]    join_fields:    - field_name: ipo.stock_symbol      source_field_name: ipo.stock_symbol    - field_name: companies.name      source_field_name: companies.name    - field_name: companies.contact_email      source_field_name: companies.contact_email    listen:      Industry: companies.industry

With this addition, when a user interacts with theIndustry dashboard filter, the corresponding source query in the merged query element will be filtered accordingly.

Most of the parameters described in this section correspond to the options in thePlot section of the visualization editor for donut multiples charts.

show_value_labels

Display the value of a bar, line, or point next to the data point.

show_value_labels: true | false## default value: false

font_size

Set the font size of value labels using any valid CSS size, such as10px or12px.

font_size: 14px

charts_across

Thecharts_across parameter specifies the number of small donut charts per row in thetype: looker_donut_multiples visualization.

charts_across: 2## default value: 3

hide_legend

This declaration will hide the legend from the visualization.

hide_legend: true | false## default value: false

hidden_fields

Thehidden_fields parameter indicates which fields, if any, are used in the query but hidden in the chart. Any hidden fields will appear in the data table section of an Explore.

hidden_fields: [inventory_items.count, distribution_centers.id]

Series parameters

The parameters described in this section correspond to the options in theSeries section of the visualization editor for donut multiples charts.

colors

Thecolors parameter specifies a list of colors for the series. The first color in the list corresponds to the first data series. If there are more series than listed colors, the colors will start over at the beginning.

colors: [blue, orange, yellow, red, purple]

For all chart attributes that specify a color, the color value can take a hex string, such as#2ca6cd, or aCSS named color string, such asmediumblue.

series_colors

Set the colors of the series based on the series name, usingname: value pairs.

For a pivoted chart, the series names are the pivot names.

series_colors:  'Yes': skyblue  'No': '#000000'

For a chart with multiple measures, the series names are the measure field names.

series_colors:  inventory_items.count: crimson  orders.count: green

If the series name is not listed inseries_colors, the chart will default to the list of colors provided incolors. Ifcolors is not set, the chart will fall back to the default color scheme.

series_labels

Set the labels of one or more series based on the series name, usingname: label pairs.

For a pivoted chart, the series names are the pivot names.

series_labels:  'Yes': iOS Users  'No': Android Users

For a chart with multiple measures, the series names are the measure field names.

series_labels:  inventory_items.count: Inventory  orders.count: Orders