1 files changed, 51 insertions, 0 deletions
diff --git a/query/README.md b/query/README.md
new file mode 100644
index 0000000..54e99af
--- /dev/null
+++ b/query/README.md
@@ -0,0 +1,51 @@
+# Query
+
+[back to index](../README.md)
+
+The `/query` endpoint is where all database operations happen. One endpoint, one JSON DERULO format, multiple actions. Pretty much the heart of jsonderulo <3 and whats the minimum requirement for JSON DERULO v1 compliance (in addition to authentication).
+
+## Pages
+
+### Actions
+- [Select](select.md) read rows from tables
+- [Insert](insert.md) add new rows
+- [Update](update.md) modify existing rows
+- [Delete](delete.md) remove rows
+- [Count](count.md) count matching rows
+
+### Features
+- [Filters](filters.md) where clauses, structured filters, joins, ordering
+- [Batch](batch.md) run multiple queries of the same type in one request
+
+## How it works
+
+`POST /query` with a JSONDERULO body. The `action` field tells the server what you want to do. The `table` field tells it which table.
+
+```json
+{
+  "action": "select",
+  "table": "items"
+}
+```
+
+Thats the simplest possible query. Selects all columns from the items table with the default limit applied.
+
+Every query should run inside a transaction. The server should set `@current_user_id` and `@request_id` as SQL session variables before running your query so triggers and stuff can reference them if needed in your schema.
+
+## Auth
+
+Bearer token required. The server should ALWAYS check your permissions for the target table (and any joined tables) before doing anything. See [permissions](../permissions/README.md) for how that works.
+
+## Common Response Fields
+
+Every response has `success` (boolean). Beyond that:
+
+| Action | Extra fields                                 |
+|--------|----------------------------------------------|
+| select | `data` (array of rows), optionally `warning` |
+| insert | `data` (last insert id), `rows_affected`     |
+| update | `rows_affected`, if applicable `warning`     |
+| delete | `rows_affected`, if applicable `warning`     |
+| count  | `data` (the count as a number)               |
+
+The `warning` field should appear when json derulo striped for you, example : your limit being capped to a maximum or blocked columns being stripped away by json derulo stripping. its not an error just a hey bbgurl please comply to what you're allowed to do and to json derulos orders!