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​

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

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

You can also specify a specific branch (or commit) to test.

spectacles sql --config-file config.yaml --project my_project --branch dev-branch-abc123

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 option. This option requires 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/*" model_a/explore_b
tip

On some shells, like zsh, the * character gets treated as a file globbing wildcard, with causes unexpected results for Spectacles. You might see an output like:

zsh: no matches found

If that happens, you need to wrap your model_name/explore_name strings in quotes, like --explores "model_a/*".

tip

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

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 to validate. Spectacles tests production by default.

spectacles content --config-file config.yaml --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 \
  --project my_project \
  --exclude my_model/this_one_always_breaks

You can also select and exclude content by folder ID. The folder ID is the last number in the URL when viewing a folder in Looker, e.g. https://spectacles.looker.com/folders/298. To exclude a folder, prepend a dash - before the folder ID.

spectacles content \
  --config-file config.yaml \
  --project my_project \
  --folders 25, 321 -33, -249, -250, -252

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 \
  --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 \
  --project my_project \
  --branch dev-branch-abc123 \
  --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 to validate.

spectacles assert --config-file config.yaml --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 \
  --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.

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.

spectacles lookml --config-file config.yaml --project my_project

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.

spectacles lookml --config-file config.yaml --project my_project --severity error

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