Making The Most Of Your Spectacles Trial

Making The Most Of Your Spectacles Trial

When getting started with Spectacles, we want to make sure you can hit the ground running. Typically as part of the trial, there are a few primary goals:

1. Cleaning up existing SQL errors in your project(s)
2. Turning on Spectacles checks on pull request
3. [Optional] Getting the dbt integration set up

As with any tools, there’s lots of different ways you can choose to do this, but we’ve found the following ordering and steps to be most effective for organisations getting started with the Spectacles

Cleaning up existing SQL errors in your project(s)

One of the first things you’ll want to do is clean up any existing SQL errors in your project. This is for two reasons. Firstly, people could be trying to use those fields and getting errors, which you want to avoid. Secondly, having a project clean of SQL errors is the way to get the shortest run-times of Spectacles on pull requests, even if you’re running the SQL validator incrementally.

To clean up your errors, we recommend doing the following:

1. Create a new suite that runs just the SQL validator. Make sure you set the SQL validator to run in “fail-fast” mode. You can read more about fail-fast mode here. Without fail-fast mode, the runtime of the SQL validator scales with the number of errors in your project. Initially, depending on the number of errors you have, this can take a little bit of time. Running in fail-fast mode allows us to quickly understand which explores in the project have errors.
2. From the Suites page in the app, click “Create Run” on this new suite and kickoff a run against production. This run will return the first error we encountered for each errored explore.
3. If about five explores or fewer have an error, follow the following steps, otherwise go to step 4.
   1. Create another suite to run the SQL validator without fail-fast mode turned on (leave fail fast unticked).
   2. Go to the suites page and kick off a run of this suite against production. This will find all these errors in your errored explores.
   3. Resolve the errors: You can either fix the errors but resolving whatever the issue is or you can comment out any errored fields until you are ready to fix them. To confirm you have resolved them successfully, commit your code and kick off another run of this suite against development mode and select the branch with your fixes.
4. If greater than five explores have errors, follow the following steps.
   1. Create another suite to run the SQL validator without fail-fast mode turned on (leave fail fast unticked). In order to be able to get the results quickly for each explore, we recommend testing the explores one at a time, so in the Explores to Validate text box, use the syntax model/explore to define the explore you want to test. You should pick one of the errored explores from the prior steps.
   2. Go to the suites page and kick off a run of this suite against production. This will find all these errors in the explore you selected.
   3. Resolve the errors: You can either fix the errors but resolving whatever the issue is or you can comment out any errored fields until you are ready to fix them. To confirm you have resolved them successfully, commit your code and kick off another run of this suite against development mode and select the branch with your fixes.
   4. Once you have resolved the errors, restart this sequence by testing the next explore, until all explores have their errors resolved.
5. Congratulations! You should now have a LookML project clean of all SQL errors!

Turning on Spectacles checks on pull request

Ultimately, you want to catch errors in your LookML before they get to production. The best way to do this is to run Spectacles on each code change/pull request.

You can turn this for the Content Validator, Style Validator and Assert Validator (assuming all your data tests pass) right away. Once your project is clean of SQL errors you can enable the SQL validator as well.

1. Enable the GitHub or Gitlab integration in the settings page (top-right corner of the application).
2. Create a new suite.
   1. Select “Trigger on pull requests from Looker” in the triggers section.
   2. Enable the Content Validator to run. Make sure to select the “incremental” option. This means that it will also show errors on a pull request that are caused by changes in that pull request.
   3. [Optional] Once all SQL errors are cleaned up, enable the SQL Validator to run. Make sure to select the “incremental” option. With this option, Spectacles will only test explores that have changed, which can significantly speed up runtimes.
   4. [Optional] If you are using data tests in Looker, enable the Assert Validator to have Spectacles run your data tests.
   5. [Optional] If you would like to enforce a style guide on your LookML, enable the Style Validator.
3. Create a new pull request, you should see Spectacles statuses on the pull request, notifying you of which tests are running.

Congratulations! Your Looker project will forever now be pristine!

[Optional] Getting the dbt integration set up

While many people leave this step until after their trial, you may want to test our dbt integration right away.

To do so, we have detailed instructions for you to follow which you can find here.