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 cheeck Fail fast, the SQL Validator will only return the first errored dimension 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.

info

If you're coming from the CLI, running with Fail fast is the same as runnning in batch mode. The default is the same as running in hybrid mode.

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 personal folders

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.

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.

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