Usage

Definition

The include parameter specifies the LookML files that will be available to a model, a view, or an Explore. If you want to use or reference a LookML file within another file, you must add it with the include parameter.

You can use the include parameter in model files, view files, and Explore files. The include parameter can reference different types of LookML files, depending on the context.

In a model file, you can use include to reference:

• View files
• Dashboard files
• Explore files
• Data test files

In a view file, you can use include to reference:

• View files
• Explore files
• Data test files

In an Explore file, you can use include to reference:

• View files
• Explore files

You can also use include to bring in files from other projects. See the Importing files from other projects documentation page for information on including files from another project. To import files from local LookML projects, you must enable the Local Project Import Labs feature.

Note the following when using include:

• You don’t need to use include for non-LookML file types, such as documentation files or data files.
• Including files is all-or-nothing, so all the included file’s information is added to the including file.
• You can use multiple include parameters in a file.
• You can use the * wildcard character to indicate files with strategic naming conventions or with the same extension. For example, you can use "*base.dashboard" to match and include both "database.dashboard" and "crunchbase.dashboard". You can use "*.dashboard" to indicate all files with the extension .dashboard.
• You can use the * wildcard character to include all files in a directory. For example, you can include all view files in the views/users/ directory by specifying include: "/views/users/*.view". See the documentation page on IDE folders for more information on using wildcards with IDE folders.

Handy Tip: When using wildcards, you can check which files are included by hovering over the information icon in the change bar of the file, or by clicking on the include statement and looking in the quick help:

Using include in a model file

You can use the include parameter in a model file to include views and dashboards or Explores.

Including views and dashboards in a model

Use the include parameter in a model file to specify the dashboard and view files that will be available to that model. If you want to use or reference a LookML file within a model, you must add it with the include parameter.

In the include parameter, use the extension .view for view files and the extension .dashboard for dashboards. You can leave out the .lkml and .lookml part of these extensions.

You can use the * wildcard character to indicate files with strategic naming conventions or with the same extension. You can also use the * wildcard in combination with directory paths to specify multiple files, as described in the Wildcard examples section of the IDE folders documentation page.

For example, you could use these include parameters in a model file:

These parameters would include the following files:

• All dashboard files in any directory in your project
• Any view files that end with base.view.lkml in any immediate child directory of the project, such as /views/database.view.lkml or /public/crunchbase.view.lkml
• All view files in the /views/ directory of the imported project named e_commerce

If your project has a large number of view files or if your project uses persistent derived tables (PDTs), you should avoid including all view files in your model. Instead, include individual view files like this. Here’s an example of including individual view files and all dashboards in a project:

Including models in a model

You cannot include a model file from another project. Instead, to reuse, refine, or extend Explores across projects, in the imported project you can create a separate Explore file, then include that Explore file in other projects. See Including Explores in a Model for more information.

Including Explores in a model

Explore files will listen to the connection of the model they are included in. Consider this fact when you include Explore files in models that are configured with a connection that is different from the Explore file’s parent model. If the schema for the including model’s connection differs from the schema for the parent model’s connection, it can cause query errors.

Explores are usually defined within a model file. However, sometimes you need a separate Explore file for a derived table, or to extend or refine an Explore across models.

If you do have a separate Explore file, you need to use the include parameter in the model file to include it. In the include parameter, use the extension .explore.lkml for Explore files.

For example, below is a model file that has two Explores:

• The aircraft_new Explore, which is defined in its own file called aircraft_new.explore.lkml in the explores folder. Because that Explore is defined in its own file, you must specify the Explore file’s path in an include parameter.
• The accidents Explore, which is defined within the model file. Because it is defined in the model file itself, you don’t need to use an include parameter for it in the model. However, you do need an include for the view on which the accidents Explore is based.

Including data tests in a model

Data tests can be defined directly in a model file or a view file. However, you can also create a separate data test file if you want to reuse your data tests in multiple places in your project.

If you do have a separate data test file, you need to use the include parameter in your model file or view file so that you can run the data tests. In the include parameter, use the extension .lkml for data test files.

For example, below is an excerpt from a model file that includes a data test file:

Once you include the data test file in a model file, you can run the data test to verify that your data test works properly and to see if your model’s logic passes the test.

You can also include the data test file in a view file, as described on theIncluding data tests in a view section on this page.

Using include in a view file

For the most part, you don’t need to use include in a view file. However, there are some cases in which you do want to include files in your view file:

• If you are extending or refining a view
• If you have an Explore file for a derived table

Including views in a view (to extend or refine)

You can also include a view file in another view file to extend or to refine the included view.

For example, here is the marketing_order_fields view file that includes the basic_order_fields view file and then extends it:

Including Explores in a view

Explore files will listen to the connection of the model they are included in. Consider this fact when you include Explore files in models that are configured with a connection that is different from the Explore file’s parent model. If the schema for the including model’s connection differs from the schema for the parent model’s connection, it can cause query errors.

In most cases, you don’t need to include an Explore in a view. However, native derived tables are a special case because they are defined in their own view file that has an explore_source parameter. You use the explore_source parameter to specify an Explore and define the desired columns and other desired characteristics for the native derived table. Explores are usually defined within a model file, but in the case of native derived tables it may be cleaner to create a separate file for the Explore using the .explore.lkml file extension. If you create a separate Explore file, you must include the Explore file in the native derived table view file.

Here is an example of using include in a native derived table view file to point to an Explore file:

See our documentation on using include statements to enable referencing fields for more information on Explore files for native derived tables.

Including data tests in a view

Data tests can be defined directly in a model file or a view file. However, you can also create a separate data test file if you want to reuse your data tests in multiple places in your project.

If you do have a separate data test file, you need to use the include parameter in your model file or view file so that you can run the data tests. In the include parameter, use the extension .lkml for data test files.

For example, below is an excerpt from a view file that includes a data test file:

Once you include the data test file in a view file, you can run the data test to verify that your data test works properly and to see if your view’s logic passes the test.

You can also include the data test file in a model file, as described on the Including data tests in a model section on this page.

Using include in an Explore file

Explores are usually defined within a model file. However, sometimes you need a separate Explore file for a derived table, or to extend or refine an Explore across models.

If you do have a separate Explore file, you can use the include parameter to include views or other Explores.

Including views in an Explore

If you have a separate Explore file, you need to include any views that are used by the Explore. Use the file extension .view for view files. You can leave out the .lkml part of the file extension. Here is an example Explore file that includes the two views it’s using:

Including Explores in an Explore

Explore files will listen to the connection of the model they are included in. Consider this fact when you include Explore files in models that are configured with a connection that is different from the Explore file’s parent model. If the schema for the including model’s connection differs from the schema for the parent model’s connection, it can cause query errors.

You can include one Explore file in another Explore file, such as when you are extending or refining an Explore. Use the include parameter and add the file extension .explore.lkml.

Here is an example Explore file that includes another Explore file and then extends the Explore:

Examples

See the previous sections for examples of using include in model files, view files, and Explore files.

Things to consider

Using wildcards

For projects where only a few files need to be managed, you can list each file in its own include parameter, like this:

Bur for projects with many files to include, you can reduce the number of include parameters that you need to write by using wildcards to include several files at once:

• Use wildcards with IDE folders to include files in a specific directory of your project.
• Use wildcards with file extensions to include files of a specific file type.
• Use wildcards with strategic filenames to include files with specific prefixes or suffixes in their filenames.

Using wildcards may be especially helpful during development when you need to create a temporary fix for LookML validation warnings, especially when organizing an existing project into IDE folders. But take the following into consideration when using wildcards in your include statements:

• Looker does not recommend the use of wildcards to include all view files in a project, since including all view files can affect the performance of LookML validation and can clutter your database schema.
• Looker does not support the use of wildcards to include all files in a project if the project has multiple model files, since model files cannot be included in other model files.

Using wildcards with IDE folders

You can use wildcards in combination with IDE folders to include files in a specific directory in your LookML project.

For example, this include statement references all the files in the /explores/ directory of a LookML project:

Using wildcards for specific file types

You can use wildcards to reference all files of a specific type. For example, this include statement references all Explore files in a LookML project:

See the Project File Types section of the LookML Project Files documentation page for a list of the types of LookML files and their file extensions.

Looker does not recommend the use of wildcards to include all view files in a project, since including all view files can affect the performance of LookML validation and can clutter your database schema.

Using wildcards with strategic naming patterns

You can also use wildcards with strategic file naming to further optimize your include statements. For example, instead of naming files like this:

You can add a strategic prefix or suffix to your filenames, like this:

Then use wildcards to reference only the .fruit suffix by using this include:

Including all view files can affect performance of LookML validation

If your project has a large number of view files and you include them all in your model file, this may affect the performance of the LookML Validator. Since the LookML Validator checks all the view files included in the model, you should include only the needed view files in the model file’s include parameter.

Consider using strategic naming conventions for view files to enable easy inclusion of groups of views within a model (see the example in Using wildcards with strategic naming patterns on this page). Or, you can use IDE folders to organize your views into folders. Then you can use the * wildcard to include all views in a single folder, instead of including all views in your project. See our documentation on using include with IDE folders for information.

Including all view files can clutter your database schema

For projects that use persistent derived tables (PDTs), you can include the PDT’s view file in your model file. However, each model file that includes the PDT’s view file will create a copy of the PDT in the scratch schema on your database. If you have multiple model files and you include all view files in your model files, you may add unnecessary clutter to your database scratch schema. For this reason, be sure that you include a PDT’s view file only in the model files where the PDT is needed.