API/Queries/Attributes.md

@@ -4,11 +4,11 @@ https://metacpan.org/pod/distribution/DBIx-Class/lib/DBIx/Class/ResultSet.pm#ATT
 
 The IronAPI supports these options:
 
-- order_by
-- [join and prefetch](#Join and Prefetch)
+- [join and prefetch](#join-and-prefetch)
 - (+)columns
 - (+)select
 - (+)as
+- order_by
 - group_by
 - collapse
 - having
@@ -25,30 +25,49 @@ This document will cover some of the options with specific examples.
 
 # Join and Prefetch
 
-    RESTRICTIONS: keys and values may not contain spaces.
+'join' will join another entity to the base resultset without fetching any of it's attributes. Prefetch
+will join and fetch all the attributes of the other entity.
 
-    If a table column references another table column, use the column name to join it:
+Only references may be joined/prefetched. There are two ways to do this, depending on the direction of the reference:
 
-```JSON
-#/data/sytem/entity/query
+1. An attribute of an entity is a reference to an attribute of another entity, use the attribute name to join or prefetch it:
+
+system.entity.module is a reference to system.module.id:
+
+`POST /data/sytem/entity/query`
 
+```json
 {
     "attrs" : {"prefetch":"module"}
 }
 ```
 
-If a table is being references by another table, use `$model__$entity__$attribute` to join it:
+This fetches all the details of the linked module entry to each entity entry.
 
-(This will get all transitions which have the instance as pre_state)
+2. An attribute of an entity is being references by another attibute of a different entity, use `$model__$entity__$attribute` to join it:
+
+system.module.id is being referenced by system.entity.module:
+
+`POST /data/system/module/query`
 
-```JSON
-#/data/system/state/query
 
+```json
 {
-    "attrs": {"prefetch" : "system__transition__pre_state"}
+  "attrs" : {"prefetch":"system__entity__module"}
 }
 ```
 
+This fetches all entity entries for a module and lists them under the module.
+
+## Restrictions
+
+Keys and values may not contain spaces.
+
+## Examples
+
+
+
+
 Combined with query conditions:
 
 (This will get all transitions which have the instance as pre_state and whose post_state is 2)