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 this tutorial page and on the LookML Terms and Concepts page.
This page explains how to configure a model in a project. Configuring a model:
- Specifies that a given model name refers to a particular model in a particular project
- Sets which connections the model is allowed to use
Although a developer specifies the desired connection in the model file, an admin controls what connections are allowed on the LookML Project 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.
LookML Projects lets you view all of your projects in one place, along with their respective models. You use this page to view and configure your projects.
When You Need to Configure Models
When Pushing a Model to Production The First Time
In production mode, the model must be configured or else any queries on that model will fail.
When a model is pushed from development mode to production for the first time, Looker often is able to configure it for you automatically. This is possible when the model's name is unique for the Looker instance. However, if you already have a configured model with the same name in another project, then Looker will not automatically configure the model.
If you have developers who have not been given the
manage_modelspermission (which is included in the
adminrole) then the model must be configured before those developers can run queries on that model.
In this case, you can configure the model before the model exists or even before the project exists. Then when a developer creates the project and the model, the model's allowed connections are already configured and the developer can run queries successfully.
For developers without
manage_modelspermission, admins can limit their access to certain connections by limiting the developers to particular model sets and limiting the connections allowed for those models.
However, Looker allows anyone who has been given the
manage_modelspermission 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.
Accessing the LookML Projects Page
To access the LookML Projects page, click the Develop menu and choose Manage LookML Projects.
Effect of Permissions
Each user may see a different list of projects and models on this page, based on their permissions.
Effect of Development Mode
You may see additional entries on this page when you view it in development mode versus production mode. For example, if you created a new model in development mode that you have not yet pushed to production then that model would be visible only when you are in development mode.
A model configuration is not needed for admins (or developers with the
manage_models permission) while they are in development mode. This lets 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.
Viewing Existing Projects and Their Models
The projects listed in the Projects section are limited to those projects that:
If you are in production mode, then the project must have been generated and pushed to production. If you are in development mode, then you pulled the project from production or you generated the project in your development mode.
Have at least one model that you are allowed to develop
developpermission for a model set that includes at least one model in the project. Alternatively, having the
manage_modelspermission gives you permission to view the project.
On the LookML Project page, anyone with
manage_models permission can add or edit model configurations for any models listed for the projects. You can choose which connections a model is allowed to use:
- a list of specific connections or
- any connection (all current and future connections)
Specifying a new project or a new model for an existing project is described later on this page.
The Projects section, shown below, is described in the following sections.
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.
The set of LookML model files for the given project.
Please note that 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.
Each model in a project will have a status showing any problems with the configuration.
|OK||This is the desired state|
|Missing LookML Model||You see this issue if someone configured a model on this page but has not yet created a corresponding LookML file for it|
|Not Configured||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
|Model 'x' is not allowed to use connection 'y'||The
|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|
The Type column specifies whether the project uses the older YAML-based LookML or uses New LookML.
Use this link to add a model configuration. On the destination page, you can specify the model name, project name, and specify which connections are available to the model.
Use this link to edit your model configuration. On the destination 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, as described here).
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.
Using 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 Manage 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, click the Edit Configuration link in the project's row in the Configured Projects section, and then click the Delete Model Configuration button.
Viewing Projects with Only a Configuration
The Configured Projects (Ready to add LookML) section contains model configurations that were specified with a project name where the project has not been generated yet.
Thus the Configured Projects (Ready to add LookML) 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 Projects section.
The Configured Projects section, shown below, is described in the following sections.
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.
This is the model name that was specified when creating the model configuration.
These are the connections that were allowed for this model when creating the model configuration.
This link lets you change the project name and the connections that are permitted for this model.
Creating New Projects and Model Configurations
Use the buttons at the bottom of this page to generate a project or configure a model.
Configuring a New LookML Project
Use the New LookML Project button to create a new project using the LookML generator. You must be in Development mode to create a new project.
Looker asks for the connection on this page so that it can automatically generate LookML based on a set of tables in your database. However, you can still add additional connections later.
The LookML Type field only appears if the YAML-based LookML legacy feature is on. In this field, you can specify whether you want the project to use New LookML or the older YAML-based LookML. If the legacy feature is off (the default setting) then the project will be created using New LookML. For more information about the benefits of using New LookML, see this article.
Configuring a Model
Use the Configure a Model button to add a configuration for an existing or planned model.
Configuring a model for a project that doesn't exist yet is useful when the developers has not been given the
manage_models permission as they'll be able to run queries as soon as they generate or create the model file.
You can also specify which database connections are allowed to be used by the model or specify that the model can use any current or future connections. If a developer uses the LookML
connection LookML parameter in the model file to specify a connection that is not allowed in the model configuration, then any query on that model will not run.