Skip to main content
A custom SQL monitor tracks a metric you define in SQL and learns its usual pattern over time. For example, you can:
  • Track the average of a numeric ML feature over time.
  • Track average revenue by region, to see a sudden increase or drop in one region.
  • Track the number of new unique users in a source table, to catch a problem before it reaches downstream models.
A custom SQL monitor detecting an anomaly in the average sales price for one region title

​
Setting up a custom SQL monitor

  1. Navigate to the table or transformation model (dbt model, SQLMesh model, Coalesce node) where you want to set up the monitor and click Add Monitor title
  2. Select Custom SQL to start creating a custom SQL monitor title
  3. Configure the monitor with the relevant settings title
    • SQL metric: an aggregate SQL expression that returns one number, for example avg(revenue).
    • Time partition: the timestamp column that splits the data into periods, for example creation_date.
    • Delay: the number of recent periods to skip, if fresh data arrives late. See Time dimensions and scheduling.
    • Detection mode: see Detection modes below.
    • Sensitivity: see Configuring monitor sensitivity.
    • Custom filter: a SQL condition that limits the rows the metric is computed on.
  4. Select a variable to segment by (optional). This will create multiple time series for each segment you select to include
    • To create a monitor for specific segments, toggle Selected values and select the desired values.
    • If you select All values, new values are automatically added.
    title
    Be careful with segments that have only a few data points. The model cannot learn a reliable range for them, which can lead to many false positive alerts.
  5. Click continue to set up the monitor with the specified configurations title
The monitor will appear shortly and can be found directly under the table you created it for and on the
A custom monitor splits your data into time partitions by the selected timestamp column, and each partition is one point in the time series. On its first run, the monitor reads the recent history of the table. After that it queries only the newest partition, to keep query costs low. This means the monitor can detect anomalies right after you set it up.

​
Detection modes

Custom SQL, custom volume and custom freshness monitors support three detection modes:
  • Anomaly detection learns the expected range from the history of the metric and alerts when a value falls outside it. This is the default, and the only mode that uses sensitivity.
  • Numeric change alerts when the value changes by more than the minimum or maximum you set between two measurements in a row.
  • Fixed thresholds alerts when the value is below the minimum or above the maximum you set.
In the two threshold modes, leave the minimum or the maximum empty to check one side only. Each mode has its own severity.

​
Resetting a monitor

If you changed historical data and want the monitor to learn it again, open the monitor, click Settings, and press Reset monitor. A reset cannot be undone, so only reset if you are sure.