Deletion Rules

A deletion rule erases data for a population you define, across your warehouse, on demand or on a schedule — and records exactly what it did. Use it to fulfil GDPR right-to-erasure and CCPA deletion requests at scale, instead of looking up and deleting identifiers one at a time.

How a Deletion Rule Works

A rule has four parts:

Each run resolves the matched population once and writes the matched keys to a short-lived table in your warehouse’s planner schema (CDP_PLANNER), which every target then reads. Two things follow from that, and both matter:

• The numbers in the log are the numbers that happened. The count reported for a target and the statement executed against it select the same rows, so records affected is never an estimate.
• All targets see one population. Without this, data changing mid-run could leave a person’s rows deleted from one table and still present in another — the one outcome an erasure request cannot tolerate.

The table is dropped when the run finishes.

Choosing What Gets Deleted

For each target, pick one:

Clearing columns is idempotent: the statement only matches rows where at least one selected column still holds a value, so a second run affects nothing and records affected always means “records that still held data”.

Which models can be targeted

A model appears in the target list only when all of the following hold. Anything ineligible is not offered rather than failing when you save.

The join a rule is saved against is pinned to it. If you later delete or change that relationship, the next run refuses rather than silently matching on a different column — re-open the rule, review the new join, and save it again.

Columns that cannot be cleared

The column carrying the link to the parent model, and the model’s own primary key, are never offered. Clearing either would make the row unreachable on any later run and break the guarantee that re-running is safe.

Observe Mode, Enabling, and Running

A rule has one Run mode with three settings:

The Dry run button is always available and always non-destructive, whatever the rule’s mode.

New rules are created in Observe only. Switching to Live deletion asks you to type the rule’s name back, and tells you what the schedule will do and when the rule was last dry-run.

Availability

Deletion Rules are off in every workspace by default. A Zeotap platform administrator enables the feature per workspace; until they do, the section does not appear in the nav and the API answers 403 deletion rules are not enabled for this workspace.

Once a workspace is enabled, the permissions below take over — your own owners and admins build and run rules, without further involvement from the platform team. Disabling is immediate: the API starts refusing and any scheduled rule stops firing on the next tick.

Permissions

Write and execute are separate so you can let someone run an already-reviewed rule without letting them change what it deletes.

These permissions only apply in a workspace where the feature has been enabled — see Availability above. A workspace settings change cannot grant the feature to itself.

Deletion Logs

Every run writes a log entry, dry or live. Each entry records:

• Rule name, trigger (manual or schedule), mode (dry run or live), and status
• Records matched, and records affected in total
• Who initiated it, and when it started and finished
• Per target: the physical table, the action, the columns, the records affected, and the exact statement executed — or, in a dry run, the statement that would have been

Logs are retained even if the rule is deleted. Each entry snapshots the rule’s name, definition, and the initiating user’s email, so the audit trail stays readable and attributable after the rule (or the account) is gone. There is no way to delete a log entry.

Run statuses

What a Deletion Rule Does Not Do

This is the part worth reading before a compliance deadline.

Creating a Rule via the UI

1. Navigate to Governance → Deletion Rules
2. Click Create rule
3. Select the parent model the rule operates on
4. Build the match conditions. The estimate panel shows how many records match — check it before continuing
5. Choose what to delete for each target model. Review the “Also affected” warning listing what else reads this data
6. Set a schedule, or leave it manual
7. Name the rule and review the summary

The rule is created in Observe only. Open it, click Dry run, and read the log — each target shows the records it would affect and the exact statement it would issue. When those look right, set Run mode to Live deletion and use Run deletion.

Creating a Rule via the API

Rules are workspace-scoped. See Base URL and Authentication for the required headers.

# Erase opted-out EU customers: delete their user row, clear the address on orders
curl -X POST "$API_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/deletion-rules" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "X-Workspace-ID: $WORKSPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "parent_model_id": "'"$USERS_MODEL_ID"'",
    "name": "Erase opted-out EU customers",
    "description": "Fulfils standing right-to-erasure requests for EU opt-outs.",
    "filter_tree": {
      "type": "and",
      "children": [
        {
          "type": "condition",
          "condition_type": "property",
          "field": "region",
          "operator": "equals",
          "value": "EU"
        },
        {
          "type": "condition",
          "condition_type": "property",
          "field": "erasure_requested",
          "operator": "equals",
          "value": true
        }
      ]
    },
    "targets": [
      { "model_id": "'"$USERS_MODEL_ID"'", "action": "delete_rows" },
      {
        "model_id": "'"$ORDERS_MODEL_ID"'",
        "action": "null_columns",
        "columns": ["shipping_address", "phone"]
      }
    ],
    "schedule": "0 3 * * *",
    "dry_run": true,
    "enabled": false
  }'

dry_run and enabled default to true and false respectively, so omitting them creates an observe-only rule. Sending "dry_run": false with "enabled": true arms the rule immediately — do that deliberately.

Trigger a run:

# Non-destructive, whatever the rule's mode. Returns 202 with the opened run.
curl -X POST "$API_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/deletion-rules/$RULE_ID/dry-run" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "X-Workspace-ID: $WORKSPACE_ID"
 
# Live. Requires enabled=true and dry_run=false on the rule.
curl -X POST "$API_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/deletion-rules/$RULE_ID/run" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

Both return 202 Accepted with the run in running state — the deletion continues past the request. Poll the log to follow it:

curl "$API_BASE_URL/api/v1/workspaces/$WORKSPACE_ID/deletion-rules/$RULE_ID/runs" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "X-Workspace-ID: $WORKSPACE_ID"

See Governance API for the full endpoint list.

Warehouse Support

Deletion rules work on Snowflake, BigQuery, Databricks, and ClickHouse. On ClickHouse the deletion is issued as a synchronous mutation (ALTER TABLE … DELETE WHERE), because MergeTree tables have no standalone DELETE — the run does not report success until the rows are gone, though background merges continue afterwards.

Deletion needs write access to the target tables and to the CDP_PLANNER schema. That is the same schema syncs and computed attributes already use, so an existing warehouse connection typically needs no additional grants beyond DELETE / UPDATE on the tables you intend to target.

Related Governance Controls