Skip to main content
Instead of creating monitors in the app, you can define them in YAML files and deploy them with synqcli. This lets you keep monitors in version control and deploy them from your CI/CD pipeline.

Getting started

  1. Install synqcli. On macOS, run brew install getsynq/tap/synqcli. On other platforms, download it from the releases page, or follow the installation instructions
  2. Authenticate. For interactive use, synqcli auth login opens a browser; for CI, set up an by clicking Add client with the following scopes
  • Edit SQL Tests
  • Edit Automatic Monitors
  • Edit Custom Monitors and pass them as QUALITY_CLIENT_ID / QUALITY_CLIENT_SECRET
  1. Run synqcli deploy against your YAML
Every command and flag is in the CLI reference. YAML is one of three ways to manage monitors outside the app. The public API drives the same services directly, and an AI assistant can create and change monitors over MCP. A monitor deployed from YAML stays managed by its config: the app will not edit it, and an MCP write that would overwrite it takes an explicit extra confirmation.

Defining monitors in code

Create a YAML file where you’ll be managing the monitor setup, for example, synq_monitors.yml. You can split your configuration up into multiple files and use namespaces to manage individual domains or data products independently.
Using NamespacesMonitors in one namespace are isolated from those in another, which helps you:
  • Avoid conflicts when multiple teams manage monitors in parallel.
  • Keep different pipelines or environments separate (e.g., transformation models in CI vs. external tables in prod).
  • Apply ownership, defaults, and alerts consistently within a group.
You can define a namespace at the top of your YAML file.
Example content of the file
Start every file with version: v1beta2. A file with no version: key is read as the legacy flat monitors: layout, which is kept for compatibility only. Do not write new files in it.

Configuring a monitor

A monitor’s type: is one of volume, freshness, custom_numeric, field_stats, category_distribution, table_stats or custom_table_stats. Read more about each monitor type.

Field stats columns and metrics

For field_stats, each entry under columns: is either a plain column name or a column with a metrics list. The column must be a string, numeric, integer, float, date or datetime column; any other type rejects the deploy.
  • A plain column name monitors every metric available for the column’s data type.
  • column with metrics restricts what is predicted to the listed metrics.
  • A metric is an id string or { metric, sensitivity }. A metric’s sensitivity (PRECISE, BALANCED or RELAXED) overrides the monitor’s mode.anomaly_engine.sensitivity.
  • A metric must exist for the column’s data type, otherwise the deploy is rejected. A column or a metric listed twice is an error. See metrics by data type.
  • Changing the selection updates the monitor in place: it does not reset the monitor or change its id. A removed metric stops being predicted, and adding it back resumes its history.

Obtaining IDs from the UI

Each entry under entities: is one asset, and its id: is the full table identifier as represented in the platform. You can locate this ID by navigating to a table in the UI (using the catalog or search functionality) and copying the ID from the URL. In the example below, bq-synq-demo::nyc_taxi::financial_statement will be the ID. title

Understanding the configurable parameters

Every configurable parameter, with its type and validation rules, is in the configuration reference. The same schema drives editor autocompletion. Put the # yaml-language-server: line from the example above at the top of your own file. For more examples of configuring individual monitors, see the examples directory.

Covering assets by query instead of listing them

A monitor or test under an entities[].id targets one asset. To cover many assets by a rule instead of naming each one, write a top-level deployment_rules: list: each entry carries a selection, and every asset matching it is covered, including assets that start matching later. A rule’s type: says what it deploys: table_stats for monitors, sql_tests for the tests listed under the rule itself. See deployment rules. deployment_rules: needs version: v1beta2 at the top of the file.

Exporting monitors from the app

To move monitors you created in the app into code, export them to a YAML file:
By default the export writes the monitors created in the app. Use --monitored to limit it to specific tables, --integration to one integration, and --source=all to include monitors created over the API. Every flag is in the CLI reference.

Development and production

To keep development and production apart, use a separate Coalesce Quality workspace for each environment. Keep the YAML in Git, and deploy it with synqcli deploy to each workspace. Each workspace has its own API client, so give your CI job the QUALITY_CLIENT_ID and QUALITY_CLIENT_SECRET of the workspace it deploys to. If table names differ between environments, select the tables with a deployment rule resolver_ql query that matches in both workspaces. Or keep one file per environment, and pass only that file to synqcli deploy. To start from the monitors you already have in a workspace, export them first.

Verifying monitors in the UI

Open the Settings of a monitor. A monitor deployed from code shows the label Monitor was created via API and can't be managed in APP. title