8.9 KiB

Raw Permalink Blame History

Table Monitor Reference

Detailed reference for building createTableMonitorMac tool calls.

When to Use

Use a table monitor when the user wants to:

Monitor many tables at once across an entire database or schema
Track freshness (when was each table last updated?)
Detect schema changes (columns added, removed, or type-changed)
Monitor volume changes (row count anomalies) across a broad set of tables
Apply broad coverage with anomaly detection (no custom thresholds needed)

Do NOT use a table monitor when the user wants to:

Track field-level metrics on a single table (use a metric monitor)
Apply custom thresholds or explicit operators like GT/LT (use a metric monitor)
Validate row-level business rules or referential integrity (use a validation monitor)

Required Parameters

Parameter	Type	Description
`name`	string	Unique identifier for the table monitor. Must be unique across all table monitors in the same namespace.
`description`	string	Human-readable description of what the monitor checks (max 512 characters).
`warehouse`	string	Warehouse name or UUID. Use `getTable` or `search` to find it.
`asset_selection`	object	Asset selection config defining which tables to monitor (see Asset Selection below).

Optional Parameters

Parameter	Type	Default	Description
`alert_conditions`	array of strings	`["last_updated_on", "schema", "total_row_count", "total_row_count_last_changed_on"]`	Metric names to monitor (see Alert Conditions below).
`domain_id`	string (uuid)	none	Domain UUID (use `getDomains` to list).

Pre-Step: Verify Warehouse

Before creating a table monitor, resolve the warehouse name or UUID. The warehouse parameter is required and must match an existing warehouse in the Monte Carlo account.

If the user provides a table name, call getTable to retrieve the table details -- the response includes the warehouse name and UUID.
If the user provides a database or schema name without a specific table, call search with the database or schema name to find assets and identify the warehouse.
Use either the warehouse name or UUID in the warehouse parameter.

NEVER guess the warehouse value. If you cannot resolve it, ask the user.

Asset Selection

The asset_selection object defines which tables the monitor covers. It must include a databases list.

Use database and schema scoping to select which tables to monitor. This is the reliable approach and covers most use cases.

Known limitation: The MCP tool supports filters and exclusions parameters, but the tool's schema describes the wrong format for them. Until this is fixed (K2-269), do not pass filters or exclusions — they will cause errors. Use database/schema scoping instead to narrow the set of monitored tables. If the user needs regex or pattern-based filtering, explain this limitation and suggest either (a) using schema-level scoping to get close, or (b) creating individual metric monitors for specific tables.

Database-Level Selection

To monitor all tables in an entire database, specify only the database name with no schemas list:

{
  "databases": [
    {"name": "analytics"}
  ]
}

This monitors every table in every schema within the analytics database.

Schema-Level Selection

To monitor all tables in specific schemas, include the schemas list:

{
  "databases": [
    {
      "name": "analytics",
      "schemas": ["core", "staging"]
    }
  ]
}

This monitors every table in the core and staging schemas within analytics, but not tables in other schemas.

Multiple Databases

You can monitor tables across multiple databases in a single monitor:

{
  "databases": [
    {"name": "analytics", "schemas": ["core"]},
    {"name": "raw_data"},
    {"name": "reporting", "schemas": ["public", "internal"]}
  ]
}

Alert Conditions

Alert conditions define which metrics the table monitor tracks. The operator is always AUTO (anomaly detection) -- custom thresholds are not available for table monitors.

Metric	Description
`last_updated_on`	Freshness monitoring. Alerts when a table has not been updated within its normal cadence.
`schema`	Any schema change. Alerts when columns are added, removed, or their types change.
`schema_fields_added`	New columns detected. Alerts only when new columns appear in the table.
`schema_fields_removed`	Columns removed. Alerts only when existing columns are dropped from the table.
`schema_fields_type_change`	Column type changes. Alerts only when a column's data type changes.
`total_row_count`	Row count changes. Alerts on anomalous changes in total row count.
`total_row_count_last_changed_on`	Time since last volume change. Alerts when the row count has not changed for an unusual duration.

Notes

All operators are AUTO (anomaly detection). Table monitors do not support custom thresholds like GT, LT, or explicit operators. If the user needs custom thresholds, use a metric monitor instead.
No schedule field. Table monitors do not support the schedule field in MaC YAML. Adding it will cause a validation error on montecarlo monitors apply. Table monitor scheduling is managed automatically by Monte Carlo. Do NOT add a schedule block to the generated YAML.
The default set (last_updated_on, schema, total_row_count, total_row_count_last_changed_on) provides broad coverage and is appropriate for most use cases. Only override the defaults when the user specifically requests a subset.
schema is a superset of schema_fields_added, schema_fields_removed, and schema_fields_type_change. If using schema, there is no need to also include the granular schema metrics.

Examples

Monitor all tables in a database (minimal config)

{
  "name": "analytics_db_monitor",
  "description": "Monitor all tables in the analytics database for freshness, schema changes, and volume",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {"name": "analytics"}
    ]
  }
}

Uses the default alert conditions (last_updated_on, schema, total_row_count, total_row_count_last_changed_on).

Monitor specific schemas with default alerts

{
  "name": "core_schemas_monitor",
  "description": "Monitor all tables in core and reporting schemas",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {
        "name": "analytics",
        "schemas": ["core", "reporting"]
      }
    ]
  }
}

Monitors every table in the core and reporting schemas, leaving other schemas unmonitored.

Monitor multiple schemas across databases

{
  "name": "prod_tables_monitor",
  "description": "Monitor production tables across analytics and raw_data databases",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {
        "name": "analytics",
        "schemas": ["core", "reporting"]
      },
      {
        "name": "raw_data",
        "schemas": ["ingestion"]
      }
    ]
  }
}

Monitors tables in specific production schemas, leaving development and staging schemas unmonitored.

Schema change monitoring only

{
  "name": "warehouse_schema_watch",
  "description": "Track schema changes across the entire data warehouse",
  "warehouse": "production_warehouse",
  "asset_selection": {
    "databases": [
      {"name": "analytics"},
      {"name": "raw_data"}
    ]
  },
  "alert_conditions": [
    "schema_fields_added",
    "schema_fields_removed",
    "schema_fields_type_change"
  ]
}

Monitors only schema changes (not freshness or volume) across multiple databases. Uses the granular schema metrics instead of schema to allow selectively enabling/disabling each type.

Table Monitor vs Metric Monitor

Aspect	Table Monitor	Metric Monitor
Scope	Multiple tables (database/schema level)	Single table
Metrics	Freshness, schema changes, row count	Field-level metrics (null rate, mean, sum, etc.)
Operator	AUTO only (anomaly detection)	AUTO or explicit thresholds (GT, LT, EQ, etc.)
Asset selection	Database/schema with filters and exclusions	Single table specified by MCON or name
Timestamp field	Not required	Required (`aggregate_time_field`)
Segmentation	Not available	Available via `segment_fields`
Best for	Broad coverage, freshness, schema drift	Targeted field-level data quality checks

Rule of thumb: If the user wants to monitor a specific field on a specific table with specific thresholds, use a metric monitor. If the user wants broad monitoring across many tables with automatic anomaly detection, use a table monitor.

8.9 KiB Raw Permalink Blame History