Add TASK and TRIGGER documentation

Subject: Add new reference documentation for TASK and TRIGGER statements

Author: joocer

docs-site/nav.json

@@ -126,6 +126,9 @@
             {
               "ALTER TABLE": "reference/sql/statements/alter-table.md"
             },
+            {
+              "ALTER TRIGGER": "reference/sql/statements/alter-trigger.md"
+            },
             {
               "ALTER VIEW": "reference/sql/statements/alter-view.md"
             },
@@ -147,6 +150,12 @@
             {
               "CREATE TABLE": "reference/sql/statements/create-table.md"
             },
+            {
+              "CREATE TASK": "reference/sql/statements/create-task.md"
+            },
+            {
+              "CREATE TRIGGER": "reference/sql/statements/create-trigger.md"
+            },
             {
               "CREATE VIEW": "reference/sql/statements/create-view.md"
             },
@@ -168,6 +177,9 @@
             {
               "DROP TABLE": "reference/sql/statements/drop-table.md"
             },
+            {
+              "DROP TASK": "reference/sql/statements/drop-task.md"
+            },
             {
               "DROP TRIGGER": "reference/sql/statements/drop-trigger.md"
             },
@@ -177,6 +189,9 @@
             {
               "DROP WORKSPACE": "reference/sql/statements/drop-workspace.md"
             },
+            {
+              "EXECUTE": "reference/sql/statements/execute.md"
+            },
             {
               "EXPLAIN": "reference/sql/statements/explain.md"
             },

docs-site/reference/sql/statements.md

@@ -102,10 +102,22 @@ Materialized views store a query's result as a physical table and refresh it aut
 | [ALTER MATERIALIZED VIEW](statements/alter-materialized-view) | Change a view's refresh owner, or suspend and resume its refresh |
 | [DROP MATERIALIZED VIEW](statements/drop-materialized-view) | Remove a materialized view and its refresh triggers |
 | [REFRESH MATERIALIZED VIEW](statements/refresh-materialized-view) | Rebuild a materialized view from its defining SELECT |
-| [DROP TRIGGER](statements/drop-trigger) | Remove one refresh trigger from a table |
-| [SHOW TRIGGERS FOR](statements/show-triggers) | List the refresh triggers attached to a table |
+| [SHOW TRIGGERS FOR](statements/show-triggers) | List the triggers attached to a table |
+
+A materialized view's refresh triggers are created and maintained by `CREATE MATERIALIZED VIEW` itself — they are not authored by hand.
+
+## Tasks & Triggers
 
-There is no `CREATE TRIGGER` — triggers only come into existence through `CREATE MATERIALIZED VIEW`.
+A task is a statement the platform runs for you, on demand or when a table changes. Where a materialized view rebuilds one `SELECT` in full, a task runs any statement — typically appending only what changed, which suits tables too large to rebuild:
+
+| Statement | Purpose |
+|-----------|---------|
+| [CREATE TASK](statements/create-task) | Define a statement the platform can run, optionally fired by a table |
+| [EXECUTE](statements/execute) | Run a task now, supplying its parameters |
+| [DROP TASK](statements/drop-task) | Remove a task |
+| [CREATE TRIGGER](statements/create-trigger) | Fire a task when a table changes |
+| [ALTER TRIGGER](statements/alter-trigger) | Suspend or resume a trigger |
+| [DROP TRIGGER](statements/drop-trigger) | Remove a trigger from a table |
 
 ## Workspace Management
 

docs-site/reference/sql/statements/alter-trigger.md

@@ -0,0 +1,54 @@
+---
+title: ALTER TRIGGER Statement — Opteryx Reference
+description: SQL ALTER TRIGGER statement syntax and examples for suspending and resuming a trigger in Opteryx
+---
+
+# ALTER TRIGGER
+
+The `ALTER TRIGGER` statement suspends or resumes one trigger.
+
+A suspended trigger still exists and is still reached when its table commits; it simply
+enqueues nothing and records that it was suppressed. Prefer this to
+[DROP TRIGGER](drop-trigger) when pausing: a dropped trigger is indistinguishable from one
+that was never created, whereas a suspended one shows that it was switched off
+deliberately, when, and by whom.
+
+## Syntax
+
+~~~sql
+ALTER TRIGGER <trigger_name>
+    ON <table_name>
+    { SUSPEND | RESUME };
+~~~
+
+## Parameters
+
+- **`<trigger_name>`** — the trigger to change. Use
+  [SHOW TRIGGERS FOR](show-triggers) to list the triggers on a table.
+- **`<table_name>`** — the table the trigger is attached to, fully qualified as
+  `<workspace>.<collection>.<table_name>`.
+- `SUSPEND` — stop the trigger firing, keeping it in place.
+- `RESUME` — let it fire again.
+
+## Examples
+
+### Suspend a Trigger
+~~~sql
+ALTER TRIGGER ingest_on_events ON my_workspace.raw.events SUSPEND;
+~~~
+
+### Resume It
+~~~sql
+ALTER TRIGGER ingest_on_events ON my_workspace.raw.events RESUME;
+~~~
+
+## Notes
+
+- Requires the `writer` role on the table the trigger is attached to, the same as creating
+  one.
+- Suspension is recorded on the **trigger**, not the task. A task fired by several tables
+  can be paused on one of them and left running on the others.
+- A suspended trigger's table continues to accept commits normally; only the reaction is
+  suppressed.
+- What a trigger runs cannot be altered in place — repoint it with
+  [CREATE OR REPLACE TRIGGER](create-trigger).

docs-site/reference/sql/statements/create-task.md

@@ -0,0 +1,96 @@
+---
+title: CREATE TASK Statement — Opteryx Reference
+description: SQL CREATE TASK statement syntax and examples for defining a statement the platform runs for you in Opteryx
+---
+
+# CREATE TASK
+
+The `CREATE TASK` statement records a statement the platform can run on your behalf, either
+on demand with [EXECUTE](execute) or automatically when a table changes.
+
+A task is the general form of the machinery behind a materialized view. Where a view
+re-runs one `SELECT` into its own backing table, a task runs any statement the engine can
+plan — typically an `INSERT` that appends only what changed, which is what makes it
+suitable for tables too large to rebuild.
+
+A task runs as its owner, so creating one is not merely registering some SQL: it creates
+something that executes with an identity. What you may define is therefore bounded by what
+you could already run yourself — see [Notes](#notes).
+
+## Syntax
+
+~~~sql
+CREATE [ OR REPLACE ] TASK <task_name>
+    [ ON <table_name> ]
+    AS <statement>;
+~~~
+
+## Parameters
+
+- **`<task_name>`** — the name of the task, fully qualified as
+  `<workspace>.<collection>.<task_name>`. A task shares its namespace with tables and
+  views, so the name must be free.
+- **`<table_name>`** — a table whose commits fire this task. Supplying it creates the
+  trigger alongside the task, so one statement leaves nothing half-wired. Omit it and the
+  task is defined but nothing fires it, which is what a backfill or a replay wants; add
+  triggers later with [CREATE TRIGGER](create-trigger).
+- **`<statement>`** — the SQL the task runs. It may contain `:name` placeholders, which are
+  supplied when the task is executed rather than now.
+- `OR REPLACE` — redefine an existing task instead of refusing. The previous statement is
+  kept as an earlier version, and the task's owner is **not** changed.
+
+## Examples
+
+### Define a Task Run on Demand
+~~~sql
+CREATE TASK my_workspace.ops.rebuild_summary AS
+    INSERT INTO my_workspace.ops.summary
+    SELECT category, COUNT(*) FROM my_workspace.sales.orders GROUP BY category;
+~~~
+
+### Define a Task Fired by a Table
+~~~sql
+CREATE TASK my_workspace.ops.ingest_events
+    ON my_workspace.raw.events
+    AS INSERT INTO my_workspace.ops.event_log
+       SELECT * FROM my_workspace.raw.events VERSION AS OF :current_version;
+~~~
+
+### Parameterize the Window
+A task fired by a table is passed the committing snapshot and the one before it, so it can
+process only what that commit added:
+
+~~~sql
+CREATE TASK my_workspace.ops.ingest_new
+    ON my_workspace.raw.events
+    AS INSERT INTO my_workspace.ops.event_log
+       SELECT c.*
+       FROM my_workspace.raw.events VERSION AS OF :current_version AS c
+       LEFT ANTI JOIN my_workspace.raw.events VERSION AS OF :parent_version AS p
+         ON c.event_id = p.event_id;
+~~~
+
+### Redefine an Existing Task
+~~~sql
+CREATE OR REPLACE TASK my_workspace.ops.ingest_events AS
+    SELECT 1;
+~~~
+
+## Notes
+
+- **You may only create a task you could run yourself.** Creating one requires `reader` on
+  everything the statement reads and `writer` where it writes, checked against you at the
+  time you create it and again every time you redefine it. Without that, a task would let
+  anyone define work over data they cannot see and have a privileged identity run it.
+- **The task runs as you.** There is no syntax for naming another principal — an argument
+  that could is the escalation above, written out. Ownership survives `OR REPLACE`, so
+  editing a task never quietly transfers whose authority it runs with.
+- **Platform identities cannot own tasks.** They can read a great deal but have no billing
+  account, so a task pinned to one would run on a schedule forever and land on nobody's
+  bill. Own a task as a user or a service account.
+- The statement is parsed when the task is created, so SQL that could never run is refused
+  now rather than discovered when it fires. It is not fully planned — a task's placeholders
+  have no values yet, and planning would demand them.
+- A task cannot create, drop, or run another task.
+- Relations inside the statement must be **fully qualified**. A task is planned with no
+  implicit workspace, so a two-part name cannot be resolved.

docs-site/reference/sql/statements/create-trigger.md

@@ -0,0 +1,77 @@
+---
+title: CREATE TRIGGER Statement — Opteryx Reference
+description: SQL CREATE TRIGGER statement syntax and examples for firing a task when a table changes in Opteryx
+---
+
+# CREATE TRIGGER
+
+The `CREATE TRIGGER` statement attaches a trigger to a table so that committing to that
+table runs a [task](create-task).
+
+Use this when the firing condition is not simply "the table the task reads" — a task can be
+fired by several tables, or by a table it does not itself read. Where the two do coincide,
+`CREATE TASK ... ON <table>` creates the trigger for you in one statement.
+
+Triggers that refresh a **materialized view** are still created automatically by
+[CREATE MATERIALIZED VIEW](create-materialized-view) and are not authored with this
+statement.
+
+## Syntax
+
+~~~sql
+CREATE [ OR REPLACE ] TRIGGER <trigger_name>
+    ON <table_name>
+    EXECUTE <task_name>;
+~~~
+
+## Parameters
+
+- **`<trigger_name>`** — a name for the trigger, unique among the triggers on that table.
+- **`<table_name>`** — the table whose commits fire it, fully qualified as
+  `<workspace>.<collection>.<table_name>`. Only commits that write data fire a trigger;
+  housekeeping such as compaction and expiration does not.
+- **`<task_name>`** — the task to run, fully qualified.
+- `OR REPLACE` — repoint an existing trigger of this name. Without it, a trigger already
+  pointing at a different task is left alone and the statement is refused, so one trigger
+  cannot silently steal another's name.
+
+## Examples
+
+### Fire a Task When a Table Changes
+~~~sql
+CREATE TRIGGER ingest_on_events
+    ON my_workspace.raw.events
+    EXECUTE my_workspace.ops.ingest_new;
+~~~
+
+### Fire One Task From Several Tables
+~~~sql
+CREATE TRIGGER ingest_on_events ON my_workspace.raw.events
+    EXECUTE my_workspace.ops.reconcile;
+
+CREATE TRIGGER ingest_on_returns ON my_workspace.raw.returns
+    EXECUTE my_workspace.ops.reconcile;
+~~~
+
+### Repoint an Existing Trigger
+~~~sql
+CREATE OR REPLACE TRIGGER ingest_on_events
+    ON my_workspace.raw.events
+    EXECUTE my_workspace.ops.ingest_v2;
+~~~
+
+## Notes
+
+- Requires the `writer` role on the **table** the trigger is attached to — landing a
+  trigger is an update to that table. It does not require any permission on the task: a
+  trigger confers no authority of its own, and what the task may do was settled against its
+  author when the task was created.
+- A fired task is passed the committing snapshot and its parent, as `:current_version` and
+  `:parent_version`. The window is fixed when the trigger fires, so a run means the same
+  thing however long afterwards it is picked up.
+- Only **catalog events** — a commit to a table — can fire a trigger. Clock schedules and
+  application signals are refused rather than stored, because nothing dispatches them yet
+  and a trigger nothing fires is worse than none: the table it maintains stops updating
+  while the trigger record still looks healthy.
+- To stop a trigger without losing it, use
+  [ALTER TRIGGER ... SUSPEND](alter-trigger).

docs-site/reference/sql/statements/drop-task.md

@@ -0,0 +1,43 @@
+---
+title: DROP TASK Statement — Opteryx Reference
+description: SQL DROP TASK statement syntax and examples for removing a task in Opteryx
+---
+
+# DROP TASK
+
+The `DROP TASK` statement removes a task. A task owns no storage, so nothing is reclaimed
+and the drop is fully reversible by re-creating it.
+
+## Syntax
+
+~~~sql
+DROP TASK [ IF EXISTS ] <task_name>;
+~~~
+
+## Parameters
+
+- **`<task_name>`** — the task to remove, fully qualified as
+  `<workspace>.<collection>.<task_name>`.
+- `IF EXISTS` — skip the operation without error if the task does not exist, instead of
+  refusing the statement.
+
+## Examples
+
+### Drop a Task
+~~~sql
+DROP TASK my_workspace.ops.ingest_events;
+~~~
+
+### Drop Only If It Exists
+~~~sql
+DROP TASK IF EXISTS my_workspace.ops.ingest_events;
+~~~
+
+## Notes
+
+- Requires the `writer` role on the task.
+- **Triggers that fire the task are not removed.** A trigger lives on the table that fires
+  it, and deleting other tables' records from this statement is how a partial failure
+  leaves a trigger nobody can see. Remove them with [DROP TRIGGER](drop-trigger).
+- `DROP TASK` takes no other options — with no storage behind it, there is nothing for
+  `CASCADE` or `RESTRICT` to decide.