Generating a model

This page provides the steps to create a new project and automatically generate a basic model from your database.

There are other options for creating your project files: you can create a blank project and manually create its model, or to clone an existing public Git repository, see the Creating a new LookML project documentation page.

Automatically generating a model from your database

You can automatically generate a model from your database within the Develop section of Looker or using the Create button in the left navigation panel.

Generating a model from within the Develop section

  1. Click Develop in the left navigation panel and verify that you are in Development Mode.

  2. Select Projects from the Develop section in the navigation panel.

  3. From the LookML Projects page, select New LookML Project:

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

  4. In the New Project dialog, specify the options for your project:

    • Project Name: Give your project a name. Choose the project name carefully and consider it a permanent ID for the project, since Looker uses the project name in the following ways:

      • To identify the project for API calls that have the project_id parameter.
      • To identify the project in the Looker instance's internal database.
      • To identify the project for local project import.
      • To display the project on the LookML Projects page.
      • To display the project in the Develop section of the Looker navigation panel.
      • As part of the URL for project files. For example, on a Looker instance with a URL of example.looker.com, the project manifest file for the project named ecommerce can be found at this URL: https://example.looker.com/projects/ecommerce/files/manifest.lkml.

    • Starting Point: Choose Generate Model from Database Schema.

    • Connection: From the drop-down menu, select the name of your database connection.

    • Build Views From: Select one of the following options:

      • All Tables: The LookML generator creates a view file for each table in your database.
      • Single Table: The LookML generator creates a view for one table in your database. If you choose this option, enter the name of the database table.

    • Schemas: To generate files for only one schema in your database, enter the name of the schema in the Schemas text field. You can list multiple schemas, separated by commas.

    • Ignore Prefixes: To leave table prefixes out of your view filenames, enter your database's prefixes in the Ignore Prefixes field. This field is case-sensitive. You can list multiple prefixes, separated by commas. For example, your tables are titled dwh_orders and DBS_users. If you enter dwh, DBS in the Ignore Prefixes text field, then Looker creates view files named orders and users.

  5. Click Create Project.

    • The LookML generator creates one model file for the project, and a view file for each table in the database (unless otherwise specified). Then, Looker opens the new project in the Looker IDE.
    • The LookML generator creates IDE folders for your view and model files. If your database has more than one schema, the LookML generator creates a folder for schemas.

For BigQuery connections, if you generate a LookML project from your database, Looker autopopulates field descriptions with the descriptions from your BigQuery column metadata, if any.

The generator also creates an Explore for each database table. To start querying your data, use the Explore panel to select the name of an Explore.

To rename your project after you've created it, see the Renaming a project section of the Accessing and editing project information documentation page.

You can manually create additional new models for your project as described on the Understanding model and view files documentation page, configure them for use in production as discussed in the When you need to configure models section on this page, and find further instructions on the Creating a new LookML project documentation page.

After your model files are generated or manually created, see the Setting up and testing a Git connection documentation page for information on connecting your Looker project to Git. You can record changes to your LookML files and manage versions of your files.

Generating a model using the Create button

To create a project and generate a model using the Create button, follow these steps:

  1. Click the Create button in the left navigation panel.
  2. Select the LookML model menu option.
  3. Verify that you are in Development Mode.
  4. Once you are in Development Mode, the Create a Project page opens.
  5. If you want to select base views for Explores, or customize other advanced options such as ignoring table prefixes in generated view file names, importing field description metadata from the database, determining model file creation, and selecting auto-generated readme files, enable the Advanced Project Creation option.
  6. Select a database connection from the Select database connection drop-down menu. If you have access to any projects that already use the connection, they appear once the connection is selected. You can choose to use an available project and add a new model to it, or create a new LookML project. If you choose to add the model to a project, a Create Model section appears as the first step on the Create a Project page, where you can name the model. Once you have made your selections, click Next.
  7. In the Select Data section, select the schemas, tables, and fields to use in the model. Views will be created from the tables. Once you have made your selections, click Next.
  8. Select a primary key for each table. This helps Looker better join your tables together. Once you have made your selections, click Next.
  9. If you enabled the Advanced Project Creation option, select the base views for Explores. Select each view that you want to use as the base view for an Explore. For each selected view, the system will automatically join as many other views as possible. Only views that have a primary key identified in the previous step can be used in a join. Once you have made your selections, click Next.
  10. If you enabled the Advanced Project Creation option, make the following selections in the Advanced Options section:
    • Ignore Prefixes - To ignore the table prefixes in generated view file names, enter the database's prefixes in a comma-separated list in this field. This field is case-sensitive. You can list multiple prefixes, separated by commas. For example, your tables are titled dwh_orders and DBS_users. If you enter dwh, DBS in the Ignore Prefixes text field, then Looker creates view files named orders and users.
    • Field descriptions - Select the Import field description metadata checkbox to use any available field descriptions in the database as LookML descriptions for generated dimensions.
    • Model file handling - Choose whether or not to create a model file. If you choose to create a model file, enter the name you want for the file in the Model Name field.
    • Getting started guide - Select the Generate a Readme file that describes how to use the output checkbox to generate a Readme file that describes how to use the project.
  11. Click Generate Model to generate the project files. Looker takes you to the files in the Looker IDE once they are generated.

Improved LookML generation

If your Looker admin has enabled the Improved LookML Generation Labs feature, Looker adds additional elements to your project when you generate the project from your database:

  • Looker adds a README file to the new project. The README file contains an introduction to LookML along with links and resources to help new LookML developers.
  • Looker adds several inline comment explanations to the model file and to each view file.
  • If a view has at least one dimension of type: number that does not contain the string id in its name, Looker creates a measure of type: sum and a measure of type: average, both of which are based on the alphabetically first dimension of type: number that does not contain the string id in its name.

When you need to configure models

Configuring a model is useful for the following reasons:

  • It specifies that a given model name refers to a particular model in a particular project.
  • It sets the connections that the model is allowed to use.

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

Although a LookML developer specifies the intended connection in the model file, an admin controls what connections are allowed on the LookML Projects page. If a model specifies using a connection that is not allowed in the model's configuration, then the connection is not allowed.

A model must have a configuration in the following scenarios:

  • When a model is pushed to production for the first time. If the model is not configured, any queries on that model fail once the model is in Production Mode. When a model is pushed from Development Mode to production for the first time, Looker configures the model automatically if the model's name is unique for the Looker instance. However, if you have a configured model with the same name in another project, then Looker does not automatically configure the model.
  • During development. If you have developers who were not given either the manage_models permission (which is included in the admin role) or the manage_project_models permission, then the model must be configured before those developers can run queries on that model. You can configure the model before the model exists or before the project exists. Then, when a LookML developer creates the project and the model, the model's allowed connections are already configured, and the developer can run queries successfully.

Looker lets developers who have either the manage_models or the manage_project_models permission run queries on an unconfigured model in Development Mode. Looker does this by searching projects for a model with that name. The first model found with that name is used to run the query.