Getting Started

What you'll achieve

By the end of this tutorial, you'll be able to use Spectacles to check the validity of the SQL defined in the dimensions of your Looker project.

Set up a local environment

We recommend creating a separate folder and Python virtual environment for Spectacles.


If you already have a preferred approach for creating a Python virtual environment, you can skip this step!

  1. Create a folder called spectacles.
  2. Create a Python virtual environment for Spectacles. If you don't already have a preferred way of doing this, we recommend pyenv-virtualenv. Follow the instructions to install pyenv and pyenv-virtualenv. Then, from your spectacles folder, run the following:
pyenv virtualenv 3.8 spectacles && pyenv local spectacles

Install Spectacles

Once you've created and activated your virtual environment, run the following to install Spectacles:

pip install spectacles

Create an API key in Looker


If you already have a Looker API key and know where to find it in Looker, you can skip this step!

  1. From Looker, go to Admin > Users.
  2. Find your user, click Edit, then under API3 Keys click Edit Keys.
  3. Generate a new API key by clicking New API Key.

You should have a client ID and client secret that look something like this:

Client ID: 4x2vgxNvCD3RYDM05gna
Client Secret: KDDwdDMm8MXyrJNqXBchbdmY

Set up a config file

In your spectacles folder, create a file named config.yaml with the following contents:

# Replace with the URL of your Looker instance
# Replace with the actual values from your API key
client_id: 4x2vgxNvCD3RYDM05gna
client_secret: KDDwdDMm8MXyrJNqXBchbdmY

Spectacles will use this config file so you don't have to type out these parameters every time.

Test Spectacles connection to Looker

Once you've saved your credentials to file, test the connection to Looker by running the following:

spectacles connect --config-file config.yaml

If the connection test is successful, you should see a message confirming your API and Looker instance version.

Connected to Looker version 7.8.18 using Looker API 3.1

Run the SQL Validator

You're ready for the final step! To run the SQL Validator, you'll need:

  • The name of your Looker project
  • A model and explore to test
What's the name of my Looker project?

Projects are listed at the bottom of the Develop menu in Looker.

Replace your project name, model name, and explore name (separated by a /) below, then run this command to launch the SQL Validator.

spectacles sql \
--config-file config.yaml \
--branch master \
--project my_project \
--explores my_model/my_explore

If your explore is free of SQL errors, you'll see something that looks like this.

============= Testing 1 explore [batch mode] [concurrency = 10] ==============
✓ eye_exam.users
Completed SQL validation in 2 seconds.

Congratulations! If Spectacles identified any SQL errors in your explore, try fixing them and re-running the validator.