Skip to main content

Validators

What you'll achieve​

By the end of this tutorial, you'll understand the different Spectacles validators and will be able to run each of them on your Looker project.

What is a validator?​

Spectacles is composed of Validators which run different checks against your Looker instance.

Spectacles supports the following validators:

  • The SQL Validator tests the sql field of each dimension for database errors.
  • The Content Validator tests for errors in Looks and Dashboards.
  • The Assert Validator runs Looker Data Tests: expressions that must evaluate to True to pass.

Validators are enabled and configured on the Suite page, which defines the tests that Spectacles runs against your Looker instance.

The SQL Validator​

The SQL validator runs queries in your data warehouse to verify the sql field in each dimension is valid.

Selecting and excluding​

By default, Spectacles will run SQL validation on all models and explores in your instance.

You can select or exclude specific models and explores. These options require the model and explore name, delimited by /. The wildcard * is also accepted. Here are some examples.

Only Explore A

model_a/explore_a

All explores in Model A

model_a/*

Every explore named Explore A across all models

*/explore_a

Explore A and Explore B

model_a/explore_a, model_a/explore_b
tip

Have some dimensions you'd like to exclude? Read about ignoring dimensions in Spectacles.

Fail fast​

By default, Spectacles will test for all dimensions with errors in the selected models and explores.

If you check Fail fast, the SQL Validator will only return the first error it finds in each explore. This is a helpful trade-off if you would like the run to complete quickly and don't need to know about every dimension with SQL errors.

Incremental mode​

In incremental mode, Spectacles will ignore any SQL errors that are already present in production. This is helpful if you only want to see SQL errors introduced by your branch changes.

Read more about incremental mode in our tutorial on incremental validation.

The Content Validator​

The Content Validator identifies content (Dashboards and Looks) that have errors. Often, these errors are due to missing references to LookML fields.

Like the SQL Validator, you can specify models and explores to include or exclude.

tip

Unlike the Looker Content Validator, which validates an entire Looker instance, the Spectacles Content Validator only displays errors caused by models and explores in the specified project.

Excluding content from validation​

In addition to selecting and excluding based on LookML, you might only want to see errors in shared content, ignoring errors from users' personal content. Check the box on the Suite page to exclude that content.

For more control, you can include or exclude specific folders and their subfolders by ID. To obtain the ID of folders from the Looker IDE, navigate to the desired folder and look at the URL. For example, the URL https://spectacles.looker.com/folders/8 corresponds to folder ID 8.

If you include and exclude folders in the same suite, excluding takes precedence, for the designated folders and for all subfolders.

Incremental mode​

In incremental mode, Spectacles will ignore any content errors that are already present in production. This is helpful if you only want to see content errors introduced by your branch changes.

Read more about incremental mode in our tutorial on incremental validation.

Limitations of content validation​

If you delete a model or change its name, Spectacles doesn't currently return these "dangling" content errors because we can no longer associate them with the project being tested.

The Assert Validator​

The Assert Validator runs any Looker Data Tests that you've defined and returns all failures and errors.

Like the SQL Validator, you can specify models and explores to include or exclude.

Writing LookML Data Tests​

note

If you already have data tests defined in your project, you can move on to the next section!

LookML data tests allow you to validate the logic of your Looker model. Data tests are great for testing complex assumptions like:

  • Revenue in May of last year should equal $204,259
  • Conversion rate should be greater than zero
  • Order status should not be null

Each data test is made up of a small native derived table and an assertion expression. Here's an example:

test: historic_revenue_is_accurate {
  explore_source: orders {
    column: total_revenue { field: orders.total_revenue }
    filters: [orders.created_date: "2019"]
  }
  assert: revenue_is_expected_value {
    expression: ${orders.total_revenue} = 626000 ;;
  }
}

Write a simple LookML data test for your project. You can test it out in Looker if you'd like. Once you have it working, try running it via Spectacles.

The Style Validator​

The Style Validator identifies LookML that doesn't match your team's stylistic preferences, like dimensions missing descriptions or view names that aren't snake-cased.

Configure a deploy key​

You'll need to add a deploy key to your repository, so Spectacles can read your LookML and scan it for style violations. Follow the steps in this short guide to create and upload a deploy key, then come back.

Create a configuration file​

Next, let's create a configuration file in your Looker project that chooses one of our predefined style rules to test with.

On a new Git branch called lkmlstyle, create a new file called lkmlstyle.yaml in the root of your Looker project's repository.

caution

You won't be able to do this in the Looker IDE, you'll need to either a) clone the repository to your local machine, create a new branch, then add and commmit the file; or b) create the file through your version control system's web editor (like github.dev).

If you try to add this file in Looker's web UI, Looker will append a .lkml to the file extension and it won't be recognized by Spectacles.

Add the following line to your new lkmlstyle.yaml file:

select: [V100]

This will select a single rule, V100, ignoring all others. V100 checks to see that all view names are in snake case (e.g. fct_orders, not fctOrders, FctOrders, or FCTORDERS).

We'll start with a single, view-level rule so we don't overwhelm you with errors at the beginning, but you can add more rules as you go by adding their codes to the select list in your configuration file.

You can view a table of all possible style rules.

Commit the file and make sure it's pushed to your lkmlstyle branch. Now, if you start a manual run in Spectacles on this branch, it will use the configuration as defined in your file.

To do that, navigate to the Suites page, find or create a Suite with the Style Validator enabled, and click Create Run. Select Development Mode to test a dev branch, or test Production directly.

Customize the default rules​

You can also customize any rule using your configuration file.

Let's modify the rule D100, which checks for yesno-typed dimensions that don't start with "is" or "has", so it allows dimensions that start with "was."

First, you'll need the YAML definition of the rule, which we can find in the public repository spectacles-ci/style-validator-rules.

Create a new key in your YAML file called custom_rules and copy the YAML definition for rule D100 into that section, as follows:

select: [V100]
custom_rules:
  - title: Yesno dimension doesn't start with 'is_' or 'has_'
    code: D100
    rationale:
      Wording the name of a **yesno** dimension as a question makes it clear
      to the user what a yes or no value represents.
    select:
      - dimension
    filter:
      - type: ParameterFilter
        parameter_name: type
        value: yesno
    regex: ^(?:is|has)_
    negative: false
    type: PatternMatchRule

This rule is a PatternMatchRule, which uses regex to check defined parts of the LookML project. Add D100 to the list of rules to check, and modify the rule definition to allow "was."

We'll change the regex from regex: ^(?:is|has)_ to regex: ^(?:is|has|was)_, and update the title to match. Here's the final rule definition:

select: [V100, D100]
custom_rules:
  - title: Yesno dimension doesn't start with 'is_', 'has_', or 'was_'
    code: D100
    rationale:
      Wording the name of a **yesno** dimension as a question makes it clear
      to the user what a yes or no value represents.
    select:
      - dimension
    filter:
      - type: ParameterFilter
        parameter_name: type
        value: yesno
    regex: ^(?:is|has|was)_
    negative: false
    type: PatternMatchRule

The next time your run the Style Validator, Spectacles will use your custom rule definition for D100 instead of the default one.

If you'd like to learn more about custom style rules, you can read about them in detail on our reference page.

Incremental mode​

In incremental mode, Spectacles will ignore any style violations that are already present in production. This is helpful if you only want to see style violations introduced by your branch changes.

Read more about incremental mode in our tutorial on incremental validation.

The LookML Validator​

The LookML Validator runs Looker's LookML Validator and returns any syntax issues with your LookML.

You or your teammates may want to write LookML outside of the Looker IDE. If you autogenerate LookML or use an external IDE like VSCode or Vim to write LookML, you may accidentally commit some LookML with syntax errors (like a missing } or invalid reference ${}).

Usually, when developing in Looker's IDE, Looker catches these errors when you click "Validate LookML" before committing. This isn't as seamless in external development environments.

Instead, you can have Spectacles run the LookML validator to identify these errors.

Setting a severity threshold​

Looker returns syntax issues at three levels of severity: info, warning, and error. Spectacles will always display all syntax issues, regardless of severity. By default, the validator will fail for any warnings or errors, but not for info messages. You can change this by setting the severity threshold for this validator.

Congratulations! Now you know how to run the SQL, Content, and Assert Validators in Spectacles and how to specify explores or models to test.