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
Single Value Chart Parameters for LookML Dashboards

Under Construction: We’re working on adding more to this page. In the meantime, check out the Single Value Chart Options documentation page to view information about creating and editing single value visualizations using the visualization option menu.

The parameters described on this page are for use with LookML dashboard elements of type: single_value.

For information about building a single value chart through the Looker UI, see the Single Value Chart Options documentation page.

Basic Parameters

When defining a LookML dashboard element, you must specify values for at least the name and type parameters. Other basic parameters like title, height, and width affect the position and appearance and position of an element on a dashboard.

name

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

name can also be used as part of a dashboard filter, described on the Dashboard Parameters documentation page.

Each name declaration creates a new dashboard element and assigns it a name. Element names must be unique. Names are sometimes referenced in the elements parameter when using layout: grid dashboards.

- name: orders_by_date

title

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

title can also be used as part of a dashboard, described on the Dashboard Parameters documentation page.

title can also be used as part of a dashboard filter, described on the Dashboard Parameters documentation page.

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

Consider this example:

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

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

type

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

type can also be used as part of a dashboard filter, described on the Dashboard Parameters documentation page.

type can also be used as part of a join, described on the type (for Joins) documentation page.

type can also be used as part of a dimension, described on the Dimension, Filter, and Parameter Types documentation page.

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

The type 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_geo_coordinates | looker_geo_choropleth | looker_waterfall | looker_wordcloud | looker_boxplot

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

height

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

height can also be used as part of a dashboard row, described on the Dashboard Parameters documentation page.

The height parameter defines the height of an element, in units of tile_size for layout: tile and layout: static dashboards.

For example, the code below specifies tile_size: 100 and height: 4, making the orders_by_date element 400 pixels in height.

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

The height parameter defines the height of an element, in units of rows, for layout: newspaper dashboards.

Each row is 50 pixels tall. A dashboard with newspaper layout defaults to an element height of 6 rows, or 300 pixels.

For example, the code below sets an element to be 600 pixels 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 the width parameter that is part of a dashboard element.

width can also be used as part of a dashboard, described on the Dashboard Parameters documentation page.

The width parameter defines the width of an element, in units of tile_size, for layout: tile and layout: static dashboards.

For example, the code below specifies tile_size: 100 and width: 4, making the orders_by_date element 400 pixels in width.

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

The width parameter defines the width of an element, in units of columns, for layout: newspaper dashboards.

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

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

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

top

The top parameter defines the top-to-bottom position of an element in units of tile_size for layout: static dashboards.

For example, the code below specifies tile_size: 100 and top: 4, positioning the top edge of the orders_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

The left parameter defines the left-to-right position of an element in units of tile_size for layout: static dashboards.

For example, the code below specifies tile_size: 100 and left: 4, positioning the left edge of the orders_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

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

A dashboard begins with row 0 at the very 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 code below 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

For layout: newspaper dashboards, the col 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 very 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 code below 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 the refresh parameter that is part of a dashboard element.

refresh can also be used as part of a dashboard, described on the Dashboard Parameters documentation page.

The refresh 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 subparameters text, state, and display.

text

The text subparameter specifies the text displayed in the note. The text can be localized.

state

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

display

The display 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, and hover requires the user to hover their mouse over the element in order to see the note.

Query Parameters

When defining a LookML dashboard element, you must specify values for at least the model and explore query parameters, and at least one field must be specified using either the dimensions parameter or the measures parameter. You can also use the other query parameters described below to control the way data is displayed in a dashboard element.

model

The model 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

explore

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

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

The explore parameter defines the Explore to use for the element query.

- name: orders_by_date explore: order

dimensions

The dimensions parameter defines the dimension or dimensions to use for the element query. Use the syntax view_name.dimension_name to specify the dimension. Don't include dimensions if the query has no dimensions.

# 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

The measures parameter defines the measure or measures to use for the element query. Use the syntax view_name.measure_name to specify the measure. Don't include measures if the query has no measures.

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

sorts

The sorts 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 syntax view_name.field_name to specify the dimension or measure. Don't include sorts if you want to use Looker's default sort order. Descending sorts are suffixed with desc; 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

The pivots parameter defines the dimensions that should be pivoted for the element query. Use the syntax view_name.dimension_name to specify the dimension. Don't include pivots if the query has no pivots.

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

limit

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

- name: orders_by_date limit: 100

filters

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

filters can also be used as part of a dashboard, described on the Dashboard Parameters documentation page.

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

The filters parameter defines the non-changeable filters that should be used for the element's query. If you would like filters that a user can change in the dashboard, you should set up the filters using filters for dashboards, then apply them to the elements using listen.

The syntax for filters 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 Looker filter 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

Dashboards can have filters that allow users to change the data behind dashboard elements. These are set up by using the filters for dashboards parameter. In order for a filter to impact an element, the element must be set up to "listen" for that filter, using the listen parameter.

The syntax for listen is:

- 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

For example, you might create a filter called Date 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 the orders_by_date element like this:

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

This concept is described in more detail on the Building LookML Dashboards documentation page.

query_timezone

The query_timezone parameter specifies the time zone in which the query will be run. The time zone options are shown on the Values for timezone documentation page. If you wish the query to run using the viewer's time zone, you can assign the value as user_timezone.

- name: orders_by_date query_timezone: America/Los Angeles
- name: orders_by_customer query_timezone: user_timezone

merged_queries

The merged_queries parameter defines how to merge results from several queries. You define the component queries under the merged_queries parameter and use the join_fields subparameter to define the merge rules.

The syntax for merged_queries is:

merged_queries: - 'primary query definition' - 'next source query definition' join_fields: - field_name: 'field from the source query using the view_name.field_name syntax' source_field_name: 'joined field from the primary query using the view_name.field_name syntax' # more join_fields definitions as needed - 'next source query definition' join_fields: - field_name: view_name.field_name source_field_name: view_name.field_name # more join_fields definitions as needed # additional source queries and join_fields definitions as needed

The first query defined under merged_results is the primary query and the other queries will be merged with that one.

For example, you can merge two queries to return results for company name, company Twitter username, IPO year, stock symbol, number of employees, and job count, by joining on the stock symbol, company name, and Twitter username:

- name: merged_results_element title: Merged Results Tile merged_queries: - model: market_research explore: company_info fields: [company.name, company.twitter_username, ipo.public_year, ipo.stock_symbol] filters: company.twitter_username: "-NULL" ipo.valuation_amount: NOT NULL sorts: [ipo.public_year desc] - model: crunchbase explore: companies fields: [companies.name, ipo.stock_symbol, companies.twitter_username, companies.number_of_employees, jobs.job_count] filters: companies.number_of_employees: NOT NULL ipo.stock_symbol: "-NULL" companies.twitter_username: "-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: company.name - field_name: companies.twitter_username source_field_name: company.twitter_username

The data results would be formatted like this:

Then you can apply element parameters to style the visualization as you desire.

hidden_fields

The hidden_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]

Style Parameters

The parameters described in this section correspond to the options in the Style section of the visualization editor for single value charts.

colors

The colors 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 a CSS named color string, such as mediumblue.

custom_color_enabled

Setting the custom_color_enabled parameter to true enables the option to specify a custom color for a single value visualization. Use this parameter with the custom_color parameter.

custom_color_enabled: true | false

custom_color

Specify a custom color for the text in a single value visualization.

custom_color: #2ca6cd | mediumblue

show_single_value_title

When this parameter is set to true, a title is displayed under the query's value. You can specify or change the title using the single_value_title parameter.

show_single_value_title: true | false

single_value_title

Specify a title to display with the query's value. The title text can be localized.

single_value_title: Title

value_format

The value_format parameter specifies the format of the query's value, independent of any formatting applied to the underlying dimension or measure. This field accepts Excel-style formatting. If value_format is not specified, the value will be displayed in the format of the underlying dimension or measure.

Comparison Parameters

The parameters described in this section correspond to the options in the Comparison section of the visualization editor for single value charts.

show_comparison

When set to true, the show_comparison parameter enables you to add comparison information to a dashboard element of type: single_value.

show_comparison: true | false

comparison_type

Use the comparison_type parameter to specify how the comparison field is used in a dashboard element of type: single_value.

You can specify one of the following values for the comparison_type parameter:

comparison_type: value | change | progress | progress_percentage

show_comparison_label

Specify whether a label is shown with the comparison field. By default, the label is the name of the comparison field.

show_comparison_label: true | false

comparison_label

Specify the label to be displayed with the comparison field. The comparison label text can be localized.

show_comparison_label: true comparison_label: Label

comparison_reverse_colors

If comparison_type is set to change, you can set comparison_reverse_colors to true to display negative numbers in a comparison field as green text with a green triangle, while positive numbers appear as red text with a red triangle.

comparison_type: change comparison_reverse_colors: true | false

Top