docs: remove delete/drop from Diagram public API

Diagram is now an inspection-only tool. delete() and drop() have been
moved to Table. Updated diagram spec, whats-new-22, and delete-data
how-to to reflect this change.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dimitri-yatsenko

src/explanation/whats-new-22.md

@@ -1,6 +1,6 @@
 # What's New in DataJoint 2.2
 
-DataJoint 2.2 introduces **isolated instances**, **thread-safe mode**, and **graph-driven diagram operations** for applications that need multiple independent database connections, explicit cascade control, and operational use of the dependency graph.
+DataJoint 2.2 introduces **isolated instances** and **thread-safe mode** for applications that need multiple independent database connections, and **graph-driven diagram operations** that replace the legacy error-driven cascade with a reliable, inspectable approach for all users.
 
 > **Upgrading from 2.0 or 2.1?** No breaking changes. All existing code using `dj.config` and `dj.Schema()` continues to work. The new Instance API is purely additive.
 
@@ -207,27 +207,29 @@ DataJoint 2.2 promotes `dj.Diagram` from a visualization tool to an operational
 
 ### From Visualization to Operations
 
-In prior versions, `dj.Diagram` existed solely for visualization — drawing the dependency graph as SVG or Mermaid output. The cascade logic inside `Table.delete()` traversed dependencies independently, with no way to inspect or control the cascade before it executed.
+In prior versions, `dj.Diagram` existed solely for visualization — drawing the dependency graph as SVG or Mermaid output. The cascade logic inside `Table.delete()` traversed dependencies independently using an error-driven approach: attempt `DELETE` on the parent, catch the foreign key integrity error, parse the error message to discover which child table is blocking, then recursively delete from that child first. This had several problems:
 
-In 2.2, `Table.delete()` and `Table.drop()` delegate internally to `dj.Diagram`. The user-facing behavior of `Table.delete()` is unchanged, but the diagram-level API is now available as a more powerful interface for complex scenarios.
+- **MySQL 8 with limited privileges** returns error 1217 (`ROW_IS_REFERENCED`) instead of 1451 (`ROW_IS_REFERENCED_2`), which provides no table name — the cascade crashes with no way to proceed.
+- **PostgreSQL** aborts the entire transaction on any error, requiring `SAVEPOINT` / `ROLLBACK TO SAVEPOINT` round-trips for each failed delete attempt.
+- **Fragile error parsing** across MySQL versions and privilege levels, where different configurations produce different error message formats.
+
+In 2.2, `Table.delete()` and `Table.drop()` use `dj.Diagram` internally to compute the dependency graph and walk it in reverse topological order — deleting leaves first, with no trial-and-error needed. The user-facing behavior of `Table.delete()` is unchanged. The Diagram's `cascade()` and `preview()` methods are available as a public inspection API for understanding cascade impact before executing.
 
 ### The Preview-Then-Execute Pattern
 
-The key benefit of the diagram-level API is the ability to build a cascade explicitly, inspect it, and then decide whether to execute:
+The key benefit of the diagram-level API is the ability to build a cascade explicitly, inspect it, and then execute via `Table.delete()`:
 
 ```python
-# Build the dependency graph
+# Build the dependency graph and inspect the cascade
 diag = dj.Diagram(schema)
-
-# Apply cascade restriction — nothing is deleted yet
 restricted = diag.cascade(Session & {'subject_id': 'M001'})
 
 # Inspect: what tables and how many rows would be affected?
 counts = restricted.preview()
 # {'`lab`.`session`': 3, '`lab`.`trial`': 45, '`lab`.`processed_data`': 45}
 
-# Execute only after reviewing the blast radius
-restricted.delete(prompt=False)
+# Execute via Table.delete() after reviewing the blast radius
+(Session & {'subject_id': 'M001'}).delete(prompt=False)
 ```
 
 This is valuable when working with unfamiliar pipelines, large datasets, or multi-schema dependencies where the cascade impact is not immediately obvious.
@@ -238,9 +240,11 @@ The diagram supports two restriction propagation modes designed for fundamentall
 
 **`cascade()` prepares a delete.** It takes a single restricted table expression, propagates the restriction downstream through all descendants, and **trims the diagram** to the resulting subgraph — ancestors and unrelated tables are removed entirely. Convergence uses OR: a descendant row is marked for deletion if *any* ancestor path reaches it, because if any reason exists to remove a row, it should be removed. `cascade()` is one-shot and is always followed by `preview()` or `delete()`.
 
+When the cascade encounters a part table whose master is not yet included in the cascade, the behavior depends on the `part_integrity` setting. With `"enforce"` (the default), `delete()` raises an error if part rows would be deleted without their master — preventing orphaned master rows. With `"cascade"`, the restriction propagates *upward* from the part to its master: the restricted part rows identify which master rows are affected, those masters receive a restriction, and that restriction then propagates back downstream to all sibling parts — deleting the entire compositional unit, not just the originally matched part rows.
+
 **`restrict()` selects a data subset.** It propagates a restriction downstream but **preserves the full diagram**, allowing `restrict()` to be called again from a different seed table. This makes it possible to build up multi-condition subsets incrementally — for example, restricting by species from one table and by date from another. Convergence uses AND: a descendant row is included only if *all* restricted ancestors match, because an export should contain only rows satisfying every condition. After chaining restrictions, use `prune()` to remove empty tables and `preview()` to inspect the result.
 
-The two modes are mutually exclusive on the same diagram. This prevents accidental mixing of incompatible semantics — a delete diagram should never be reused for subsetting, and vice versa.
+The two modes are mutually exclusive on the same diagram — DataJoint raises an error if you attempt to mix `cascade()` and `restrict()`, or if you call `cascade()` more than once. This prevents accidental mixing of incompatible semantics: a delete diagram should never be reused for subsetting, and vice versa.
 
 ### Pruning Empty Tables
 
@@ -260,7 +264,21 @@ Without prior restrictions, `prune()` removes physically empty tables. This is u
 
 ### Architecture
 
-`Table.delete()` now constructs a `Diagram` internally, calls `cascade()`, and then `delete()`. This means every table-level delete benefits from the same graph-driven logic. The diagram-level API simply exposes this machinery for direct use when more control is needed.
+`Table.delete()` constructs a `Diagram` internally, calls `cascade()` to compute the affected subgraph, then executes the delete itself in reverse topological order. The Diagram is purely a graph computation and inspection tool — it computes the cascade and provides `preview()`, but all mutation logic (transactions, SQL execution, prompts) lives in `Table.delete()` and `Table.drop()`.
+
+### Advantages over Error-Driven Cascade
+
+The graph-driven approach resolves every known limitation of the prior error-driven cascade:
+
+| Scenario | Error-driven (prior) | Graph-driven (2.2) |
+|---|---|---|
+| MySQL 8 + limited privileges | Crashes (error 1217, no table name) | Works — no error parsing needed |
+| PostgreSQL | Savepoint overhead per attempt | No errors triggered |
+| Multiple FKs to same child | One-at-a-time via retry loop | All paths resolved upfront |
+| Part integrity enforcement | Post-hoc check after delete | Data-driven post-check (no false positives) |
+| Unloaded schemas | Crash with opaque error | Clear error: "activate schema X" |
+| Reusability | Delete-only | Delete, drop, export, prune |
+| Inspectability | Opaque recursive cascade | `preview()` / `dry_run` before executing |
 
 ## See Also
 

src/how-to/delete-data.md

@@ -189,39 +189,46 @@ count = (Subject & restriction).delete(prompt=False)
 print(f"Deleted {count} subjects")
 ```
 
-## Diagram-Level Delete
+## Inspecting Cascade Before Deleting
 
 !!! version-added "New in 2.2"
-    Diagram-level delete was added in DataJoint 2.2.
+    Cascade inspection via `dj.Diagram` was added in DataJoint 2.2.
 
-For complex scenarios — previewing the blast radius, working across schemas, or understanding the dependency graph before deleting — use `dj.Diagram` to build and inspect the cascade before executing.
+For a quick preview, `table.delete(dry_run=True)` returns the affected row counts without deleting anything:
 
-### Build, Preview, Execute
+```python
+# Quick preview of what would be deleted
+(Session & {'subject_id': 'M001'}).delete(dry_run=True)
+# {'`lab`.`session`': 3, '`lab`.`trial`': 45, '`lab`.`processed_data`': 45}
+```
+
+For more complex scenarios — working across schemas, chaining multiple restrictions, or visualizing the dependency graph — use `dj.Diagram` to build and inspect the cascade explicitly:
 
 ```python
 import datajoint as dj
 
-# 1. Build the dependency graph
+# 1. Build the dependency graph and apply cascade restriction
 diag = dj.Diagram(schema)
-
-# 2. Apply cascade restriction (nothing deleted yet)
 restricted = diag.cascade(Session & {'subject_id': 'M001'})
 
-# 3. Preview: see affected tables and row counts
+# 2. Preview: see affected tables and row counts
 counts = restricted.preview()
 # {'`lab`.`session`': 3, '`lab`.`trial`': 45, '`lab`.`processed_data`': 45}
 
-# 4. Execute only after reviewing
-restricted.delete(prompt=False)
+# 3. Visualize the cascade subgraph (in Jupyter)
+restricted
+
+# 4. Execute via Table.delete() after reviewing
+(Session & {'subject_id': 'M001'}).delete(prompt=False)
 ```
 
 ### When to Use
 
 - **Preview blast radius**: Understand what a cascade delete will affect before committing
-- **Multi-schema cascades**: Build a diagram spanning multiple schemas and delete across them in one operation
+- **Multi-schema inspection**: Build a diagram spanning multiple schemas to visualize cascade impact
 - **Programmatic control**: Use `preview()` return values to make decisions in automated workflows
 
-For simple single-table deletes, `(Table & restriction).delete()` remains the simplest approach. The diagram-level API is for when you need more visibility or control.
+For simple single-table deletes, `(Table & restriction).delete()` remains the simplest approach. The diagram API is for when you need more visibility before executing.
 
 ## See Also
 

src/reference/specs/diagram.md

@@ -120,9 +120,9 @@ dj.Diagram(Subject) + dj.Diagram(analysis).collapse()
 ## Operational Methods
 
 !!! version-added "New in 2.2"
-    Operational methods (`cascade`, `restrict`, `delete`, `drop`, `preview`, `prune`) were added in DataJoint 2.2.
+    Operational methods (`cascade`, `restrict`, `preview`, `prune`) were added in DataJoint 2.2.
 
-Diagrams can propagate restrictions through the dependency graph and execute data operations (delete, drop) using the graph structure. These methods turn Diagram from a visualization tool into an operational component.
+Diagrams can propagate restrictions through the dependency graph and inspect affected data using the graph structure. These methods turn Diagram from a visualization tool into a graph computation and inspection component. All mutation operations (delete, drop) are executed by `Table.delete()` and `Table.drop()`, which use Diagram internally.
 
 ### `cascade()`
 
@@ -189,49 +189,6 @@ restricted = (diag
     .restrict(Session & 'session_date > "2024-01-01"'))
 ```
 
-### `delete()`
-
-```python
-diag.delete(transaction=True, prompt=None, dry_run=False)
-```
-
-Execute a cascading delete on the cascade subgraph. All tables in the diagram are deleted in reverse topological order (leaves first) to maintain referential integrity.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `transaction` | bool | `True` | Wrap in atomic transaction |
-| `prompt` | bool or None | `None` | Prompt for confirmation. Default: `dj.config['safemode']` |
-| `dry_run` | bool | `False` | If `True`, return affected row counts without deleting |
-
-**Returns:** `int` (rows deleted from root table) or `dict[str, int]` (table → row count mapping when `dry_run=True`).
-
-**Requires:** `cascade()` must be called first.
-
-```python
-diag = dj.Diagram(schema)
-restricted = diag.cascade(Session & {'subject_id': 'M001'})
-restricted.preview()   # inspect what will be deleted
-restricted.delete()    # execute the delete
-```
-
-### `drop()`
-
-```python
-diag.drop(prompt=None, part_integrity="enforce", dry_run=False)
-```
-
-Drop all tables in the diagram in reverse topological order.
-
-| Parameter | Type | Default | Description |
-|-----------|------|---------|-------------|
-| `prompt` | bool or None | `None` | Prompt for confirmation. Default: `dj.config['safemode']` |
-| `part_integrity` | str | `"enforce"` | `"enforce"` or `"ignore"` |
-| `dry_run` | bool | `False` | If `True`, return row counts without dropping tables |
-
-**Returns:** `dict[str, int]` (table → row count mapping when `dry_run=True`). Returns `None` otherwise.
-
-**Note:** Unlike `delete()`, `drop()` does not use cascade restrictions. It drops all tables in the diagram.
-
 ### `preview()`
 
 ```python
@@ -257,7 +214,7 @@ counts = restricted.preview()
 diag.prune()
 ```
 
-Remove tables with zero matching rows from the diagram. Without prior restrictions, removes physically empty tables. With restrictions (`cascade()` or `restrict()`), removes tables where the restricted query yields zero rows.
+Remove tables with zero matching rows from the diagram view. This only affects the diagram object — no tables or data are modified in the database. Without prior restrictions, removes physically empty tables from the diagram. With restrictions (`cascade()` or `restrict()`), removes tables where the restricted query yields zero rows.
 
 **Returns:** New `Diagram` with empty tables removed.
 
@@ -291,6 +248,14 @@ When a child table has multiple restricted ancestors, the convergence rule depen
 - **`cascade()` (OR):** A child row is affected if *any* path from a restricted ancestor reaches it. This is appropriate for delete — if any reason exists to delete a row, it should be deleted.
 - **`restrict()` (AND):** A child row is included only if *all* restricted ancestors match. This is appropriate for export — only rows satisfying every condition are selected.
 
+**Multiple foreign keys to the same parent:**
+
+When a child table references the same parent through multiple foreign keys (e.g., `source_mouse` and `target_mouse` both referencing `Mouse`), these paths always combine with **OR** regardless of the propagation mode. Each foreign key path is an independent reason for the child row to be affected — this is structural, not operation-dependent.
+
+**Unloaded schemas:**
+
+If a descendant table lives in a schema that hasn't been activated (loaded into the dependency graph), the graph-driven delete won't know about it. The final `DELETE` on the parent will fail with a foreign key error. DataJoint catches this and produces an actionable error message identifying which schema needs to be activated.
+
 ---
 
 ## Output Methods
@@ -475,7 +440,7 @@ combined = dj.Diagram.from_sequence([schema1, schema2, schema3])
 
 ## Dependencies
 
-Operational methods (`cascade`, `restrict`, `delete`, `drop`, `preview`, `prune`) use `networkx`, which is always installed as a core dependency.
+Operational methods (`cascade`, `restrict`, `preview`, `prune`) use `networkx`, which is always installed as a core dependency.
 
 Diagram **visualization** requires optional dependencies:
 
@@ -490,7 +455,7 @@ If visualization dependencies are missing, `dj.Diagram` displays a warning and p
 ## See Also
 
 - [How to Read Diagrams](../../how-to/read-diagrams.ipynb)
-- [Delete Data](../../how-to/delete-data.md) — Diagram-level delete workflow
+- [Delete Data](../../how-to/delete-data.md) — Cascade inspection and delete workflow
 - [What's New in 2.2](../../explanation/whats-new-22.md) — Motivation and design
 - [Data Manipulation](data-manipulation.md) — Insert, update, delete specification
 - [Query Algebra](query-algebra.md)