1 files changed, 54 insertions, 0 deletions
diff --git a/query/update.md b/query/update.md
new file mode 100644
index 0000000..2c5b753
--- /dev/null
+++ b/query/update.md
@@ -0,0 +1,54 @@
+# Update
+
+[back to query](README.md) /// [home](../README.md)
+
+Modify existing rows in a table.
+
+## Request
+
+```json
+{
+  "action": "update",
+  "table": "items",
+  "data": {
+    "price": 29.99,
+    "status": "active"
+  },
+  "filter": {
+    "column": "id",
+    "op": "=",
+    "value": 42
+  }
+}
+```
+
+## Fields
+
+| Field    | Type   | Required | Notes                        |
+|----------|--------|----------|------------------------------|
+| `action` | string | yes      | must be `"update"`           |
+| `table`  | string | yes      | target table                 |
+| `data`   | object | yes      | column value pairs to update |
+| `where`  | object | yes*     | simple key value filter      |
+| `filter` | object | yes*     | structured filter            |
+
+*at least one of `where` or `filter` is required. you cant do an unfiltered update.
+
+## Response
+
+```json
+{
+  "success": true,
+  "rows_affected": 1
+}
+```
+
+## Behaviors
+
+- a WHERE clause is **mandatory**. the server refuses to run an update without one. this is a safety thingy yk
+- columns you dont have write access to are silently stripped. `warning` is included if json derulo stripped for you
+- `last_modified_by` auto set to your user ID
+- `last_modified_at` is handled by sqls ON UPDATE trigger
+- ownership scoping applies: if you have `rwo` you can only update rows where `pinned_to` equals your user ID uness you have rwa. same deal with `rwg` for group scoping
+- limit is applied if set and capped to your max
+- auto generation rules apply on update too if configured for the update action