Semantic Reporting

Semantic reporting lets AgentQ combine filters, grouping, counts, and history requests through a shared query interface. It is the default reporting interface in full AgentQ chat and MCP. Ask a question in ordinary language; AgentQ discovers the relevant schema and prepares the structured request.

The query interface works with Qualytics metadata and permitted evidence. It does not execute SQL you supply, return bulk source records, or change your assets.

Discover a Resource

Call describe_query_schema without a resource to list the available resources. Then pass a resource name, such as anomalies, to discover its supported fields, metrics, defaults, lifecycle rules, and limits. Only permitted fields and projections are advertised.

Resources include datastores, containers, fields, quality checks, check templates, anomalies, detection-time failed checks, operations, recurring schedules, tags, datastore groups, integrations, stored container and field quality scores, anomaly and partition comments, curated container/anomaly history, and daily insight series (platform_insights, datastore_insights, container_insights, field_insights, quality_check_insights). Integration metadata requires the Manager or Admin role and supports a category filter, such as alerting or ticketing. Other datastore-owned resources require the Reporter team permission on the datastore.

The following examples show the plan argument to query_qualytics. Discover the live schema before composing a request: a field available on one resource is not necessarily available on another.

Filter and Count by Tag

Datastores, containers, fields, quality checks, and anomalies support tag.name and tag.id filters. To answer “How many fields have the tag Compliance applied?”:

{
  "resource": "fields",
  "mode": "aggregate",
  "where": {"field": "tag.name", "op": "eq", "value": "Compliance"},
  "metrics": ["field_count"]
}

This is a server-calculated count of distinct fields you can access. Multiple matching tags do not count a field more than once. Field metadata remains available for masked, excluded, or missing fields; filter status as well if you want a narrower set.

Use eq for an exact tag name or ID, in for any of several names or IDs, and contains for a case-insensitive substring of a tag name. Put separate tag predicates inside all to require all of them. Tags are filters here; they cannot be selected as columns or used as grouping keys.

The filter matches tags attached to the requested entity, including tags already propagated to it. For anomalies, it matches the anomaly's current tags. Use container.tag.name or container.tag.id when you mean tags on its parent container. Neither filter represents the failed check's tags at detection time; historical failed-check evidence remains a separate resource.

Count Anomalies by Container

This request counts active anomalies by container and returns the largest counts first:

{
  "schema_version": 1,
  "resource": "anomalies",
  "mode": "aggregate",
  "group_by": ["container.id"],
  "metrics": ["anomaly_count"],
  "order_by": [{"field": "anomaly_count", "direction": "desc"}],
  "page": {"limit": 20}
}

The count includes distinct anomaly entities visible to you. It is not the number of failed checks or the number of distinct source records affected. Permission and lifecycle filters apply before the count is calculated.

Anomalies default to Active. To include other statuses, specify them explicitly:

{
  "resource": "anomalies",
  "mode": "aggregate",
  "where": {"field": "status", "op": "in", "value": ["Active", "Acknowledged"]},
  "metrics": ["anomaly_count"]
}

List the Checks on a Container or Field

Quality checks expose their current field assignment as a filter and their template linkage as columns. To list the active checks on the orders container that involve the email field:

{
  "resource": "quality_checks",
  "where": {
    "all": [
      {"field": "container.name", "op": "eq", "value": "orders"},
      {"field": "field.name", "op": "eq", "value": "email"}
    ]
  },
  "select": ["id", "description", "rule_type", "status", "field_count", "template_id", "template_locked"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}

field.id and field.name match the check's current field assignment, not the fields involved when an anomaly was detected. template_id is null for standalone checks; template_locked reports the source template's lock, so a true value means the check's properties follow its template. Checks default to Active; include Draft or the archived statuses with an explicit status filter. Personal flags such as favorites are not reporting fields.

Templates use the quality_check_templates resource, which exposes template_locked, tag.name filters, and derived_check_count. Templates are shared across the workspace, but this count includes only checks in datastores where you have the Reporter team permission or higher. It includes all check statuses and excludes deleted checks and deleted parent containers. Your current access applies before the count is selected, filtered, grouped, or sorted.

For example, list the most-used templates within your reporting scope:

{
  "resource": "quality_check_templates",
  "select": ["id", "description", "template_locked", "derived_check_count"],
  "order_by": [{"field": "derived_check_count", "direction": "desc"}],
  "page": {"limit": 10}
}

Count Anomalies by Rule at Detection Time

Each anomaly records the checks that failed when it was detected. That evidence does not change when a check is later edited, archived, or deleted. The failed_checks resource has one row per anomaly and failed check, and its anomaly_count metric counts distinct anomalies:

{
  "resource": "failed_checks",
  "mode": "aggregate",
  "group_by": ["rule_type"],
  "metrics": ["anomaly_count"],
  "order_by": [{"field": "anomaly_count", "direction": "desc"}]
}

An anomaly that failed two checks of different rule types appears in both groups, and once in each. A check's rule type never changes, so the rule type is the detection-time value even when the check has since been archived. Row projections separate current check state (quality_check.status, quality_check.description) from detection-time evidence (quality_check.description_at_detection, message); a missing recorded version returns null rather than the current text. Failure messages require Source Data Shared.

The anomalies resource carries the same evidence as filters. To list active anomalies whose failed checks involved the email field, or that failed a Data Diff check:

{
  "resource": "anomalies",
  "where": {
    "any": [
      {"field": "field.name", "op": "eq", "value": "email"},
      {"field": "failed_check.rule_type", "op": "eq", "value": "dataDiff"}
    ]
  },
  "select": ["id", "type", "status", "container.name", "anomalous_records_count", "failed_check_count", "field_count"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}

Here field.name means the fields involved at detection time, which can differ from the check's current fields. failed_check_count and field_count describe the same evidence. Both resources apply the ordinary anomaly defaults: Active status unless you filter otherwise, live parent containers, and no soft-deleted anomalies. Retained evidence for deleted anomalies stays on the anomaly_failed_checks history resource.

Count Data Diff Checks

Use dataDiff to report on comparison checks. The reporting schema exposes canonical rule names and rejects unsupported values before running a query.

{
  "resource": "quality_checks",
  "mode": "aggregate",
  "where": {"field": "rule_type", "op": "eq", "value": "dataDiff"},
  "metrics": ["check_count"]
}

This counts the Data Diff checks you can access, subject to the usual Active default. Use the same rule identifier for templates and grouped reports. Comparison checks do not need separate current and legacy counts.

Find the Data Diff Check on the Largest Container

Quality checks expose their target container's reporting fields under container.*. This request ranks all matching checks you can access by the latest known row count, then returns the first result:

{
  "resource": "quality_checks",
  "where": {"field": "rule_type", "op": "eq", "value": "dataDiff"},
  "select": ["id", "description", "container.id", "container.name", "container.latest_row_count", "container.latest_row_count_at", "container.latest_row_count_source"],
  "order_by": [{"field": "container.latest_row_count", "direction": "desc"}],
  "page": {"limit": 1}
}

The target is the container that owns the check. This does not rank its reference container. Checks default to Active. Equal row counts use check ID as a stable tie-breaker; increase the limit to see more matches. Unknown row counts sort last. If the returned row count is null, the available measurements cannot establish a largest container.

latest_row_count selects the newer of a valid current profile total and a volume measurement. A freshness-only measurement does not erase an older known volume. A profile that processed more records than its recorded total is not treated as proof that the container is empty. Zero means measured empty; null means unknown. The accompanying time and source identify the selected evidence.

Query Current Profiles and Derived Properties

Containers expose current profile properties as latest_profile.*, including record totals, records processed, profile result, observation time, and check synchronization counts. Fields expose current profile type information and scalar statistics under the same prefix. The current profile is the one selected by Qualytics for that entity, which may differ from the newest profile in its history.

For example, find fields whose current profile reports low completeness:

{
  "resource": "fields",
  "where": {"field": "latest_profile.completeness", "op": "lt", "value": 0.9},
  "select": ["id", "name", "container.name", "latest_profile.completeness", "latest_profile.created_at"],
  "order_by": [{"field": "latest_profile.completeness", "direction": "asc"}],
  "page": {"limit": 20}
}

Field statistics require Source Data Shared for selection, filtering, grouping, and sorting. Statistics for masked fields are null in all these operations. Missing profiles also return null. Histograms, source samples, opaque sketches, correlations, and regression models are not exposed through these scalar fields.

Other reporting fields include:

Discover the resource to see exact names, data requirements, and definitions. Numeric fields can be selected, filtered, and sorted; grouping is available where the discovered schema permits it. These are reporting fields on existing resources, so combining them does not require another tool.

Interpret Datastore Measurements and Counts

Datastore observability totals combine each live container's newest measurement. Some measurements contain freshness information without volume or size, so a total can cover only part of the datastore. Request coverage alongside the total:

{
  "resource": "datastores",
  "select": ["id", "name", "latest_observability_measurement.total_row_count", "latest_observability_measurement.row_count_container_count", "latest_observability_measurement.live_container_count", "latest_observability_measurement.last_measurement_time"],
  "page": {"limit": 20}
}

Compare row_count_container_count with live_container_count. A null total means no included measurement supplies a row count. last_measurement_time is the most recent measurement time across the containers, not a guarantee that every container was measured then. Size totals have a separate coverage count.

Datastore records_count follows Data Under Management: it uses each container's latest known non-null volume at query time, including enrichment datastores. It can therefore differ from an observability total whose newest measurements contain only freshness information. Unknown container volumes do not become zero in either calculation.

Counts also have different time scopes. anomaly_count includes retained anomalies across statuses, including soft-deleted evidence, for live containers. Container active anomaly counts exclude deleted anomalies; field active anomaly counts preserve retained evidence whose status is Active. Field counts use membership at detection time, even when a check's fields have since changed. The derived counts under a field's latest_profile.* describe current state, not a snapshot taken when profiling ran.

A container's fields_count excludes excluded fields; a datastore's field_count includes all field statuses. Application-maintained datastore counters and stored scores can lag recent changes. Passing and failing check counts require a prior assertion; an unasserted check is unknown. Latest operation metadata can describe a queued, running, or failed operation, so inspect its result as well as its time.

Read Quality Scores and Datastore Dimensions

Containers and fields expose their current stored score under latest_quality_score.*, and the container_scores and field_scores resources hold score history. Datastores expose the same eight dimensions under quality_score.*, calculated exactly as the datastore card does:

{
  "resource": "datastores",
  "select": ["id", "name", "quality_score.total", "quality_score.completeness", "quality_score.coverage", "quality_score.timeliness", "quality_score.created_at"],
  "order_by": [{"field": "quality_score.total", "direction": "asc"}],
  "page": {"limit": 20}
}

A datastore dimension is a weighted average: multiply each live, scanned container's newest stored score by its container weight, add those values, and divide by the total weight of the containers that contributed a score. Newest means the latest creation time; if timestamps tie, the higher score ID wins. Each container contributes once, and scanned containers without scores do not increase the denominator.

The datastore card and listings use the same calculation. A measured score of zero stays zero. A dimension is null when the datastore has never been scanned, is an enrichment datastore, has no contributing measurement for that dimension, or has no positive total weight. These are stored domain measurements; the interface does not compute new averages across arbitrary sets of containers.

To compare containers in a datastore, or tagged containers across datastores, select latest_quality_score.* on the containers resource with a datastore.id or tag.name filter and order by latest_quality_score.total. A null score means no stored measurement is available; it does not establish a score of zero.

Read Daily Insights

Insight resources return one row per UTC calendar day of a window ending today, using the same calculations as the Insights pages. Use insights mode with one positive target ID and an optional timeframe of week, month, quarter or year. The default is week:

{
  "resource": "container_insights",
  "mode": "insights",
  "where": {
    "all": [
      {"field": "container.id", "op": "eq", "value": 123},
      {"field": "timeframe", "op": "eq", "value": "month"}
    ]
  },
  "select": ["date", "quality_score.total", "anomalies_identified", "records_measured"]
}

platform_insights needs no target and accepts optional datastore.id and tag.name filters; it is always restricted to the datastores you can report on. Use eq with one value, such as 123 or "Finance", and in with a non-empty array, such as [123, 456] or ["Finance", "Compliance"]. Entity insight resources require eq with one target ID. Combine different filters in an all group; repeated filters and any groups are unsupported.

Each insight row contains date and the available values directly under column names such as quality_score.total or anomalies_identified. The columns vary by resource:

Field insights support active, missing, and excluded fields under live containers you can access. A field without a current profile has no insights.

Totals, trends, and histograms are returned in provenance.summary, separate from daily rows. For platform and datastore insights, the check distribution is at provenance.summary.checks_histogram. Discover each resource for its exact columns. select narrows the daily columns; date is always returned, whether or not you select it.

Schema discovery exposes lifecycle before you query; the result repeats it in provenance.lifecycle. Daily score behavior depends on the resource:

• Platform and datastore scores use the latest known score up to each day, so a score can carry forward across days without a new measurement.
• Container and field scores include only measurements recorded on that day. Check assertions also describe that day's results. These resources do not carry measurements forward.

An omitted column means no measurement is available for that day, not zero activity. A missing score does not establish that checks are absent or that the asset has never been scanned; inspect check coverage and operation history before drawing that conclusion. Insight series do not support pagination, custom sorting, grouping, or time_series. They have a 100,000-byte output budget; an oversized series is refused rather than truncated. Select fewer columns or a shorter timeframe if it exceeds the budget.

For operation activity over time, including failed or aborted runs, use the operations resource in aggregate mode with a time_series on created_at, filtering type, result or datastore.id. duration_seconds is available on operation rows; averages and success ratios across operations are model calculations and are disclosed as such.

Find Datastores without Active Recurring Schedules

{
  "resource": "datastores",
  "where": {"field": "has_active_recurring_schedule", "op": "eq", "value": false},
  "select": ["id", "name"],
  "page": {"limit": 25}
}

Schedules attached to flow actions do not count as recurring schedules. A paused recurring schedule does not satisfy the active-schedule condition.

Find the Next Five Scheduled Operations

{
  "resource": "schedules",
  "where": {"field": "has_next_run", "op": "eq", "value": true},
  "select": ["id", "name", "type", "datastore.name", "next_trigger", "timezone"],
  "order_by": [{"field": "next_trigger", "direction": "asc"}],
  "page": {"limit": 5}
}

This returns the earliest persisted next-run times for recurring operation schedules you can access. Deactivated schedules, paused jobs, missing jobs, and schedules attached to flow actions do not qualify. Equal times use schedule ID as a stable tie-breaker.

Each row represents one pending occurrence of a schedule. This does not expand a recurring schedule into several future runs or include scheduled flows. Overdue times remain visible because they may still be pending. The time is a scheduling record, not a guarantee that work will start then. Use scheduler_state to distinguish scheduled, paused, missing, and deactivated records; it does not establish scheduler health. A missing timezone setting means UTC.

Find Failed Operations on a Calendar Day

For “any failed operations from May 15,” establish the year, timezone, and intended time field. This example finds failures completed on May 15, 2026 in New York:

{
  "resource": "operations",
  "where": {
    "all": [
      {"field": "result", "op": "eq", "value": "failure"},
      {"field": "end_time", "op": "gte", "value": "2026-05-15T00:00:00-04:00"},
      {"field": "end_time", "op": "lt", "value": "2026-05-16T00:00:00-04:00"}
    ]
  },
  "select": ["id", "type", "datastore.name", "result", "end_time", "error_code", "fault_domain"],
  "order_by": [{"field": "end_time", "direction": "asc"}],
  "page": {"limit": 25}
}

The range includes the start of May 15 and excludes the start of May 16. Use start_time instead when you mean operations that started on that date. created_at records creation, while dispatched_at can reflect a later restart. An operation without a completion time does not match an end_time range.

result retains the exact outcome or lifecycle state: queued, running, success, failure, partial, or aborted. Failure is distinct from partial completion or an abort. The coarser status field matches the polling summary: queued/running map to running, success/partial to completed, and other outcomes to failed. Use result when that distinction matters. These reports read stored state; they do not contact workers or wait for an operation to finish.

List Recent Operations on a Container

Operations expose their target containers as filters. To see the latest runs that targeted the orders container:

{
  "resource": "operations",
  "where": {"field": "container.name", "op": "eq", "value": "orders"},
  "select": ["id", "type", "result", "status", "created_at", "end_time", "target_container_count", "has_message"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 25}
}

container.id and container.name are filters only. They match live containers that belong to the operation's own datastore; a container in another datastore, such as an enrichment datastore, never matches. target_container_count counts those same targets, so zero also describes a datastore-wide operation such as a sync. Combine datastore.id, type, result or status, and schedule.id to narrow the list, and use status equal to running for work that has not finished. Promotions report their promote_type. Target container names and the operation message, when there is one, are available in the operation details; has_message tells you whether a message exists.

Recurring schedules expose the same container.id and container.name filters for their saved target containers, plus target_tag.name and target_tag.id for saved tag selectors and counts of both. The cron cadence of a schedule is not a reporting field; use the schedule's detail projection, or the list_schedules tool when you need the cadence of many schedules at once.

Count and Read Anomaly Comments

To answer “how many comments exist on anomaly 123?”:

{
  "resource": "anomaly_comments",
  "mode": "aggregate",
  "where": {"field": "anomaly.id", "op": "eq", "value": 123},
  "metrics": ["comment_count"]
}

This counts live root comments and replies. Deleted comment placeholders do not count, but their surviving replies do. The anomaly can be Active, Acknowledged, archived, or retained after soft deletion, provided its parent container is live and you have access. Unlike ordinary anomaly queries, this resource has no Active-status default. Zero means no eligible comments were found; it does not confirm that an inaccessible or nonexistent anomaly exists.

Read recent comment text with Source Data Shared:

{
  "resource": "anomaly_comments",
  "where": {"field": "anomaly.id", "op": "eq", "value": 123},
  "select": ["id", "parent_id", "created_at", "message"],
  "order_by": [{"field": "created_at", "direction": "desc"}],
  "page": {"limit": 20}
}

Comment text can contain source values, so selecting, filtering, or sorting by message requires Source Data Shared. Metadata counts remain available at Metadata Shared. The result is a flat page of live comments, not a reconstructed conversation with deleted placeholders.

Filter or group comments by anomaly.status when you need discussion counts for a particular current status. This is the anomaly's status now, not when the comment was written. Ordinary anomalies queries also expose comment_count and latest_comment_at, subject to their Active default; an explicit status filter includes other statuses. The latest-comment time records creation rather than edits. Historical status changes remain available through anomaly history.

Read Partition Comments

Comments on partitions use the partition_comments resource with the same shape. To read the discussion on partition 45 with its authors:

{
  "resource": "partition_comments",
  "where": {"field": "partition.id", "op": "eq", "value": 45},
  "select": ["id", "parent_id", "is_reply", "author.id", "author.name", "created_at", "message"],
  "order_by": [{"field": "created_at", "direction": "asc"}],
  "page": {"limit": 25}
}

Both comment resources expose author.id and author.name, parent_id for the parent in the same thread, and is_reply. A reply whose parent was deleted still reports that parent ID, although the deleted placeholder itself is never returned. Partition comments require Reporter access to the partition's datastore and a live parent container; comments on containers and quality checks are not available through reporting.

Request a Weekly Trend

{
  "resource": "operations",
  "mode": "aggregate",
  "where": {
    "all": [
      {"field": "result", "op": "eq", "value": "failure"},
      {"field": "tag.name", "op": "eq", "value": "Finance"}
    ]
  },
  "metrics": ["operation_count"],
  "time_series": {
    "field": "created_at",
    "interval": "week",
    "start": "2026-09-01T00:00:00Z",
    "end": "2026-10-01T00:00:00Z",
    "timezone": "UTC"
  }
}

This example groups operations by creation time and uses the datastore's current tags. Buckets use UTC and exclude the end timestamp. An absent bucket means no matching observations were returned. A trend in counts does not by itself establish a cause.

Operation trends use paged aggregate results, with at most 75 rows per page. A quarter of daily buckets can exceed one page, and grouping by result adds more rows. Whenever has_more is true, repeat the request with page.offset set to next_offset until all pages are read before analyzing the full trend.

Read Details or Configuration History

Use a positive numeric ID from an authorized result. This example requests the current details of container 123:

{
  "resource": "containers",
  "mode": "detail",
  "where": {"field": "id", "op": "eq", "value": 123}
}

For the current definition of a computed container, use mode: "definition". Detail and definition requests return fixed, curated projections; omit select, sorting, and offsets. Use row mode when you need a smaller selection of scalar fields.

Configuration history is a separate resource:

{
  "resource": "container_history",
  "mode": "history",
  "where": {"field": "container.id", "op": "eq", "value": 123},
  "page": {"limit": 20}
}

Container history combines relevant container configuration, grouping, field, and computed-field changes. Read the returned interpretation and coverage notes. Retention and the start of version tracking can limit what is available; an absent event does not prove that a change never happened. Anomaly history and failed-check evidence use anomaly.id instead.

History requests return a bounded set of the newest evidence and do not support offsets, arbitrary field selections, or time-series grouping. Anomaly failed-check evidence preserves the check definition used when the anomaly was detected.

Defaults and Result Interpretation

Results include applied defaults, scope, page information, and limitations. returned_count describes the current page; an unavailable total_count is not zero. Follow next_offset only when it is present. Pages are separate observations, so concurrent changes may affect a multi-page listing.

A detail or history projection is evidence about one entity. It does not claim that all nested relationships or all past events are included. Explaining a cause or combining several results can still require a model-derived answer and the usual disclosure.

Permissions, Sharing, and Limits

Every query runs with your current role and team access. Query arguments cannot choose another user or widen your datastore permissions. Unauthorized data does not contribute to counts, sorting, grouping, or relationship filters.

Metadata-only plans remain available at Metadata Shared. Field-profile statistics, container profile completeness, comment text, anomaly descriptions, and historical evidence that can quote values require Source Data Shared. Filtering, sorting, or grouping by those fields also requires that level, even if the field is not returned. Query-specific sharing checks apply to both AgentQ chat and the semantic reporting tools over MCP.

Queries have bounded page sizes, output sizes, filter complexity, and execution time. Time-series requests use UTC and cover at most 366 days, except operation reports, which support up to 1,827 days for five-year reporting. The start is inclusive and the end is exclusive, so include the day after the last date you want to report. Unsupported metrics, arbitrary joins, raw SQL, and overly expensive requests are refused. A refusal or partial result is not evidence that no matching data exists.

The interface supplies counts and stored quality scores. It does not calculate new score formulas, arbitrary averages, or causal explanations. Use the returned schema and limitations to decide whether a question is supported.

Inspect a Check Template

Use the template resource to read a template's configuration before creating a check from it:

{
  "resource": "quality_check_templates",
  "mode": "detail",
  "where": {"field": "id", "op": "eq", "value": 123}
}

Replace the example ID with one discovered from your workspace. Use quality_checks for a check attached to a container. Detail requests require a numeric ID and return a curated projection, which may include bounded nested lists.

See Also