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

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.

spectacles sql --config-file config.yaml --branch master --project my_project

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

--explores model_a/explore_a

All explores in Model A

--explores model_a/*

Every explore named Explore A across all models

--explores */explore_a

Explore A and Explore B

--explores model_a/explore_a model_a/explore_b

All explores in Model A except for Explore B

--explores model_a/* --exclude model_a/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.

spectacles content --config-file config.yaml --branch master --project my_project
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.

spectacles content \
--config-file config.yaml \
--branch master \
--project my_project \
--exclude my_model/this_one_always_breaks

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.

spectacles content \
--config-file config.yaml \
--branch master \
--project my_project \
--exclude-personal

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.

spectacles content \
--config-file config.yaml \
--branch master \
--project my_project \
--incremental

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.

spectacles assert --config-file config.yaml --branch master --project my_project

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.

spectacles assert \
--config-file config.yaml \
--branch master \
--project my_project \
--exclude my_model/this_one_always_breaks

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.