dq-list-checks

Instructions

Implementation Reference

• src/tools/quality-results.ts:14-56 (handler)

  Main handler function for dq-list-checks. Builds a SQL query to list recent rows from DQ_RESULTS_TABLE, applying optional filters for dataset, status, type, and a time window. Supports two schema flavors (generic/us-all) via column mapping.

  export async function dqListChecks(args: z.infer<typeof dqListChecksSchema>): Promise<unknown> {
    const flavor = getDqFlavor();
    const cols = getDqColumns(flavor);
    const backend = config.dq.backend;
    const filters: string[] = [];
    const params: unknown[] = [];
    if (args.dataset) {
      filters.push(`${cols.dataset} = ?`);
      params.push(args.dataset);
    }
    if (args.status) {
      filters.push(`LOWER(${cols.status}) = ?`);
      params.push(args.status);
    }
    if (args.type) {
      filters.push(`${cols.checkType} = ?`);
      params.push(args.type);
    }
    filters.push(tableTimeWindowSql(flavor, backend, "HOUR"));
    params.push(args.sinceHours);
    const where = "WHERE " + filters.join(" AND ");
  
    const checkNameSelect = cols.checkName
      ? cols.checkName + " AS check_name"
      : `(${cols.checkType} || ':' || COALESCE(${cols.tableName}, '')) AS check_name`;
  
    const sql = `
      SELECT ${checkNameSelect},
             ${cols.checkType} AS check_type,
             ${cols.dataset} AS dataset,
             ${cols.tableName} AS table_name,
             ${cols.status} AS status,
             ${cols.severity} AS severity,
             ${cols.failureCount} AS failure_count,
             ${cols.runAt} AS run_at,
             ${cols.message} AS message
      FROM ${resultsTable()}
      ${where}
      ORDER BY ${cols.runAt} DESC
      LIMIT ?`;
    params.push(args.limit);
    return { ...(await dqQuery(sql, params)), schema: flavor };
  }

• src/tools/quality-results.ts:6-12 (schema)

  Zod schema defining input parameters for dq-list-checks: dataset (optional string), status (optional enum pass/fail/warn/error), type (optional string), sinceHours (default 24, range 1-720), limit (default 100, range 1-500).

  export const dqListChecksSchema = z.object({
    dataset: z.string().optional().describe("Filter by dataset / source"),
    status: z.enum(["pass", "fail", "warn", "error"]).optional().describe("Filter by status"),
    type: z.string().optional().describe("Filter by check type (dbt_test | freshness | anomaly | reconciliation | ...)"),
    sinceHours: z.coerce.number().int().min(1).max(720).default(24),
    limit: z.coerce.number().int().min(1).max(500).default(100),
  });

• src/index.ts:100-100 (registration)

  Registration of the dq-list-checks tool with the MCP server under the 'quality' category. Links the schema (dqListChecksSchema.shape) and handler (wrapToolHandler(dqListChecks)) to the tool name.

  tool("dq-list-checks", "List recent rows from DQ_RESULTS_TABLE filtered by dataset / status / type / time window", dqListChecksSchema.shape, wrapToolHandler(dqListChecks));

• src/clients/dq-schema.ts:49-80 (helper)

  Column mapping helper that returns the actual DB column names for the two supported schema flavors (generic and us-all). The dq-list-checks handler calls getDqColumns() to build schema-agnostic SQL.

  export function getDqColumns(flavor: DqFlavor = getDqFlavor()): DqColumnMap {
    if (flavor === "us-all") {
      return {
        runAt: "run_date",
        checkType: "check_type",
        status: "status",
        dataset: "source",
        tableName: "target_name",
        severity: "dimension",
        failureCount: "metric_value",
        message: "details::text",
        checkName: null,
        scoreDate: "run_date",
        scope: null,
        tier: null,
      };
    }
    return {
      runAt: "run_at",
      checkType: "check_type",
      status: "status",
      dataset: "dataset",
      tableName: "table_name",
      severity: "severity",
      failureCount: "failure_count",
      message: "message",
      checkName: "check_name",
      scoreDate: "score_date",
      scope: "scope",
      tier: "tier",
    };
  }

• src/clients/dq-store.ts:114-116 (helper)

  Returns the qualified results table name (DQ_RESULTS_TABLE env var). Used by dq-list-checks handler to construct the FROM clause.

  export function resultsTable(): string {
    return qualifyTable(config.dq.resultsTable);
  }