QUA-1024: Restructure Aggregation Comparison check docs

docs/data-quality-checks/aggregation-comparison/api.md

@@ -0,0 +1,116 @@
+# :material-api:{ .middle style="color: var(--q-brick)" } Aggregation Comparison Check API
+
+The Aggregation Comparison check is created and managed through the standard Quality Checks API by setting `rule` to `aggregationComparison` and providing both aggregation expressions plus the comparison operator under `properties`. The check evaluates one aggregate per side and compares them, so the `fields` array is not used.
+
+!!! tip
+    For complete API documentation, including request and response schemas, visit the [API docs](https://demo.qualytics.io/api/docs){:target="_blank"}.
+
+## Endpoints
+
+| Method | Path | Purpose |
+|:---|:---|:---|
+| `POST` | `/api/quality-checks` | Create a new Aggregation Comparison check. |
+| `GET` | `/api/quality-checks/{id}` | Retrieve an Aggregation Comparison check by ID. |
+| `PUT` | `/api/quality-checks/{id}` | Update an existing Aggregation Comparison check. |
+| `DELETE` | `/api/quality-checks/{id}` | Delete (or archive) an Aggregation Comparison check. |
+
+**Permissions** (on the target container's team):
+
+- **`POST`** and **`PUT`** for an Active check: **Author** team permission (or above).
+- **`POST`** and **`PUT`** for a Draft check: **Drafter** team permission (or above).
+- **`DELETE`**: **Author** team permission (or above).
+- **`GET`**: **Reporter** team permission (or above).
+
+The team-permission hierarchy is Editor > Author > Drafter > Viewer > Reporter. "Or above" includes every higher level.
+
+## Payload Example
+
+Create an Aggregation Comparison check on the `orders` container that asserts `ROUND(SUM(o_totalprice))` equals the same roll-up evaluated against the `lineitem` container in the same datastore. The payload below shows every field accepted by the create endpoint:
+
+```json
+{
+    "description": "Order totals must equal the line-item roll-up.",
+    "rule": "aggregationComparison",
+    "fields": [],
+    "container_id": 145,
+    "filter": null,
+    "properties": {
+        "expression": "ROUND(SUM(o_totalprice))",
+        "comparison": "eq",
+        "ref_container_id": 178,
+        "ref_expression": "ROUND(SUM(l_extendedprice * (1 - l_discount) * (1 + l_tax)))",
+        "ref_filter": null
+    },
+    "tags": ["reconciliation", "finance"],
+    "additional_metadata": {"jira": "DATA-4012"},
+    "template_id": null,
+    "status": "Active",
+    "owner_id": 7,
+    "default_anomaly_assignee_id": 12
+}
+```
+
+To reference a container in a **different** datastore, include `ref_datastore_id` in the `properties` block. Leave it out (or set to `null`) when the reference container lives in the same datastore as the target.
+
+## Field Notes
+
+| Field | Required | Notes |
+|:---|:---:|:---|
+| `description` | Yes | Free-text description shown in the UI. |
+| `rule` | Yes | Must be `"aggregationComparison"`. |
+| `fields` | No | Aggregation Comparison does not select columns. Send an empty array `[]` or omit. |
+| `container_id` | Yes | ID of the target container (table or file) the check runs against. |
+| `filter` | No | SQL `WHERE` expression applied to the target container **before** the target aggregation runs. Send `null` for no filter. |
+| `properties` | Yes | Object holding the rule-specific configuration. See the breakdown below. |
+| `properties.expression` | Yes | The target aggregation expression. Must produce a single aggregate value. Supports Check Variables. |
+| `properties.comparison` | Yes | One of `lt`, `lte`, `eq`, `gte`, `gt`. |
+| `properties.ref_datastore_id` | No | Datastore ID for the reference container. Omit or send `null` when the reference container lives in the same datastore as the target. |
+| `properties.ref_container_id` | Yes | Container ID for the reference data. |
+| `properties.ref_expression` | Yes | The reference aggregation expression. Must produce a single aggregate value. Supports Check Variables. |
+| `properties.ref_filter` | No | SQL `WHERE` expression applied to the reference container **before** the reference aggregation runs. Send `null` for no filter. |
+| `tags` | No | List of tag names applied to the check for filtering and organization. |
+| `additional_metadata` | No | Free-form key-value pairs (typically links to catalog entries, tickets, governance records). |
+| `template_id` | No | ID of a Check Template to associate the check with. `null` if not using a template. |
+| `status` | No | `"Active"` (default) or `"Draft"`. Draft checks are not evaluated by Scans. |
+| `owner_id` | No | ID of the user who owns the check. Defaults to the user creating the check when omitted. |
+| `default_anomaly_assignee_id` | No | ID of the user automatically assigned to anomalies produced by the check. |
+
+Two payload fields exist for other rule types but do not apply to Aggregation Comparison:
+
+- `coverage` is ignored. The rule asserts a single boolean condition between two aggregates and has no per-row violation rate.
+- `anomaly_message_field` is ignored. Aggregation Comparison emits Shape Anomalies only, and Shape Anomalies always use the fixed template.
+
+## What `PUT` Can Change
+
+A `PUT` to `/api/quality-checks/{id}` can update most fields on an existing Aggregation Comparison check. Three values stay immutable: the rule type, the container the check is attached to, and the associated Check Template. If any of these needs to change, delete the check and create a new one.
+
+!!! info "Editable vs Immutable on PUT"
+
+    **Editable**
+
+    - `description`
+    - `filter`
+    - `properties.expression`
+    - `properties.comparison`
+    - `properties.ref_datastore_id`
+    - `properties.ref_container_id`
+    - `properties.ref_expression`
+    - `properties.ref_filter`
+    - `tags`
+    - `additional_metadata`
+    - `status`
+    - `owner_id`
+    - `default_anomaly_assignee_id`
+
+    **Immutable**
+
+    - `rule`
+    - `container_id`
+    - `template_id`
+
+## Related
+
+- [Introduction](introduction.md){:target="_blank"}: formal definition, field scope, and general/anomaly properties.
+- [How It Works](how-it-works.md){:target="_blank"}: full semantics, NULL handling, filter behavior, and anomaly templates.
+- [Examples](examples.md){:target="_blank"}: three production scenarios with sample data and resulting anomalies.
+- [FAQ](faq.md){:target="_blank"}: short answers to the most frequent questions.