Editing and validating LookML

Using the IDE

This page describes some of the Looker IDE features that can assist you in writing LookML.

You can access the Looker IDE (integrated development environment) through the Looker Develop menu. See Accessing project files for details and other options.

Autosuggest

As you type, the IDE suggests possible parameters and values that are sensitive to the context of what you are typing. For example, the suggestions for a dimension's type parameter will only include valid options for that parameter. Also, fields in sql parameters have to be marked with ${...}, so the IDE adds that syntax when suggesting fields.

Autosuggest automatically appears wherever it can be shown. To close it, press the Esc key on your keyboard. To view it at any point, press Ctrl+Space (Windows) or Control-Space (Mac).

Ad hoc error checking

The IDE catches syntax errors as you type. A red X in the gutter indicates a syntax error, which is underlined in red. When you hover over the red X, a short description of the problem appears. For example, if you mistakenly type avrage instead of average as the value of the type parameter for a measure, the IDE displays the error Invalid value for "type":avrage.

The LookML Validator is still required to perform a full model validation. Some errors, such as an invalid field reference due to a missing join, require a holistic look at the model and therefore are only surfaced when the LookML Validator is run.

Quick Help panel

Select the Quick Help icon to open the Quick Help panel, which provides explanations and options for the current location in the code. Select a parameter name in the sidebar to open the Looker documentation page for that parameter.

Note: You can also use the metadata panel to view contextually relevant information about the objects in the Looker IDE metadata panel. See the Metadata for LookML objects documentation page for more information.

Automatic formatting

When you are in Development Mode, you can use the format file keyboard shortcut to automatically indent your LookML file. The indentation indicates the hierarchy of parameters and subparameters, making your LookML easier to read and understand.

Folding

A small arrow appears in the gutter next to the start of each top-level LookML parameter in the file. Selecting this arrow folds or unfolds that section of LookML so that you can focus on just particular sections.

The See file actions menu for the LookML file also provides Fold LookML and Unfold LookML options to expand or collapse all LookML sections down to the top-level parameter within the current file.

You can also use keyboard shortcuts to fold and unfold LookML.

Marking additions, changes, and deletions

In the LookML IDE, several indicators are always displayed when you are in Development Mode and have uncommitted changes.

• The file's name is displayed with a blue dot in the left side of the window to indicate that the file is new, changed, or renamed.
• When you open a new or changed file, the line numbers inside the file are highlighted in green to show new or changed lines, and a horizontal red line indicates removed lines.

Adding comments

You can add comments to your LookML to make it more readable. To add a single comment, use the # character:

dimension: name {
  sql: ${TABLE}.name ;; # This is the customer's full name
}

You can comment out an entire block of code using keyboard shortcuts by performing these steps:

1. Select the lines that you want to comment out.
2. Press Command + / (Mac) or Ctrl + / (Windows).

The IDE will add the # character to each of your selected lines.

Commenting out SQL blocks

If you are commenting out lines that are entirely within a SQL code block, manually add SQL comment notation.

When you use the SQL comment block, the commented-out sections will still be interpreted as LookML code. Therefore, you will see your comments within LookML-generated SQL, but the comments won't affect the query results.

Jump to object or file

In the Looker IDE, you can do a quick search to navigate directly to LookML objects and project files by using the Jump to object or file feature. Click the Jump to object or file icon from the file browser or the object browser, or use the keyboard shortcut Command-J (Mac) or Ctrl+J (Windows).

See the Accessing LookML project files documentation page for more information.

Finding and replacing text in your project

The Looker IDE has a find and replace function, which you can use to search all your project files for text and then replace all instances or selected instances in a bulk operation.

Tip: The Looker IDE find and replace is a great tool for locating LookML elements in large LookML projects and for replacing text in descriptions and labels. If you want to search and replace in your project for the names of models, Explores, and fields, use the Content Validator's find and replace function instead. Changing the names of models, Explores, and fields can break references within your model, and the Content Validator can validate your LookML references and fix errors in your LookML after making these types of changes.

To use the Looker IDE find function, follow these steps:

1. Navigate to the search panel in the IDE.
2. Enter a term in the Find field.
3. Optionally, you can select Case Sensitive to search only for instances that match the case you entered in the Find field, or select RegEX to perform a regular expression search.
4. Select Find.
5. Optionally, you can select a file's name to open that file in the IDE.

If you are in Development Mode, you will also see the Replace With field. To replace text in your project, follow these steps:

1. Enter replacement text in the Replace With field. Optionally, you can leave the Replace With field blank if you want to delete the text in the Find field instead of replacing it.

2. Select Select & Replace to preview how your text would be replaced in your project.

3. The results show all instances in your project highlighted for replacement. You can use the following options to customize which instances are replaced:

   • Use the checkbox next to the results summary to select or deselect all instances across your entire project.
   • Use the checkbox next to a single instance to select or deselect that instance.

4. Select the Replace Selected button to apply the replacement to the instances you've selected. The IDE will show the changes that were made.

Creating and testing new fields

As an example of editing LookML, we'll add several fields and then test them.

Creating a dimension

First we will add a new dimension to our users view that determines if a user is from either California or New York. The dimension will be type: yesno, which means it will return Yes if the user is from California or New York, and No if not.

The LookML for our new dimension looks like:

dimension: from_ca_or_ny {
  type: yesno
  sql: ${TABLE}.state = "California" OR ${TABLE}.state = "New York" ;;
}

Add this dimension to the user view file, and then click the Save Changes button in the file.

Check out substitution operators to learn more about ${TABLE}.state.

Creating a measure

Next we will add a new measure to our user view that averages the age of our users. This measure will be type: average and aggregate over the column age.

The LookML for this new measure looks like:

measure: average_age {
  type: average
  sql: ${TABLE}.age ;;
}

Add this measure to the user view file, and then click the Save Changes button in the file.

Testing the fields in the Explore

You can test your new dimension and measure by querying them. After you save your changes, these fields will appear in the field picker in the Explore. Use the See file actions drop-down menu next to the view filename to easily access the Explore for the current view. The See file actions drop-down menu lists any Explores that are based on the view, including Explores that the view is joined to. As an example, to access the Explore for a view called users, you can select the Explore Users option from the See file actions drop-down menu.

In the Users Explore, you can select the new fields to add them to a query. For example, you can create a query with both of the new fields that shows the average age of users who are from California or New York and the average age of users who are not:

Note: You must be in Development Mode to access these new fields until you have committed and pushed your changes to production.

Validating your LookML

When you are satisfied with your updates, you can save your changes. The IDE will alert you to any unresolved syntax errors within a single file.

Next, use the LookML Validator to perform a full model validation. Some errors, such as an invalid field reference due to a missing join, require a holistic look at the model and therefore are only surfaced when the LookML Validator is run. Be sure to validate your LookML changes before publishing them to the production environment. Although validation will not catch every issue, such as database permission issues, it will prevent most errors.

Note: The LookML Validator should not be confused with the Content Validator, which instead checks to see if the changes you've made will break any saved Looks.

The LookML Validator scans only LookML files that have been updated since the last LookML validation, or files that are affected by updates:

• If a model-level setting changes, everything is validated again.
• If a view changes, only the Explores where it is used are validated again.
• If an Explore changes, only that Explore is validated again.

Tip: If you notice that the LookML validation takes a long time to complete, the first thing to check is the include parameter in your model file. If you include all your view files (include: "*.view"), the LookML Validator will have to check them all, which can affect performance. If this is the case, update the model file's include parameter so that only the needed view files are included.

Running validation

To run the LookML Validator, select the Validate LookML button at the top right of the Looker IDE; or select the Project Health icon at the top of the IDE to open the Project Health panel, and then click the Validate LookML icon.

After you run the LookML Validator, you may see a list of errors and other warnings that you should address. You can select any arrow to expand the lists of errors or warnings.

The validator button in the Project Health panel will become available again if you make and save another change.

Validation messages

Looker displays validation messages after running validation on your LookML.

Note: LookML dashboards show informational messages, rather than warnings, in the sidebar when permissive localization is enabled.

No LookML errors found

When there are no issues found by the validator, Looker displays a green checkmark along with the text No LookML errors found.

LookML errors

LookML errors are issues that could prevent queries from running. The number in parentheses is the number of errors found (nine in the following example):

Within the expanded list of issues you will see the reason validation didn't pass. Often times, if you click on the error, it will bring you directly to the problem row of code. You'll see a red "X" next to the row. Hovering over it will provide more detailed error information in some cases:

Chat Team Tip: The validation error we are asked about most is "Unknown or inaccessible field." Visit the Error: Unknown or inaccessible field Best Practices page for the causes and what to do about it.

LookML warnings

LookML warnings may not prevent a query from being run, but they may still result in broken or unintended functionality for your users. As with errors, the number in parentheses is the number of warnings found (three warnings in the following example):

As with LookML errors, you can expand warnings and jump to the problem code by selecting the warning in the Project Health panel and then hovering over the red X icon to view more information:

Deploying your changes

After you've validated that your changes will work properly, you can use Looker's Git integration to commit and deploy your changes to production.

Note: If you change field names that serve as filters in your Looks or dashboards, be sure to review the Filters section of your scheduled Looks and dashboards and update the filters as needed to reflect your changes. If a scheduled content delivery includes filters that no longer function (for example, if the referenced field has changed), the scheduled delivery could expose unfiltered data.