Choosing a Query Mode

The SQL validator can be run in one of three modes: batch mode (default), single mode, or hybrid mode. You can set the query mode at the command line with the --mode option.


Each query mode has pros and cons. If you're unsure, hybrid mode is a great place to start.

Batch mode

In batch mode (default), Spectacles will run one query for each selected explore. Each query will include every dimension in its corresponding explore.

  • Pros: Spectacles will run fewer queries and usually finishes more quickly, depending on the number of dimensions in your explores.

  • Cons: Because each explore is a single query, you will only see the first SQL error encountered in that query. This means Spectacles may find additional errors once you have fixed the first error.

Single mode

In single mode, Spectacles will run one query per dimension and report an error for each problematic dimension.

  • Pros: Spectacles will return every SQL error, not just the first error (unlike in batch mode). This means you can fix all errors at once without having to run Spectacles in between each fix. Spectacles will also display line-number links to the LookML of each errored dimension, which makes fixing problems faster.

  • Cons: Spectacles may run a large number of queries and may take longer to complete.


Spectacles runs no more than 10 queries at a time to avoid overwhelming your Looker instance. You can change this value with the query concurrency flag.

You can also restrict validation to a specific explore or model to reduce the query load on your instance.

Hybrid mode

In hybrid mode, the Spectacles runs the validator in batch mode to identify the explores with errors. Next, Spectacles runs those errored explores again in single mode to find each errored dimension.

Hybrid mode is a compromise between batch mode and single mode. It takes more time to run than batch mode does, but returns all of the errored dimensions.