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:
spectacles sql
tests thesql
field of each dimension for database errors.spectacles content
tests for errors in Looks and Dashboards.spectacles assert
runs Looker Data Tests: expressions that must evaluate toTrue
to pass.
The SQL Validator
The SQL validator runs queries in your data warehouse to verify the sql
field in each dimension is valid.
You must specify the Looker project and Git branch to validate.
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 using the --explore
and --exclude
options. These options require the model and explore name, delimited by /
. The wildcard *
is also accepted. Here are some examples.
Only Explore A
All explores in Model A
Every explore named Explore A across all models
Explore A and Explore B
All explores in Model A except for Explore B
tip
Have some dimensions you'd like to exclude? Read about ignoring dimensions in Spectacles.
Query modes
You can run the SQL validator in different modes which affect how Spectacles builds SQL queries. This tutorial won't go into the different modes (the default approach is one query per explore) but you can read more about choosing a query mode here.
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 must specify the Looker project and Git branch to validate.
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.
Selecting and excluding
You can select and exclude specific models and explores using the same syntax as you did with the SQL validator.
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. Add the flag --exclude-personal
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 must specify the Looker project and Git branch to validate.
Selecting and excluding
You can select and exclude specific models and explores using the same syntax as you did with the SQL and Content validators.
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:
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.