Computed Join API

The Computed Join API is exposed through the /containers endpoints. All paths in this page are relative to https://<your-instance>.qualytics.io/api. Authentication uses a Bearer token in the Authorization header.

Permissions

To create, edit, or delete a Computed Join you need:

• Editor on the parent datastore, or Author on the parent datastore plus ownership of the Computed Join.
• At least Viewer on every other datastore an input reads from.

The parent datastore is the left container's datastore in pairwise mode, or the first source's datastore in SQL mode. Reading requires at least Reporter on the parent datastore. Permission on the other input datastores is checked only when creating or editing the join.

Schema

A Computed Join has two mutually exclusive shapes. Pairwise mode uses the left_* and right_* fields plus select_clause. SQL mode uses sources and query instead, and must omit every pairwise field. The container has the following fields:

Create a Computed Join

Endpoint: POST /api/containers

Permission: Editor on the parent datastore, or Author with owner_id set to your own ID (or omitted).

Expected response: 200 OK with the created container.

curl -X POST https://your-instance.qualytics.io/api/containers \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_type": "computed_join",
    "name": "customer_orders_join",
    "left_container_id": 101,
    "right_container_id": 202,
    "left_join_field_name": "customer_id",
    "right_join_field_name": "customer_id",
    "left_prefix": "cust",
    "right_prefix": "order",
    "join_type": "left",
    "select_clause": "cust_customer_id, cust_name, cust_city, order_order_id, order_product"
  }'

curl -X POST https://your-instance.qualytics.io/api/containers \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_type": "computed_join",
    "name": "customer_order_summary",
    "sources": [
      { "container_id": 101, "alias": "orders", "where_clause": "order_date >= '\''2026-01-01'\''" },
      { "container_id": 202, "alias": "customers" }
    ],
    "query": "SELECT c.customer_id, c.name, COUNT(o.order_id) AS order_count FROM customers c JOIN orders o ON o.customer_id = c.customer_id GROUP BY c.customer_id, c.name"
  }'

Validate a Computed Join

Endpoint: POST /api/containers/validate

Permission: Same as Create.

Use this endpoint to test the join configuration without persisting it. On success the endpoint returns no body; validation errors are returned as standard error responses.

Expected response: 204 No Content (nothing is persisted).

Query parameters:

The Validate endpoint expects the container payload wrapped in {"container": {...}, "container_id": <existing-id-or-null>}. Pass container_id when validating an edit to an existing Computed Join; omit it (or send null) when validating a new one. For a SQL-mode join, the wrapped container object carries sources and query instead of the pairwise fields.

curl -X POST https://your-instance.qualytics.io/api/containers/validate \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "container": {
      "container_type": "computed_join",
      "name": "customer_orders_join",
      "left_container_id": 101,
      "right_container_id": 202,
      "left_join_field_name": "customer_id",
      "right_join_field_name": "customer_id",
      "left_prefix": "cust",
      "right_prefix": "order",
      "join_type": "left",
      "select_clause": "cust_customer_id, cust_name, cust_city, order_order_id, order_product"
    },
    "container_id": null
  }'

Update a Computed Join

Endpoint: PUT /api/containers/{id}

Permission: Editor on the parent datastore, or Author who is the current owner. Editors do not need to own the join to update it. Only an Editor can reassign owner_id to another user; an Author cannot transfer ownership.

Updates the editable fields of the Computed Join. PUT requires container_type and name on every call (even when neither is changing); other fields are optional and unchanged when omitted. In pairwise mode, the left and right container_id are immutable after creation; to change them, delete and recreate the join, and sending left_container_id or right_container_id in an update body is silently ignored. In SQL mode, sending query (with its sources) replaces the query and the full set of aliased sources; the container-level where_clause and group_by_clause are ignored in SQL mode. Switching a pairwise join to SQL mode is supported by sending query and sources; switching a SQL-mode join back to pairwise is not supported through update. Sending an empty or whitespace-only description clears any existing description.

curl -X PUT https://your-instance.qualytics.io/api/containers/123 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_type": "computed_join",
    "name": "customer_orders_join",
    "select_clause": "cust_customer_id, cust_name, order_product",
    "where_clause": "order_product IS NOT NULL"
  }'

If the new Select Expression (pairwise) or query (SQL mode) drops fields that have active quality checks or anomalies, the request returns 409 Conflict with a list of affected fields. Re-submit with "force_drop_fields": true in the request body to apply the change; the dropped fields are marked missing and their checks and anomalies are preserved until the fields reappear (see How It Works).

curl -X PUT https://your-instance.qualytics.io/api/containers/123 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "container_type": "computed_join",
    "name": "customer_orders_join",
    "select_clause": "cust_customer_id, cust_name",
    "force_drop_fields": true
  }'

Get a Computed Join

Endpoint: GET /api/containers/{id}

Permission: Reporter (or higher) on the datastore.

curl -X GET https://your-instance.qualytics.io/api/containers/123 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

List Computed Joins

Endpoint: GET /api/containers

Permission: Returns containers on datastores where you have at least Reporter.

Returns containers visible to the caller. Filter by container_type=computed_join to list only Computed Joins, optionally scoped to one or more datastores with datastore.

Query parameters:

curl -X GET "https://your-instance.qualytics.io/api/containers?container_type=computed_join&datastore=42" \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Delete a Computed Join

Endpoint: DELETE /api/containers/{id}

Permission: Editor on the parent datastore, or Author who is the current owner. Editors do not need to own the join to delete it.

Expected response: 204 No Content on success.

Deletes the Computed Join and all its quality checks, anomalies, profile data, and derived computed fields. The operation is irreversible.

If the Computed Join is referenced by quality checks elsewhere, the delete fails with 409 Conflict.

curl -X DELETE https://your-instance.qualytics.io/api/containers/123 \
  -H "Authorization: Bearer <YOUR_API_TOKEN>"

Error responses