Getting started with Looker

Best Practices

Documentation

Community

Training

Certification

Articles in this section

See more

Understanding other project files

Avatar
Looker Support
  • Updated
Follow

A Looker project consists of one or more model files, one or more view files, and possibly the following types of files as well:

An in-depth explanation of model and view files is given on the Understanding model and view files documentation page. The rest of the file types are described in the sections below.

For information on accessing a project’s files, see the Accessing and editing project information documentation page.

Project files are organized by your Looker developers using folders in the IDE.

Dashboard files

Looker supports two types of dashboards:

  • User-defined dashboards, which can be created by non-developer users without using LookML. For details, see the Creating user-defined dashboards documentation page.
  • LookML dashboards, which are stored as version-controlled files that are associated with the project.

If your project contains LookML dashboards, they will be defined in dedicated dashboard files in the IDE.

For more information on LookML dashboards, see the Creating LookML dashboards documentation page.

Document files

Looker document files let you write documentation or other notes about your Looker data model using GitHub-flavored Markdown. This can be helpful for your users to become acquainted with how your organization uses Looker.

Creating document files

To add a document file to your project:

After you create a file you can edit it by clicking Edit in the upper right. Then you can preview your changes by clicking Preview, or save your changes by clicking Save.

Viewing the document outside the IDE

To see a document outside the IDE, which you will need to do to take advantage of the navigation features described below, choose the View Document option from the drop-down menu in the upper left:

You can distribute the URL of the resulting page to other users so that they don’t need to navigate through Looker’s developer section to reach it.

Adding a navigation structure to your document

You can add a sidebar to your document files so that users can easily see the structure of the information and navigate between documents:

To add sidebar navigation for a document, create a navigation section starting on the first line of the document. Mark the start and end of your navigation section with three dashes (---).

You can use the following parameters in the navigation section:

navigation

At the minimum, you can use navigation: true on a document to add the navigation sidebar to that document. Here’s how it looks in a Markdown file:

This adds to the document a navigation sidebar with links to all the project’s documentation pages. If you include only navigation: true in a document, the sidebar of that document lists all the project’s documentation pages in alphabetical order by filename.

Also, you might find that organizing by alphabetical filename is not ideal, or you may have some documents you don’t want to show in a page’s navigation:

If you want to change the order of files in a document’s navigation sidebar, or if you want to show only a subset of your documents in the sidebar, you can use this format:

---
navigation:
  - document_one
  - document_two
  - document_three
  - document_four
---

So now the page will show only the files you want, and in an order that makes more sense:

title

By default, the sidebar displays the document’s heading (if the document begins with a heading), or the document’s filename if there is no heading in the file. You can add a title parameter at the top of a document to change how the document is displayed in navigation sidebars:

---
title: New Title for Users
---

This title will be used as the link text in the navigation sidebars of all documents unless you specify a different label in the navigation section of a document.

label

If you want to change the way a page is listed in a document’s navigation sidebar, you can use the document and label parameters like this:

---
navigation:
  - document_one
  - document: document_two
    label: Customized Label for Document Two
  - document_three
  - document_four
---

To use the label parameter, you must add the document: before the document filename as shown in the preceding example. If you are not using a label for a document, do not include document: before the filename.

The label value defines how a document is shown in the document’s sidebar navigation, even if the document to which it refers has its own title parameter.

The preceding example looks like this in the document’s sidebar:

section

If you want to break the navigation sidebar into sections, you can use the section parameter like this:

---
navigation:
  - document_one
  - document_two
  - section: My Section Name
  - document_three
  - document_four
---

The section parameter adds a section break and a text heading to the sidebar:

The text heading is not a link itself; it does not refer to any of your documentation files.

Data files

Data files are JSON files with file extension .json, .topojson, or .geojson.

The map_layer parameter lets you use a JSON file as a custom map that can then be used to plot your data in Looker:

You then use the map_layer_name parameter with a dimension so that you can associate a data value (like “Paris”) with a geographic region on your custom map.

You can edit a JSON file in the LookML IDE and then click Save. For debugging, you can choose View Raw to view the file in raw format. If you have the proper extension to view JSON in your browser, you will also have the option to view the file in a Parsed format:

Adding data files

To add a JSON file to your project, use the drag-and-drop feature to upload the file from your computer (see the Uploading files section on the Working with folders in the IDE documentation page for the procedure).

Project manifest files

Your project may contain a project manifest file, which is used for the following tasks:

Model localization is not currently compatible with project import.

Each project can only have one manifest file, and it must be named manifest.lkml and located at the root level of your project’s directory structure and in your Git repo.

Creating a manifest file

To add a project manifest file to your project, use the Create Project Manifest option from the + menu at the top of the Looker IDE file browser (see the Creating files section on the Working with folders in the IDE documentation page for the procedure). This will create a manifest.lkml file at the root level of your project’s directory structure. Do not move the manifest file; it needs to be stored at the root level of your directory structure.

The Create Project Manifest option is available only from the + icon at the top of the file browser in the Looker IDE. It is not an option from the folder menus, since the manifest file must be located at the root level of your project’s directory structure.

Also, the Create Project Manifest option is available only if your project doesn’t have a manifest file already, since a project can only have one manifest file.

Manifest lock files

Manifest lock files are created automatically when a remote dependency is added to the project manifest file. Looker uses the manifest lock file to track the version of the remote project(s) specified in the manifest file:

Looker developers do not need to create or edit a manifest lock file, since lock files are managed automatically by Looker.

For more information, see the Importing files from other projects documentation page.

Locale strings files

If you are localizing your data model you will need to create locale strings files for each locale you want to localize to, including your default locale (for example, often English in the USA).

Locale strings files list key-value pairs for each label and description that you are localizing in your model. The strings file for each locale should provide that locale’s translation for each label or description. More information about creating locale strings files appears on the Localizing your LookML model documentation page.

Creating locale strings files

If you are creating locale strings files to localize your model and would also like to take advantage of Looker’s native UI localization, you must name your strings files using specific locale codes that can be found in the Locale section of our Users documentation page.

To create a locale strings file in your project:

Explore files

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.

Explore files have the file extension .explore.lkml.

Creating Explore files

To create an Explore file in your project:

When creating Explore files:

  • Be sure to use the file extension .explore.lkml
  • Once you create the file in your project, be sure to use the include parameter to make your new file available for referencing in other files in your project. Explore files can be included in views, in models, and in other Explore files.
  • Once you create an Explore file, you can view the objects and navigate to the Explore file using the object browser in the Looker IDE.

Data test files

Your project may have data test files used for verifying the logic of your LookML model. Data tests can be contained in model files or in view files, but if your developers want to use the same data tests across several different models, it may be helpful to keep the data tests in their own, dedicated file.

Creating data test files

To create a data test file in your project:

When creating data test files:

  • Data test files have the file extension .lkml.
  • Once you create the file in your project, be sure to use the include parameter to make your new file available for referencing in other files in your project. Explore files can be included in views, in models, and in other Explore files.

Refinements files

Your project may have files used for LookML refinements. LookML refinements can be contained in model, view, or explore files, or in their own, dedicated file.

Creating refinements files

To create a refinements file in your project:

When creating refinements files:

  • Refinements files have the file extension .lkml.
  • Once you create the refinements in your project, be sure to use the include parameter to make your new file available for referencing in other files in your project.

Other files

Many LookML elements can be housed in different files in your project, or in their own dedicated files. For example, data tests can be housed in model files, view files, or their own dedicated .lkml files.

Creating generic LookML files

To create a generic LookML file in your project:

Once you create the file, be sure to use the include parameter to make your new file available for referencing in other files in your project.