Usage
Hierarchyinclude - or - include - or - include |
Default ValueNoneAcceptsA string containing a filename or pattern |
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:
In a view file, you can use include
to reference:
In an Explore file, you can use include
to reference:
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 theviews/users/
directory by specifyinginclude: "/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 namede_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 calledaircraft_new.explore.lkml
in theexplores
folder. Because that Explore is defined in its own file, you must specify the Explore file’s path in aninclude
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 aninclude
parameter for it in the model. However, you do need aninclude
for the view on which theaccidents
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.