1 files changed, 63 insertions, 0 deletions
diff --git a/query/batch.md b/query/batch.md
new file mode 100644
index 0000000..471adf5
--- /dev/null
+++ b/query/batch.md
@@ -0,0 +1,63 @@
+# Batch Queries
+
+[back to query](README.md) /// [home](../README.md)
+
+Run multiple queries of the same type in one request. All should share the same `action` and `table`.
+
+## Request
+
+```json
+{
+  "action": "insert",
+  "table": "items",
+  "queries": [
+    { "data": { "name": "Widget A", "price": 10 } },
+    { "data": { "name": "Widget B", "price": 20 } },
+    { "data": { "name": "Widget C", "price": 30 } }
+  ],
+  "rollback_on_error": true
+}
+```
+
+## Fields
+
+| Field               | Type    | Required | Notes                                                       |
+|---------------------|---------|----------|-------------------------------------------------------------|
+| `action`            | string  | yes      | shared across all sub queries                               |
+| `table`             | string  | yes      | shared across all sub queries                               |
+| `queries`           | array   | yes      | array of individual query bodies (without action and table) |
+| `rollback_on_error` | boolean | no       | default false. if true, any failure rolls back everything   |
+
+Each item in `queries` can have the same fields as a normal single query (columns, data, where, filter, limit, offset, order_by) just without repeating action and table.
+
+## Permission
+
+Batch operations should require the `allow_batch_operations` permission for your power level (on `jde_groups`). Without it you get a 403. 
+
+Someday better granularity of this permission might be introduced but for now this should suffice.
+
+## How it should work
+
+- everything runs in a single transaction
+- for INSERT batches the server should ideally be smart about it and combine them into one multi row INSERT statement instead of doing N individual inserts (way faster)
+- for SELECT and COUNT each sub query runs individually within the transaction
+- if `rollback_on_error` is true and any sub query fails the entire batch should be rolled back and nothing committed
+- if `rollback_on_error` is false (default) failures are reported but successful queries still commit
+
+## Response
+
+Success looks the same as the individual action responses but with a `results` array for partial success/failure scenarios.
+
+When `rollback_on_error` is true and something fails:
+
+```json
+{
+  "success": false,
+  "error": "Batch operation failed, all changes rolled back [request_id: abc123]",
+  "results": [
+    { "success": true, "rows_affected": 1 },
+    { "success": false, "error": "duplicate key" },
+    { "success": true, "rows_affected": 1 }
+  ]
+}
+```