API/Queries/Attributes.md

@@ -8,8 +8,8 @@ The IronAPI supports these options:
 
 - [join and prefetch](#join-and-prefetch)
 - [(+)columns](#columns)
-- (+)select
-- (+)as
+- [(+)select](#select-and-as)
+- [(+)as](#select-and-as)
 - [order_by](#ordering)
 - group_by
 - collapse
@@ -120,7 +120,8 @@ More documentation on joining can be found here:
 ## Restrictions
 
 'attributes' may be a scalar or a list of scalars referencing one of the fetched attributes.
-E.g. `"name"`, `"me.name"`, `["me.name","module.id"]`.
+E.g. `"name"`, `"me.name"`, `["me.name","module.id"]`. It may also be a selector for a json(b) attribute:
+`me.data->>'ident'`.
 
 ## Examples
 
@@ -181,7 +182,7 @@ For each entry in "select" a corresponding entry in "as" must be present to name
 
 Only [permitted functions](#permitted-functions) may be called. The value of the call might be itself a function call, like `{"max" : "coalesce(me.id,1)"}`.
 This function must again be in the list of permitted functions and it's parameters can only be column identifiers or values which match the regular expression
-used to check column names (`^[a-zA-Z0-9\.\_]+$`).
+used to check [column names](#permitted-column-names).
 
 ## Examples
 
@@ -282,13 +283,14 @@ Ordering can be defined by the "order_by" attribute.
 |{"-desc" => "colB"}           | ORDER BY colB DESC|
 |["colA", {-asc => "colB"}]    | ORDER BY colA, colB ASC|
 |{ "-asc" => ["colA","colB"] } | ORDER BY colA ASC, colB ASC|
-|[ "FUNC(colA,?)", "bla" ]     | ORDER BY FUNC(colA, ?) /* with "bla bound to ? */|
-|[ <br>{ "-asc" => "colA" },<br>{ "-desc" => ["colB"] },<br>{ "-asc" => ["colC","colD"] },<br>[ "FUNC(colF, ?)", "bla" ],<br>]  | ORDER BY, colA ASC,<br>colB DESC,<br>colC ASC, colD ASC,<br>FUNC(colF, ?) /* with "bla" bound to ? */ |
+|[ "FUNC(colA,?)", "bla" ]     | ORDER BY FUNC(colA, ?) - with "bla bound to ? |
+|[ <br>{ "-asc" => "colA" },<br>{ "-desc" => ["colB"] },<br>{ "-asc" => ["colC","colD"] },<br>[ "FUNC(colF, ?)", "bla" ],<br>]  | ORDER BY, colA ASC,<br>colB DESC,<br>colC ASC, colD ASC,<br>FUNC(colF, ?) - with "bla" bound to ?  |
 
 
 The API also supports [similarity](/API/Queries/Query-Search-Options#similarity) for sorting.
 
 Any column from a joined/prefetched table or a column selected with ["select"](#select-as) can be used.
+A json selector on a column may also be used (e.g. `me.data->>'ident'`).
 
 More details can be found here: <https://metacpan.org/pod/SQL::Abstract::Classic#ORDER-BY-CLAUSES>
 
@@ -331,6 +333,18 @@ Multiple sort parameters may be listed in the order they should be applied with:
 }
 ```
 
+### Function call
+
+`POST /data/system/entity/query`
+
+```json
+{
+  "attrs": {
+    "order_by": ["coalesce(me.id,?)",1]
+  }
+}
+```
+
 Similarity;
 
 `POST /data/system/entity/query`
@@ -349,6 +363,22 @@ Similarity;
 }
 ```
 
+A column defined by select and as:
+
+`POST /data/system/entity/query`
+
+```
+{
+  "attrs": {
+    "join": "module",
+    "columns" : "me.id",
+    "+select" : [{"count" : "module.id", "-as" : "module_count"}],
+    "order_by": "module_count",
+    "group_by" : "me.id"
+  }
+}
+```
+
 # Collapse
 
 When "collape" is set to a true value, indicates that any rows fetched from joined has_many relationships
@@ -449,6 +479,11 @@ Note that "prefetch" is a shortcut for "join", adding all columns from the joine
 
 https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#collapse
 
+# Permitted Column Names
+
+Wherever a column is defined, it may be a simple name if it's unique e.g. `id`, or with the entity prefix `me.id`.
+For json columns, a selector may be defined: `data->>'ident'` or `me.data->>'ident'.
+
 # Permitted functions
 
 For any attribute which allows to call a function, this function must be permitted. Apart from