JAYSON DERULO

1 files changed, 67 insertions, 0 deletions

diff --git a/query/select.md b/query/select.md
new file mode 100644
index 0000000..0b84dc8
--- /dev/null
+++ b/query/select.md
@@ -0,0 +1,67 @@
+# Select
+
+[back to query](README.md) /// [home](../README.md)
+
+Read rows from a table.
+
+## Request
+
+```json
+{
+  "action": "select",
+  "table": "items",
+  "columns": ["id", "name", "price"],
+  "filter": {
+    "and": [
+      { "column": "status", "op": "=", "value": "active" },
+      { "column": "price", "op": ">", "value": 10 }
+    ]
+  },
+  "joins": [
+    {
+      "table": "categories",
+      "on": "items.category_id = categories.id",
+      "type": "LEFT"
+    }
+  ],
+  "order_by": [
+    { "column": "name", "direction": "ASC" }
+  ],
+  "limit": 50,
+  "offset": 0
+}
+```
+
+## Fields
+
+| Field      | Type             | Required | Default        | Notes                                                        |
+|------------|------------------|----------|----------------|--------------------------------------------------------------|
+| `action`   | string           | yes      |                | must be `"select"`                                           |
+| `table`    | string           | yes      |                | target table                                                 |
+| `columns`  | array of strings | no       | all columns    | which columns to return                                      |
+| `where`    | object           | no       |                | simple key value filter (see [filters](filters.md))          |
+| `filter`   | object           | no       |                | structured filter with operators (see [filters](filters.md)) |
+| `joins`    | array            | no       |                | join other tables (see [filters](filters.md))                |
+| `order_by` | array            | no       |                | sort results (see [filters](filters.md))                     |
+| `limit`    | integer          | no       | server default | max rows to return                                           |
+| `offset`   | integer          | no       | 0              | skip this many rows                                          |
+
+## Response
+
+```json
+{
+  "success": true,
+  "data": [
+    { "id": 1, "name": "Widget", "price": 19.99 },
+    { "id": 2, "name": "Gadget", "price": 29.99 }
+  ]
+}
+```
+
+## Behaviors
+
+- if you dont specify `columns` you get all columns you have read access to
+- if you request columns youre not allowed to see they should get silently stripped and a `warning` should be included so you know json derulo censored you
+- `limit` should be auto applied if you dont set one (from config defaults). if you set one higher than your allowed max it gets capped and a `warning` tells you
+- ownership scoping should be automatically applied based on your permission level (see [ownership](../permissions/ownership.md))
+- you need read permission on every joined table in regards to what you want to join obv. otherwise your whole query gets spanked by jsonderulo!