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.

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.

Limitations of content validation​

If you delete an explore or model or change its name, Spectacles doesn't currently return these "dangling" content errors because we can't distinguish between explores that were excluded and explores that are missing. (Track issue on GitHub)

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 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.