Spectacles

Overview

This documentation provides a detailed guide on integrating Spectacles.dev with Paradime to enhance continuous integration (CI) workflows for your dbt project hosted on GitHub.

This integration enables automated LookML testing and seamless deployment processes, ensuring high code quality and reliability. Spectacles runs a test suite, but instead of testing production data, it tests data in the Turbo CI schema that reflects the output of your dbt™️ changes.

Prerequisites

Before proceeding, ensure the following prerequisites are met:

• Active Spectacles.dev account

• Spectacles.dev GitHub app installed in your GitHub account with access to your dbt repository.

• Paradime GitHub app installed in your GitHub account with access to your dbt repository.

• Paradime Scheduler connection configured with target name: ci

• Paradime Bolt Turbo CI configured in your Paradime workspace.

Paradime Turbo CI configuration

• Generates Full dbt Project Output: The Turbo CI run must produce the complete output of your dbt project. If you are using the modified state in your Turbo CI configuration, the initial step should clone your production schema into the target schema for each run See the example below:

Turbo CI dbt commands

dbt clone --target ci
dbt build --select state:modified+ --target ci

LookML configuration

You will need to configure schema references in our LookML using a user attribute, allowing Spectacles to modify the sql_table_name in your views. This adjustment will direct Looker to query the Paradime Turbo CI-generated staging data instead of the production data.

This guide details the steps required to make these changes to your LookML.

Spectacles configuration

Set user attributes

For each user attribute you'd like to modify in Spectacles, you'll need to configure it with a default value on the Spectacles Settings page.

Here are the steps in Spectacles:

1. In the top-right, click Settings ⚙️.

2. Scroll down to the Looker Settings section.

3. Under User attribute, input the name of the user attribute that controls the schema in your LookML.

4. Under Default value, input the name of schema you use for production. For non-dbt Cloud runs, Spectacles will use this value.

5. Click Update Settings.

Want to know more about using user attributes with Spectacles? Find our guide to user attributes here.

Set up a new Suite​

Follow these steps to create a new Suite that triggers SQL validation whenever a pull request is opened and Paradime Turbo CI complete successfully.

1. Navigate to Suites

   • In the top menu, click Suites.

   • Click New Suite.

2. Create a Simple Suite

   • Name your Suite: Paradime PRs.

3. Configure Triggers

   • Leave all the options unchecked as Paradime will trigger the Suite on completion of a Paradime Turbo CI.

   • In the Schema User Attribute field, select the user attribute created in Looker.

4. Configure the SQL Validator

   • Explores to query: Leave the default setting unless you need to specify models using the model selection syntax.

   • Explores to exclude: Leave the default setting.

   • Fail fast: Select Yes.

   • Query concurrency: Leave the default setting.

   • Uncheck Is Enabled for both the Content Validator and the Assert Validator.

5. Finalize the Suite

   • Click Create Suite.

Your new Suite is now set up to trigger SQL validation whenever a pull request is opened and Paradime Turbo CI completed successfully .

Connect Spectacles.dev to your Paradime workspace

What you need to configure the Spectacles integration?

1. Get your Spectacles API key: You can generate or replace your API key in the Settings page for your Spectacles organisation.

Only one API key can be active at a time, so save your API key somewhere securely when generating it. If you lose it, you'll need to replace it with a new key.

1. To retrieve the below information navigate to the suite you have created in the previews step that you want to trigger on the back of a Paradime Turbo CI run and copy the Url in you browser, it will look something like this:

https://app.spectacles.dev/org/pN9xfJfvcH6crAG0lyl4/proj/tYEXxrhFnkDJWv9gidAI/suites/ppRIWcoQLkcf6B5Ay78d/update

• Get your Spectacles Org ID: This will be the first ID after org/ in your spectacles.dev url. In the above example, the org id is pN9xfJfvcH6crAG0lyl4.

• Get your Spectacles Project ID: This will be the second ID after proj/ in your spectacles.dev url. In the above example, the projected id is tYEXxrhFnkDJWv9gidAI.

• Get your Spectacles Suite ID: This will be the third ID after suites/ in your spectacles.dev url. In the above example, the Suite id is ppRIWcoQLkcf6B5Ay78d.

1. Get the Looker Schema User Attribute name: This has been previously set in Looker for your views in the sql_table_name. Based on the Spectacle.dev guide you might have called this dbt_schema.

1. Get the Paradime scheduler connection schema value: This value corresponds to the schema name field set in the connection used to execute Paradime Turbo CI.

Setup the Spectacles integration in your Paradime workspace

To finalize the Spectacles integration in Paradime, you need to configure a set of environment variables within the Paradime workspace.

Use the predefined environment variable names as listed below:

Environment Variable Name	Environment Variable Value example
SPECTACLES_API_TOKEN	eyJhbGci0Mwyjdb5srBdDsAVOKdN5E
SPECTACLES_ORG_ID	pN9xfJfvcH6crAG0lyl4
SPECTACLES_PROJECT_ID	tYEXxrhFnkDJWv9gidAI
SPECTACLES_SUITE_ID	ppRIWcoQLkcf6B5Ay78d
SPECTACLES_CI_LOOKER_SCHEMA_NAME_KEY	dbt_schema
SPECTACLES_CI_LOOKER_SCHEMA_NAME_VALUE	ci

For additional Looker User attributes, add more envrionment variables in the workspace settings as: SPECTACLES_LOOKER_USER_ATTRIBUTE_<user_attribute_name> = <value>