User Guide Getting Started Help Center Documentation Community Training
Looker
Managing Projects

A project is a collection of LookML files that describe how your database tables are related to each other and how Looker should interpret those tables. You can learn more about projects on the LookML Projects and Developer Mode page and on the LookML Terms and Concepts page.

This page explains how to create a project, rename a project, and configure a model in a project.

Viewing Lists of LookML Projects

There are two basic categories of projects:

The projects you see in those lists depends on the following things:

To view the LookML Projects page, click the Develop menu and choose Manage LookML Projects.

Renaming a Project

Once you have created your project, you can always go back and change the project name using the project’s Project Settings page:

  1. Verify that you have Development Mode turned on.
  2. Navigate to your project in the Develop menu.
  3. In the project, select Project Settings from the Git drop-down menu.
  4. In the Project Settings page, use the Name field to edit the name of your project.
  5. To save the new project name, click Save Project Settings.

When You Need to Configure Models

Configuring a model is useful for the following reasons:

A model configuration is not needed for admins (or developers with the manage_models permission) while they are in Development Mode. This lets Looker developers work easily while in Development Mode. However, if a model configuration does exist, any queries will be constrained by that configuration even in Development Mode.

Although a Looker developer specifies the desired connection in the model file, an admin controls what connections are allowed on the LookML Projects page. Thus, a model should only use a connection that the configuration allows because the configuration always wins. If a model specifies using a connection that is not allowed in the model’s configuration, then the connection is not allowed.

The LookML Projects page lets you view all of your projects in one place, along with their respective models. You use this page to create, view, and configure your projects.

A model needs a configuration when pushing the model to production for the first time, and during development:

For developers without manage_models permission, admins can limit their access to certain connections by limiting the developers to particular model sets and limiting the connections allowed for those models.

For developers that have the manage_models permission, Looker allows them to run queries on an unconfigured model in Development Mode. Looker does this by searching projects for a model with that name. The first model it finds with that name is used to run the query.

Existing Projects and Their Models

In the top section of the LookML Projects page, you can see certain existing projects. In Production Mode, you see projects that have been generated and pushed to production. In Development Mode, you see projects that you have pulled from production or generated yourself in your Development Mode.

To see a project, you must have the manage_models permission, or have the develop permission for at least one model in the project.

If you have the manage_models permission, you can add or edit the configuration for any model listed under the projects.

To specify a new project or a new model for an existing project, see the sections Creating a New LookML Project and Configuring a Model.

Viewing the Listing for a Project

Below you can see an example of the project listings in the Projects section. Each element of a project listing is described below.

Project Name

This is the name of the project. Each project may have one or more models listed next to it. You can click on the project name to navigate to the LookML for that project. If the project uses the older YAML-based LookML, that is indicated next to the project name.

Models

The set of LookML model files for the given project.

If your Development Mode environment differs from production, this list can change between Development Mode and Production Mode. For example, if you might have created a new model in Development Mode that you have not yet pushed to production.

Configuration Issues

If there is a problem with a model, the model will show a status indicating the problem with the configuration.

Issue Explanation
LookML model file doesn’t exist yet You see this issue if someone configured a model on this page but has not yet created a corresponding LookML file for it.
Configuration required for use You see this issue if someone created a new LookML model file in an existing project, but has not configured it on this page yet.
Connection ‘x’ does not exist The connection declared in the model file does not exist (such as if someone misspelled it or has not created it yet).
Model ‘x’ is not allowed to use connection ‘y’ The connection declared in the model file is not permitted according to the configuration on this page.
A model named ‘x’ is already configured in project ‘y’ Model names must be unique within your Looker instance, even if they are in different projects.

Adding and Editing Configurations

If the Configure button is available next to the project’s listing, you can add or edit the project’s model configuration.

If the model does not have a configuration, when you click Configure, Looker displays the Configure a Model page. On the Configure a Model page, you can specify the model name, project name, and specify which connections are available to the model:

If the model does have a configuration, when you click Configure, Looker displays the Edit Model Configuration page. On the Edit Model Configuration page, you can change which connections are available to the model:

You can view the model name but not rename it. Models are named according to the filenames you use in the Models section of the Looker IDE.

In the Project field, you can specify that the model should be associated with a different project. For example, if you created a new project including a model with the same name, you can transition the model configuration to be associated with the new project’s model.

In the Allowed Connections field, you can limit the model to use a list of specific connections, or you can allow the model to use any connection (all current and future connections).

Deleting a Project

Clicking the Delete Project button will remove all LookML from the project, in all development and production environments across your Looker instance.

Please be certain you want to delete a project before you do so. It cannot be undone and is difficult and laborious to recover.

A deleted project will no longer appear in the Projects section of the LookML Projects page, but will still appear in the Configured Projects section.

To remove the project configuration, which will remove the project from your development environment completely, select the project from the Develop menu, click on the Git menu and select Project Settings, then click Delete Project.

Projects with Only a Configuration

The Pending Projects section contains models that are configured with a project name, but not yet generated.

Thus the Pending Projects section contains projects and models that are only configured, that do not yet have any LookML.

Configuring models before the project exists is useful if you have developers who have not been given the manage_models permission. Because the model has already been configured, those developers will be able to run queries as soon as they create the project and that model. When the project is generated, the listing for that project moves to the top section of the LookML Projects page.

Viewing the Listing for a Project

Below you can see an example of the Pending Projects section. The elements of this section are described below.

Project Name

This section lists projects that are configured but not yet generated, so the project name in this field is the intended name of the project when it is later generated. Clicking the project name takes you to the New Project page where you can generate that project. You must be in Development Mode to reach the New Project page.

Models

This is the model name that was specified when creating the model configuration.

Allowed Connections

The column to the right of the model name shows the connections that were allowed for this model when creating the model configuration.

Editing a Configuration

The Configuration button lets you change the project name and the connections that are permitted for this model. Click it to edit the model configuration.

On the Edit Model Configuration page, you can change which connections are available to the model. You can view the model name but not rename it.

You can also specify that the model should be associated with a different project. For example, if you created a new project including a model with the same name, you can transition the model configuration to be associated with the new project’s model.

Adding LookML to a Project

The Add LookML button opens the New Project page for that project, letting you use the LookML generator to automatically generate LookML based on a set of tables in your database.

Creating a New LookML Project

From the LookML Projects page, you can create a new LookML project:

Looker can create a project in several ways, based on the Starting Point option you choose. The following sections describe how these starting points work:

If you want to rename your project after you’ve created it, use the Project Settings page (see the Renaming a Project section).

Automatically Generating a Model from Your Database

If you select Generate Model from Database Schema as the starting point, the LookML generator automatically creates your model and view project files based on the tables in your database. See the Generating a Model documentation page for more information.

With this option, Looker asks for the connection name so that it can automatically generate LookML based your database. However, you can still add additional connections later.

Cloning a Public Git Repository

If you select Clone Public Git Repository as the starting point, Looker will copy the files from a public Git repository into your new LookML project.

Looker projects that are cloned from public Git repositories are read-only. However, you can use the Project Import Labs feature to import the read-only project into another of your Looker projects where you can edit the files. Additionally, you can use the cloned repository files as a starting point, then use the Looker extends function to build up a project from there.

To clone an existing public Git repository into a Looker project:

  1. Verify that you are in Development Mode.
  2. Click the New LookML Project button at the top of the LookML Projects page.
  3. In the New Project pop-up window, give your project a name.
  4. For Starting Point, choose Clone Public Git Repository.
  5. Enter the URL for the public Git repository. Make sure that the URL is the in format git://github.com/example/my-repository.git.

    If you have a URL such as https://github.com/llooker/blocks_redshift_admin, you can edit it to the correct format by replacing “https://” with “git://” and then adding “.git” at the end. So the URL you would enter would be: git://github.com/llooker/blocks_redshift_admin.git.
  6. Click Create Project. Looker will pull all of the public repository’s files into a new LookML project and open the project.
  7. Click Deploy from Remote to pull all remote changes into your local version of the repository.

Creating a Blank Project

If you select Blank Project as the starting point, Looker creates an empty project so that you can create your LookML files from scratch.

To create a blank project:

  1. Verify that you are in Development Mode.
  2. Click the New LookML Project button at the top of the LookML Projects page.
  3. In the New Project pop-up window, give your project a name.
  4. For Starting Point, choose Blank Project.
  5. Click Create Project.

Once you have a blank project, you can create model and view files, then you can connect your project to Git so that you can record changes to your LookML files and manage versions of your files.

Configuring a Model

Use the Configure New Model button at the top of the LookML Projects page to add a configuration for an existing or planned model.

Configuring a model for a project that doesn’t exist yet is useful if the developers have not been given the manage_models permission. If you configure the model for them, the developers will be able to run queries as soon as they generate or create the model file.

You can also specify which database connections can be used by the model, or you can specify that the model is allowed to use any current or future connections. Looker developers use the LookML connection parameter to specify in the model file which connection the model should use. If a developer specifies a connection that you have not allowed in the model’s configuration, then any query on that model will not run.

Top