Skip to main content
Instead of defining your monitor placement specifications in the UI, you can also provide a YML file to specify where to place monitors programmatically. This is beneficial if you prefer to manage monitor placement through code, e.g., enforce it through your CI/CD development process.

​
Getting started

  1. Install synqcli from the releases page, or follow the installation instructions for your platform
  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
version: v1beta2 is the current format. A file with no version: key is read as the legacy flat monitors: layout, which exists for compatibility only — do not author new files in it.

​
Configuring a monitor

You can define custom monitor types as code (freshness, volume, custom_numeric, and field_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: is read only under version: v1beta2. A file with no version: key is read as the flat layout, which has no such key — the list is accepted, no rule is created, and synqcli deploy reports success. Declare the version at the top of the file before adding a rule to it.

​
Verifying monitors in the UI

If you navigate to the Settings menu for a monitor, you can verify that it’s created by code by seeing the Monitor was created via API and can't be managed in APP label. title