User Guide Help Center Documentation User Forums Training
New LookML
Old LookML
New LookML
LookML Functional Reference

Overview

As discussed on our What is LookML? tutorial page, LookML is a language for describing dimensions, aggregates, calculations, and data relationships in a SQL database. Looker uses a model written in LookML to construct SQL queries against a particular database.

After learning LookML, you can use this reference page to quickly identify the parameters you need to achieve the data modeling effect you want — or simply to take a tour of what’s possible. This reference includes the parameters that can be used for data modeling, organized by the effect they have in the Looker UI or in the generated queries. Each section also includes links to related tutorials in Looker Docs and Looker’s Learn environment.

At the end of this reference is a brief section about other types of resources, including tutorials and reference guides for understanding LookML and the development process, creating dashboards, embedding, and the Looker API.

Types of Files

A LookML Project is a collection of files that defines the data modeling and (optionally) dashboards for a project. The data modeling parameters can be added to these types of files:

If you are looking at an existing model and want to know what each parameter is doing, this reference is useful — but you may find it more efficient to use the individual reference pages for the relevant LookML structures: manifest, model, explore, join, view, or fields.

Types of Parameters

Some data modeling parameters affect the Looker user interface, some affect only the query and many affect both. On the left side of the current page is an On this page section, which you can use to quickly jump to a section listing available parameters for a specific type of functionality.

If you want to:

Using Each Section in This Reference

Each topic or subtopic includes links to related tutorials and a table of the parameters that provide that type of functionality

The tutorials are in Looker Docs or in Learn, where you can see the LookML functioning in a Looker instance. Ask the Looker chat team or your Looker analyst if you don’t yet have an account on Learn.

Each table entry lists:

The Level in the table entries is manifest, model, explore, join, view, or fields. There can be several different parameters with the same name, which are used at different levels in LookML.

For the field-level parameters, often the same parameter can be used with several types of fields. Thus, a symbol is used to identify the types of fields that can include that parameter. You can hover over the symbol to remind yourself of its meaning or click it to see a reference page for that field type. The symbols are:

D = Dimension    DG = Dimension Group    F = Filter    M = Measure   P = Parameter  


Structural

A project contains one or more model files and one or more view files, each containing LookML parameters specifying how to query and display data in Looker. Optionally, you could have one or more explore files to implement native derived tables.

Relationships between LookML Elements

The diagram shows that view typically includes the most common field types (dimensions and measures). A view also can contain several other field types: dimension groups, filter fields, and parameter fields.

The rest of this topic is divided into these subsections:

Major Structural Parameters in a Model or Explore File

As shown in the diagram above, a project contains one or more model files. The model files use parameters to define a model and its explores and joins. The project also contains one or more view files. The view files contain parameters that define the view, its fields (including dimensions and measures), and sets of fields in the view.

This section describes the major structural parameters that you typically put in a model file. An explore parameter is usually defined at the top level of a model file, but when using a native derived table may be defined in an explore file.

In addition to the parameters listed in the table below, check out these related tutorials:

Parameter Name Level Description
explore Model Expose a view in the Explore Menu. For more information about explores and their parameters, see the Explore Parameter Reference page. This parameter affects the explore name and menu. This parameter has many subparameters listed elsewhere on the current page.
fields Explore Limits the fields available in an explore from its base view and through the explore’s joins. Affects the fields available in the Field Picker.
include Model Add files to a model. Also can be used in view files for native derived tables.
join Join Join an additional view to an explore

Major Structural Parameters in a View File

As shown in the diagram in the Structural section above, a project contains one or more view files, each containing parameters defining that view, its fields (including dimensions and measures), and sets of fields.

This section describes the major structural parameters that you typically put in a view file. In addition to the parameters listed in the table below, check out these related tutorials:

Parameter Name Level Description
dimension View (but listed on field reference page) Create a dimension field. Affects the default behavior of the Field Picker.
dimension_group View (but listed on field reference page) Create several time-based dimensions at the same time. Affects the default behavior of the Field Picker.
fields Join Determine which fields from a join are brought into an explore
filter View (but listed on field reference page) Create a filter-only field for use in a templated filter or conditional join. Affects the default behavior of the Field Picker.
measure View (but listed on field reference page) Create a measure field. Affects the default behavior of the Field Picker.
parameter View (but listed on field reference page) Create a filter-only field users can use to provide input to a liquid {% parameter %} tag. Affects the default behavior of the Field Picker.
view Model (but in view file) Create a view. Affects the default behavior of the Field Picker. This parameter has many subparameters listed elsewhere on the current page.

Helper Structural Parameters

These parameters help you define the structural behavior you want, such as letting you specify sets of fields, include certain files (and their contents), reuse definitions, and so forth. In addition to the parameters listed in the table below, check out these related tutorials:

Also, check out these tutorials about referencing structural parameters:

Also, many parameters let you specify a SQL block, discussed in the SQL Block section of the LookML Terms and Concepts tutorial.

The helper structural parameters are:

Parameter Name Level Description
extends Explore and View Lets you reuse the definition of another LookML object, adding and overriding subparameters as desired. (Can also be used with LookML dashboards.)
extension Explore and View Lets you specify that an explore, view or dashboard cannot be used directly. Instead the definition is intended as a template for other objects, which use extends based on this object. (Can also be used with dashboards.)
include Model Add files to a model. Also can be used in view files for native derived tables.
local_dependency Manifest Specify one or more project that contains files that you want to include.
project_name Manifest Specify the name of the current project.
set View Define a set of dimensions and measures to be used in other parameters. Can be used to limit the fields available to a join and therefore to the Field Picker. Also can be used to define which fields should appear when a user drills into the data. This parameter has a fields subparameter.
timeframes Fields: DG Define the set of timeframe dimensions you want a dimension_group to produce. Affects the default behavior of the Field Picker.

Explore Name and Menu

The name of an explore and its appearance on the Explore menu can help your users choose the right explore for their needs. This topic has several subsections:

Default Behavior

The default Explore name and Explore menu appearance is specified by the parameters listed below. In addition, this topic is discussed in the Explore Name and Menu section of the Explore Menu and Field Picker tutorial.

Parameter Name Level Description
explore Model Expose a view in the Explore Menu. For more information about explores and their parameters, see the Explore Parameter Reference page. This structural parameter affects the explore name and menu.

Modifying Explore Name and Menu

The name of an explore and its appearance on the Explore menu can help your users choose the right explore for their needs. The Explore name and Explore menu appearance can be modified by the parameters in the table below.

In addition, this topic is discussed in these tutorials:

Parameter Name Level Description
description Explore Add a description for an explore that appears to users on the Explore page and in the Explore menu
group_label Explore Create a label to use as a heading in the Explore Menu
hidden Explore Hide an explore from the Explore Menu
label Explore Change the way an explore appears in the Explore Menu
label Model Change the way a model appears in the Explore Menu

Field Picker

The organization and display names of the views and fields in the Field Picker can help users understand visualizations and find the fields they need in explores. The Field Picker’s contents and organization is discussed in the Explore Menu and Field Picker tutorial.

The parameter listings in this topic are divided into these subsections:

Default Behavior

The default Field Picker appearance and behavior is specified by the parameters listed below. In addition, this topic is discussed in the Field Picker Display Overview section of the Explore Menu and Field Picker tutorial.

Parameter Name Level Description
dimension View (but listed on field reference page) Create a dimension field. Affects the default behavior of the Field Picker.
dimension_group View (but listed on field reference page) Create several time-based dimensions at the same time. Affects the default behavior of the Field Picker.
filter View (but listed on field reference page) Create a filter-only field for use in a templated filter or conditional join. Affects the default behavior of the Field Picker.
measure View (but listed on field reference page) Create a measure field. Affects the default behavior of the Field Picker.
parameter View (but listed on field reference page) Create a filter-only field users can use to provide input to a liquid {% parameter %} tag. Affects the default behavior of the Field Picker.
timeframes Fields: DG Define the set of timeframe dimensions you want a dimension_group to produce. Affects the default behavior of the Field Picker.
view Model (but listed on view reference page) Create a view. Affects the default behavior of the Field Picker

Modifying the View Names

The display name of a view can help your users understand and find the fields they need in explores. If the view name is shown in a visualization, then modifying the view names can help users understand the visualization. The view names in the Field Picker can be modified by the parameters in the table below. In addition, this topic is discussed in the View Names in Field Picker section of the Explore Menu and Field Picker tutorial.

Parameter Name Level Description
label View Specify how the view name will appear in the Field Picker
view_label Explore Specify how a group of fields from the explore’s base view will be labeled in the Field Picker
view_label Join Change the way the join’s view name appears in the Field Picker

Modifying the Field Organization

The organization of fields can help your users find the fields they need in explores. The organization of fields in the Field Picker can be modified by the parameters in the table below.

In addition, this topic is discussed in these tutorials:

Parameter Name Level Description
group_label Fields: D DG M F Group fields together within a view in the Field Picker
view_label Fields: D DG M F P Change the fields that appear within a view in the Field Picker

Modifying the Field Listings

Modifying the way that fields are listed can help your users understand visualizations and find the fields they need in explores. The listings for fields in the Field Picker can be modified by the parameters in the table below.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
description Fields: D DG M F P Add a description to the field users can see on hover
fields Explore Limits the fields available in an explore from its base view and through the explore’s joins. Affects the fields available in the Field Picker.
fields Join Determine which fields from a join are brought into an explore
hidden Fields: D DG M F P Hide a field from the Explore UI
label Fields: D DG M F P Change the way a field name appears in the Field Picker
label_from_parameter Fields: D M Change the way a field name appears in the Field Picker based on the input to a parameter

Data Values and Data Display

In the Data section, modifying the data values, format, and order can help your users understand the results. In some cases, it might be appropriate to enable data filling. If you are using locational information, consider using parameters to specify what map to use for your data.

This topic includes the following sections:

Affecting Data Values for Multiple Field Types

You can change the data values using the parameters in the table below. Also, check out the related information in the SQL Block section of the LookML Terms and Concepts tutorial.

Users can also define their own table calculations that show in the Data section. However, when possible, you should define dimensions and measures in LookML so that the correct calculation is made once and then used consistently in various queries.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
case Fields: D M Create a discrete set of values a dimension can have determined by SQL conditions. This parameter has when and else subparameters.
sql Fields: D DG M F Determine how a field will be calculated
type (for dimension, filter, or parameter) Fields: D F P Specify the type of dimension, filter, or parameter
type (for dimension group) Fields: DG Dimension groups always use type: time
type (for measure) Fields: M Specify the type of measure

Affecting Data Values for Specific Dimension Types

You can modify the data values for some dimension types using type-specific parameters. These dimension types include:

You can also see examples of several of these parameters in these tutorials:

Affecting data values for date or datetime dimensions:

Parameter Name Level Description
convert_tz Fields: D DG F M P Disable automatic time zone conversion for a dimension_group
datatype Fields: D DG F Specify the type of time data you are providing to a dimension_group.
fiscal_month_offset Model Specify the month your fiscal year begins (if it differs from calendar year)
week_start_day Model Specify the day of week that week-related dimensions should start on

Affecting data values for type: distance dimensions:

Parameter Name Level Description
end_location_field Fields: D Define the field that contains the end location for a type: distance field. Also considered a structural parameter.
start_location_field Fields: D Define the field that contains the start location for a type: distance field
units Fields: D The unit to use for type: distance fields

Affecting data values for type: location dimensions:

Parameter Name Level Description
sql_latitude Fields: D Define the latitude of a type: location dimension
sql_longitude Fields: D Define the longitude of a type: location dimension

Affecting data values for type: tier dimensions:

Parameter Name Level Description
tiers Fields: D Define the tiers for a type: tier dimension

Affecting Data Values for Measures

You can modify the data values for measures. Most are limited to specific measure types, as specified in the table. Also, check out these related tutorials:

Parameter Name Level Description
approximate Fields: M Perform an approximate count for type: count_distinct measures, for Redshift or BigQuery
approximate_threshold Fields: M Set the count at which BigQuery switches from an exact count distinct to an approximate count distinct
direction Fields: M Determine the direction that type: percent_of_total or type: running_total measures are calculated when pivots are used
list_field Fields: M Declare the dimension from which a type: list measure will be calculated. Also considered a structural parameter.
percentile Fields: M Specify the fractional value (the Nth percentile) for a type: percentile or type: percentile_distinct measure
primary_key Fields: D Declare a dimension as the primary key of a view
sql_distinct_key Fields: M Define the unique entities over which a type: sum_distinct or type: average_distinct measure will be calculated
symmetric_aggregates Explore Specify whether symmetric aggregates are enabled for an explore. Also listed for parameters affecting how a join behaves.

Data Formats

You can make data values more easily readable for your users by formatting the data using the parameters in the following table.

Also, read the following tutorials:

Parameter Name Level Description
html Fields: D DG M Modify the HTML output of a field using liquid templating
named_value_format Model Create a custom value format to be used with value_format_name. This parameter has a value_format subparameter.
style Fields: D Change the way that tiers appear in the Looker UI for a type: tier dimension
value_format Fields: D M Format the output of a field using Excel style options
value_format_name Fields: D M Format the output of a field using a built-in or custom format

Data Order and Filling

For most fields, the sort order is straightforward — just an alphanumeric sort of the values. In some cases, you may want the results of a New LookML case or Old LookML sql_case statement to sort in a particular order. Or you may want the values to sort by another field’s value. You also can specify whether to block users from asking Looker to fill in missing dates and values for a field.

Parameter Name Level Description
allow_fill Fields: D DG Determine if dimension filling is allowed for a dimension
alpha_sort Fields: D Make a case parameter sort its conditions alphabetically
order_by_field Fields: D M Sort a field by the values of another field

Visualizing the Data

If you are providing locational data to users, Looker provides a variety of maps you can make available to visualize data values in the Visualization section. You can also provide and use custom maps for the visualizations.

Parameter Name Level Description
map_layer Model Create custom maps to be used with map_layer_name. This parameter has many subparameters listed on the map_layer page.
map_layer_name Fields: D Specifies a mapping from a data value to a geographic region that you’ve defined on a built-in or custom map

Using the Data

You can let your users click on a data value to drill into the data, link to another resource (in Looker or an external URL), or let a user trigger an action. You can specify the desired behavior for those situations using parameters in this section.

For the Visualization section, you also can provide custom maps or Looker-provided maps for your data values. For this functionality, see the Visualizing the Data section on the current page.

Drilling

In Looker, every query result can be the starting point for another query. Users can click on a data value to drill into the data. You can specify which fields are displayed when the user drills into the data.

In addition to the parameters listed in the table below, check out these related tutorials:

Parameter Name Level Description
drill_fields Fields: D DG M Declare the list of fields that will be displayed when the measure or dimension is drilled into
set View Define a set of dimensions and measures to be used in other parameters. Can be used to limit the fields available to a join and therefore to the Field Picker. Also can be used to define which fields should appear when a user drills into the data.

Linking

You can let your user click on a data value to navigate to a related URL. You can specify which fields are displayed when the user drills into the data. In the parameters below, you can specify the text to display, the destination URL, and a favicon (the icon for the destination website).

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
link Fields: D M Create links to other Looker and external content. This parameter has label, url, and icon_url parameters.

Using Data Actions

Sometimes your users will want to be able to trigger other events after viewing the data. If you are using Action Hub, you specify that fields with certain tags can use specific integrated services. You also can use data actions to specify what options are available to the users for a field. These parameters are shown in this table:

Parameter Name Level Description
action Fields: D M Creates a data action on a field that lets users perform tasks in other tools, directly from Looker. This parameter has many subparameters listed on the action page.
tags Fields: D DG M F P Add text that can be passed to other applications to provide data about a field

Filtering

Users can specify filters for their queries in Explores, Looks, and dashboards.

Specifying filter options can help you curate the user’s experience, adding in filters that will help them or ensure that they do not accidentally create a query that causes unnecessarily heavy use of your database resources. You also can specify whether filters are case sensitive or have default values. There are also multiple parameters for specifying how Looker provides filter suggestions as the user types.

Be sure to check out these related tutorials:

This topic is divided into the following sections:

Requiring Filters with Fixed Values

Specifying filter options can help you curate the user’s experience, adding in filters that will help them or ensure that they do not accidentally create a query that causes unnecessarily heavy use of your database resources.

Be sure to check out these related tutorials:

Here are the parameters for specifying filters that will always be used:

Parameter Name Level Description
access_filter Explore Add user-specific filters to an explore. Has subparamters field and user_attribute.
sql_always_having Explore Insert conditions into the query’s HAVING clause that a user cannnot change or remove for this explore
sql_always_where Explore Insert conditions into the query’s WHERE clause that a user cannnot change or remove for this explore
sql_where Join If this join is included in the query, inserts conditions into the query’s WHERE clause that a user cannnot change or remove for this explore. (For BigQuery only). Also could be considered a filter parameter.

Requiring Filters with Changeable Values

With this section’s parameters, you can specify that filters must be used but permit the user to change the value of the filter.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
always_filter Explore Add filters a user can change, but not remove, to an explore. This parameter has a filters subparameter.
filter Fields: F Create a filter-only field for use in a templated filter
filters Fields: M Restrict a measure’s calculation based on dimension limitations. This parameter has field and value subparameters.

Preventing Filters

Using the following parameters, you can also prevent a user from using a field as a filter in all circumstances or just when drilling.

Parameter Name Level Description
can_filter Fields: D DG M Determine if a dimension or measure can be used as a filter
skip_drill_filter Fields: D Stop a dimension from being added to the filters when a measure is drilled into

Conditional Filters

In some cases, you may want to specify that the user must use one of several filters to narrow their query. For example, the user must limit the query by date or by region. In addition to the parameter listed below, see the Filtering Result Sets section of the Advanced LookML Concepts page.

Parameter Name Level Description
conditionally_filter Explore Add filters to an explore if a user does not add their own filter from a specific list. This parameter has filters and unless subparameters.

Filter Value Behavior

To make filtering easier for your users, you can provide a default value for the filter or treat the filter values as case-insensitive.

Parameter Name Level Description
case_sensitive Explore Specify whether filters are case sensitive for an explore
case_sensitive Fields: D F Determine if filters are case sensitive for a dimension
case_sensitive Model Specify whether filters are case sensitive for a model
default_value Fields: F P Specifies a default value for filter fields

Filter Suggestions

Filter suggestions are a great way to help your users filter data successfully. By default, the suggestion values are based on that field’s unique values. In some cases, it may be useful to disable suggestions or to change the suggestion behavior.

This topic is divided into several sections:

Enabling or Disabling Suggestions

If you think that a field has a very large number of unique values, it might make sense to disable filter suggestions for that field. That avoids the user having to wade through too many suggestions and the database having to provide those suggestions. You can enable or disable filter suggestions at several levels.

Parameter Name Level Description
suggestable Fields: D DG M F P Enable or disable suggestions for a field
suggestions Explore Specify whether filter suggestions are enabled for an explore
suggestions View Enable or disable suggestions for all dimensions on this view

Suggestion Values

By default, the filtering suggestions are based on that field’s unique values. In some cases, the filtering suggestions might be more useful if you specified the most likely filter suggestions. Also, if you are limiting access to some values in the data, then you can choose to apply or not apply those limits to the suggestions.

Parameter Name Level Description
allowed_value Fields: P Specify the choices for a parameter. This parameter has label and value.
bypass_suggest_restrictions Fields: D DG F P Show suggestions to users when sql_always_where or access_filter_fields is in use, but don’t apply those limits to the suggestions
full_suggestions Fields: D DG F P Show suggestions to users when sql_always_where or access_filter_fields is in use, and do apply those limits to the suggestions
suggest_dimension Fields: D DG M F P Base the suggestions for a field on the values of a different dimension
suggest_explore Fields: D DG M F P Base the suggestions for a field on the values of a different explore
suggestions Fields: D F P Declare a list of values that will be used for a field’s suggestions

Caching Suggestions

By default, the filtering suggestions are based on that field’s unique values. Those values are cached to help performance, but you can change the length of time that the cached values are used. If the data is fairly stable, consider using a longer time to improve the performance for getting those suggestion values.

Parameter Name Level Description
suggest_persist_for Fields: D F P Change the cache settings for Looker filter suggestions

Joining Views

As discussed in Working with Joins in LookML, joins enable the exploration of data from more than one view at the same time. You can “join” together different views to let users see how your data relates to each other.

Joins are defined in the model file to establish the relationship between an explore and a view. Joins connect one or more views in a single explore, either directly, or through another joined view.

This topic is divided into two sections:

What to Join

There are a variety of parameters that specify what views to join, in general and in specific situations. In addition, you can specify which fields be brought into the join.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
always_join Explore Specify which joins must always be applied to an explore
fields Join Determine which fields from a join are brought into an explore
from Join Specify the view on which a join will be based
include Model Add files to a model. Only views in files available in the model can be used for joins.
join Explore Join an additional view to an explore. For more information about joins and their parameters, see the Join Parameters reference page. This parameter has many subparameters listed elsewhere on the current page.
required_joins Join Specify which joins should be applied to an explore when fields from a certain join are chosen
sql_table_name Join Specify the database table on which a join will be based

How to Join

You can specify how the joins between views should work and what the join condition will be. You should also specify a primary key so that Looker can use symmetric aggregates to provide correct results for aggregates.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
foreign_key Join Specify a relationship between an explore and a join using the joined view’s primary key
outer_only Join Specify whether all queries must use an outer join
primary_key Fields: D Declare a dimension as the primary key of a view
relationship Join Declare a join as having a one-to-one, many-to-one, one-to-many, or many-to-many relationship
sql_on Join Specify a relationship between an explore and a join by writing a SQL ON clause
symmetric_aggregates Explore Specify whether symmetric aggregates are enabled for an explore. Also listed for parameters affecting measure values.
type Join Declare a join as being a left, full, inner, or cross type

Caching

Looker reduces the load on your database and improves performance by using cached results of prior queries when available and permitted by your caching policy. In addition, you can create complex queries as persistent derived tables (PDTs), which store their results to simplify later queries. You need to balance this efficiency with how “fresh” the data should be for your users.

This topic is divided into the following sections;

Caching Queries

When planning caching, you should consider both performance and how “fresh” the data should be. You can use datagroups to integrate Looker more closely with the ETL phase of your data pipeline. For example, if you load data in batch through a nightly ETL job then you can have Looker notice that the ETL has finished and clear any related cached queries.

In addition to the parameters below, see the following tutorials:

Parameter Name Level Description
datagroup Model Creates a datagroup caching policy for the model. This parameter has max_cache_age and sql_trigger subparameters.
persist_for Explore Change the cache settings for an explore. Consider using the greater functionality of a datagroup parameter instead.
persist_for Model Change the cache settings for a model. Consider using the greater functionality of a datagroup parameter instead.
persist_with Explore Specify the datagroup to use for the explore’s caching policy
persist_with Model Specify the datagroup to use for the model’s caching policy

Caching Filter Suggestions

By default, filtering suggestion values are based on a query of that field’s unique values. Those values are cached to help performance, but you can change the length of time that the cached values are used. If the data is fairly stable, consider using a longer time to improve the performance for getting those suggestion values.

Parameter Name Level Description
suggest_persist_for Fields: D F P Change the cache settings for Looker filter suggestions

Caching for PDTs

The Regeneration and Caching Parameters for PDTs section of the current page provides parameters affecting caching for PDTs.

Creating Derived Tables

As discussed in the Using Derived Tables tutorial, derived tables are important tools in Looker that enable you to expand the sophistication of your analyses. In some cases, they can also play a valuable role in enhancing query performance.

At a high level, Looker’s derived table functionality provides a way to create new tables that don’t already exist in your database. These tables can be temporary and built at query time, or they can be stored in your database. Either way, you define a derived table by writing a SQL query, and the results of that query become the derived table. You can then reference the derived table in a LookML view, just like any other table.

In addition to the parameters listed, check out these tutorials:

Structural Parameters for Derived Tables

Derived tables can be defined using SQL or LookML. All derived tables start with this parameter:

Parameter Name Level Description
derived_table View Base a view on a derived table. This parameter has many subparameters listed elsewhere on the current page.

Native derived tables are much easier to read, understand, and reason about as you model your data.

Parameter Name Level Description
bind_filters View Specifies a filter on the field specified in its to_field subparameter. The value is from the runtime filter specified by the from_field subparameter. The runtime filter must be in a view joined to the same explore.
column View Specifies a column to include in the explore_source. Has a field subparameter.
derived_column View Specifies a column in the explore_source with an expression in the namespace of the inner columns. Aggregate SQL expressions will not work here, since there is no SQL grouping at this step. This is especially useful for defining window functions when applicable. Has a sql subparameter.
explore_source View Generates SQL for a derived table based on its associated explore. The explore_source has various subparameters which are specified in this table.
expression_custom_filter View Optionally specifies a custom filter expression on an explore_source query.
filters View Optionally specifies a custom filter expression on an explore_source query.
include Model Add files to a model. Only views in files available in the model can be used for joins. Also used when creating native derived tables as described in this page
limit View Optionally, specifies the row limit of the query.
sort View Optionally, specifies a sort for this explore_source. Has a desc subparameter to specify whether the sort should be descending and a field subparameter to specify the field to sort.
timezone View Sets the time zone for the explore_source query. For non-persistent derived tables, set the time zone to “query_timezone” to automatically use the time zone of the currently running query. If time zone is not specified, by default the explore_source query will perform no time zone conversion (operating in the database time zone).

For SQL derived tables, use the parameter listed below. Also, read the following tutorials:

Parameter Name Level Description
sql (for derived_table) View Declare the SQL query for a derived table

Regeneration and Caching Parameters for PDTs

When planning PDT regeneration and its related query caching, you should consider both efficiency and how “fresh” the data should be.

You can use datagroups to integrate Looker more closely with the ETL phase of your data pipeline. For example, if you load data in batch through a nightly ETL job then you can have Looker notice that the ETL has finished and clear any related cached queries.

Using the same or different datagroups, you can choose to regenerate PDTs when the fresh data becomes available. Alternatively, you can specify that PDTs should be regenerated infrequently, even though the underlying tables update frequently, so queries against the PDTs can be cached longer.

For PDTs, use the parameters listed below. Also, read the following tutorials:

Parameter Name Level Description
datagroup_trigger View Specify the datagroup to use for the PDT rebuilding policy
persist_for (for derived_table) View Set the maximum age of a persistent derived table before it is regenerated. Consider using the more powerful datagroup_trigger parameter.
sql_trigger_value View Specify the condition that causes a persistent derived table to be regenerated. Consider using the more powerful datagroup_trigger parameter.

Query Efficiency Parameters for DTs

Depending on your database dialect, there are some parameters you can use to improve the efficiency of your derived table. Also, you can see some of the parameters in the Persistent Derived Tables - Advanced LookML tutorial on Learn.

Parameter Name Level Description
distribution View Set the distribution key of a persistent derived table that is built in Redshift or Aster
distribution_style View Set the distribution style of a persistent derived table that is built in Redshift
indexes View Set the indexes of a persistent derived table built in a traditional database (e.g. MySQL, Postgres) or an interleaved sort key in Redshift
partition_keys View ADDED5.10Specify that a persistent derived table be partitioned by one or more fields in Presto, or by a single date/time field in BigQuery
sortkeys View Set the sort keys of a persistent derived table that is built in Redshift

Additional Query Behavior Parameters

Many of the parameters listed in other sections of the current page affect the resulting query. This section provides some additional parameters that affect either:

What You Query

There are a variety of parameters that affect what you query that have not been mentioned in other sections.

For example, you need to specify the connection to be used to run the queries against the database. Optionally, you can specify that Looker add certain fields to the user’s query. You also have a variety of parameters to affect the view or database table that will be used for the query.

In addition to the parameters below, check out these tutorials:

Parameter Name Level Description
connection Model Change the database connection for a model
fanout_on Fields: D DG M Enable access to Google BigQuery repeated fields
from Explore Specify the view on which an explore will be based, and reference the fields of that view by the explore’s name
required_fields Fields: D M F P Require that additional fields are added to a query when a field is chosen
sql_table_name Explore Specify the database table on which an explore will be based
sql_table_name View Change the SQL table on which a view is based
view_name Explore Specify the view on which an explore will be based, and reference the fields of that view by the view’s name

How You Query

There are a variety of parameters that affect how Looker constructs or handles the query. Most of them have been mentioned in other sections, but here are the remaining ones.

Several of these parameters involve making sure that symmetric aggregates will work. For more information about symmetric aggregates, see:

Parameter Name Level Description
alias Fields: D DG M F P Allow saved URLs with old field names to remain functional after re-naming a field
cancel_grouping_fields Explore Cancel the GROUP BY clause when certain fields are chosen in an explore
primary_key Fields: D Declare a dimension as the primary key of a view
sql_where Join If this join is included in the query, inserts conditions into the query’s WHERE clause that a user cannnot change or remove for this explore. (For BigQuery only). Also could be considered a filter parameter.
symmetric_aggregates Explore Specify whether symmetric aggregates are enabled for an explore. Also listed for parameters affecting measure values.

Parameters to Avoid

You may see the following parameters in your model, so the current page lists what those parameters do. However, if you are adding new modeling, please avoid these parameters.

Parameter Name Level Description
access_filter_fields Explore AVOID AS OF3.10 Replaced by access_filter
decimals Fields: D M AVOID AS OF3.38 Replaced by value_format
distkey View AVOID AS OF3.26 Set the distribution key of a persistent derived table that is built in Redshift
format Fields: D M AVOID AS OF3.16 Replaced by value_format
scoping Model AVOID AS OF3.52 No longer required
sql Join AVOID AS OF3.10 Replaced by a combination of sql_on, foreign_key, type, and/or sql_table_name, as described here
sql_foreign_key Join AVOID AS OF3.16 Replaced by foreign_key
template Model AVOID AS OF3.30 Specify the template engine to be used with html parameters
view_label View AVOID AS OF4.4 Specify how the view name will appear in the Field Picker. Use label instead.

Other Tutorials and Resources

This section lists tutorials and reference guides for other types of development tasks and tools:

Understanding LookML and the Development Process

This reference focuses on LookML parameters and mentions relevant Writing LookML tutorials along the way, but you may want to use the Looker Docs menu to read through additional tutorials. The links below are for the first tutorial in each series:

Creating Dashboards

This reference includes only data modeling parameters, not LookML dashboard parameters. Any dashboard files in a project contain parameters for defining a LookML dashboard. You can read the Dashboard Parameters page for dashboard parameters that affect the entire dashboard, the Dashboard Element Parameters page for dashboard parameters that affect a single dashboard element, and the Dashboard Reference Line Parameters page for adding a reference line to a dashboard tile. You also can create a user-defined dashboard or convert one type of dashboard to the other type.

Embedding Looks, Explores, and Dashboards

For embedding Looks, Explores, and dashboards you can learn more about Basic Private Embedding or about SSO Embedding. Either way, you can also interact with those iframes using Embedded JavaScript Events.

Using the API and SDKs

The Looker API is a secure, “RESTful” application programming interface for managing your Looker instance, and fetching data through the Looker data platform. With the Looker API you can write applications or automation scripts to provision new Looker user accounts, run queries, schedule reports, and so forth. Just about anything you can do in the Looker application you can do via the Looker API. Check out this article to get started with the API, then use the Looker API Reference to learn details of the Looker API endpoints for each type of functionality.

We recommend using our Ruby SDK or Swagger-generated SDK to take care of the intricate details of authentication, parameter serialization, response serialization, and other concerns.

Top