This is an advanced topic that assumes a solid knowledge of LookML.

Overview

With LookML refinements, you can adapt an existing view or Explore without editing the LookML file that contains it. This is ideal for:

• Projects with Looker Blocks, which use pre-built pieces of LookML.
• Projects that import files from other projects.
• Projects where you often need to generate your files from tables in your database.
• Situations where you want to share LookML between models or projects while making customizations in each place (hub-and-spoke configurations).

For example, if you have the following view file in your project:

You can refine the flights view as shown below: Use the view parameter with the same view name, but add a plus sign (+) in front of the name to indicate that it’s a refinement of an existing view.

This refinement adds an air_carrier dimension to the existing flights view:

This refinement can go in any LookML file in the project, such as a model file, view file, or in its own dedicated LookML file. See the Using Refinements in Your LookML Project section for how it works.

The refinement combined with the original LookML has the end result as if this were the original LookML for the view:

In the Looker UI, users will see the Air Carrier dimension, just as if you had added the dimension to the original view file itself.

See the example below for more detailed implementation information.

Refinements Compared to Extends

Looker also supports extending LookML objects. Extending is useful when you want to create a new copy of an existing view or Explore so that you can add new objects to it. For example, you can create a base view that defines all of your fields, and then create multiple new views that extend the base view. These new views can then be modified to hide certain fields in the base view, or to change definitions or labels for the fields from the base view.

Refinements are useful when you want to modify an existing view or Explore with some tweaks or adjustments to certain objects, but you don’t want to create copies of the view or Explore. Refinements are ideal for situations where you cannot or do not want to modify the base view or Explore, and for situations where creating a new view or Explore would require extensive changes to other LookML references. See the Example section below for an example of this use case.

For most use cases, refinements are a simpler and cleaner alternative to extends.

Refinements Override Parameters

It is important to note that a refinement will override the original settings of an object. In the example below, the original view has a hidden dimension (hidden: yes):

And in another file we’ve added a refinement to that dimension with hidden: no:

The last refinement takes precedent, so hidden: no is applied and the dimension will be displayed in the final view.

Refinements Are Applied in Order

An object can be refined multiple times and in multiple places, which enables Looker developers to use refinements in a lot of creative ways. But this also means that developers have to be very mindful of the order in which refinements are applied:

• Within a project, refinements are applied in the order in which their files are included. Refinements from files included last will override refinements from files included earlier.
• Within a single file, refinements are applied line by line going downwards. Refinements with the highest line number are applied last and will override any earlier refinements, if there are conflicts.

You can use the final: yes flag to verify that your refinements are being applied in the order you expect. See the Using final: yes to Prevent Further Refinements section for details.

For example, in the view file below we have two refinements of the faa_flights view. The first refinement hides a dimension (hidden: yes), and the second refinement displays the dimension (hidden: no). When there are conflicts like this, the refinement furthest down in the file takes precedent:

The logic is similar for including multiple files in a project: Refinements in the last file listed in the includes will take precedent. For example, if we have a model file that includes these files:

Any refinements in the distance_analysis.lkml will be applied first, and then any refinements in the finishing_touches.lkml file will be applied. If there are any conflicts, the refinements in the last file, finishing_touches.lkml, will take precedent.

Because refinements leverage the order of includes, you should not use wildcards in your includes if you want to use refinements. As a general practice, it’s best to avoid using wildcards with views anyway, especially if your project has a large number of view files or if your project uses persistent derived tables (PDTs). But with refinements in particular, using wildcards in your includes is not recommended.

Using final: yes to Prevent Further Refinements

As described above, the same object can be refined multiple times in multiple places, and the last refinement will override all previous refinements.

If you have a refinement that you want to be considered the final refinement for the view or Explore, you can add the final: yes flag to the refinement. The Looker IDE will return a LookML error if there are existing refinements that would be applied after this final refinement, or if a developer tries to add a new refinement that would be applied after this final refinement. For example, the second refinement in this view file would create a LookML error because the previous refinement has the final: yes flag:

Adding the final: yes flag to a refinement is a good way to verify that your refinements are being applied in the order you intend.

Using Refinements in Your LookML Project

Here are the broad steps for refining views and Explores in your project:

1. Identify the view or Explore you want to refine.
2. Decide where you want to house your refinements. You can add refinements in any existing LookML file, or you can create separate LookML files for your refinements. (See the procedure for Creating a Data Test File for an example of creating generic LookML files.)
3. Use the include parameter to incorporate your refinements into your model:
   • In the file where you write your refinements, you must include the files of the LookML that you’re refining. The Looker IDE will give you warnings if you try to refine an object that is not included.
   • In your model file, include the files where your refinements are defined. You can combine files and use includes in very creative ways, see the Using Refinements to Add Layers to Your Model section below.

Example

Refining LookML objects is an easy way to adapt views and Explores without having to edit the original LookML. This is especially handy when your views and Explores are read-only in your project, such as with files imported from other projects. Let’s walk through an example of refining an Explore.

Here is the LookML for the aircraft Explore:

This Explore contains several views, each of which has many dimensions.

Now let’s say that we have another LookML project called e_faa_refined, and this project is importing the aircraft Explore file. In the e_faa_refined project we want to dramatically simplify the aircraft Explore.

Because the aircraft Explore is an imported file, we can’t edit it directly. So let’s add a refinement to it instead. In this case, we’ve created a separate file called refinements.lkml that contains this LookML:

The refinements.lkml file contains the following:

• The include parameter to bring in the original aircraft.explore.lkml file from the imported project (see the Importing Files from Other Projects documentation page for details on how to refer to imported project files).
• Refinements to the aircraft Explore:
  • The + sign in front of the Explore name indicates we’re refining an existing Explore.
  • The label parameter changes the Explore’s label to “Aircraft Simplified”.
  • The fields parameter specifies that only three fields will be displayed in the Explore.

The end result is as if this were our original aircraft Explore and aircraft view:

Other Use Cases for Refinements

As mentioned above, refinements are ideal for adapting LookML objects that are read-only, such as Looker Blocks or imported files.

But once you get a feel for adding refinements and including them in your models, you can do very cool things with your projects, as described in the following examples.

Using Refinements to Add Analysis

You can use refinements to add analysis to your model without touching the original LookML files. For example, say we have a project where our views and Explores are generated from tables in your database and stored in a LookML file called faa_basic.lkml. We can create an faa_analysis.lkml file where we use refinements to add analysis. In this example, we’ve created a new derived table with distance analysis and then joined the derived table into an existing flights Explore. We’ve also refined the existing flights view to add new fields from the analysis:

Using Refinements to Add Layers to Your Model

Another interesting use case for refinements is to add layers to your project. You can create multiple refinement files and then include them strategically to add layers.

For example, in our FAA project we can create an faa_raw.lkml file that contains all the views and Explores generated from tables in your database. This file has a view for every table in the database, each with a dimensions for each database column.

In addition to the raw file, you can create an faa_basic.lkml file to add a new layer with basic refinements, such as adding joins to your Explores, or adding measures to your views, like this:

You can then add an faa_analysis.layer.lkml file to add a new layer with analysis (see the previous section for an example of an analysis file).

From there, we just need to include all of our refinement files into our model file. We can also use our model file to add refinements to point our views at the database tables we want to reference:

You can duplicate this model file and point to different database tables, or you can include different refinement files that you’ve created to define other layers you want in your model.

Using Refinements for PDTs

As described in the Refinements Compared to Extends section above, an extension creates a new copy of the object being extended. In the case of persistent derived tables (PDTs), you shouldn’t use extensions, since each extension of a PDT will create a new copy of the table in your database.

However, you can add refinements to the PDT’s view, since refinements don’t create a new copy of the object being refined.

Things to Consider

When refining an object, be aware that localization rules apply to your refinements as well. If you are refining an object and then defining new labels or descriptions, you should provide localization definitions in your project’s locale strings files. See the Localizing Your LookML Model documentation page for more information.