Merge pull request #89 from CLIMB-TRE/development

Development

docs/fields/lookups.md

@@ -13,6 +13,8 @@ Different [types][types] have different lookups available to them.
 [`[date]`][date]
 [`[datetime]`][datetime]
 [`[bool]`][bool]
+[`[array]`][array]
+[`[structure]`][structure]
 
 Return values equal to the search value.
 
@@ -54,6 +56,8 @@ Return values that are not within the set of search values.
 ## `contains`
 
 [`[text]`][text]
+[`[array]`][array]
+[`[structure]`][structure]
 
 Return values that contain the search value.
 
@@ -96,18 +100,21 @@ Return values that case-insensitively end with the search value.
 ## `length`
 
 [`[text]`][text]
+[`[array]`][array]
 
 Return values with a length equal to the search value.
 
 ## `length__in`
 
 [`[text]`][text]
+[`[array]`][array]
 
 Return values with a length that is within the set of search values.
 
 ## `length__range`
 
 [`[text]`][text]
+[`[array]`][array]
 
 Return values with a length that is within an inclusive range of search values.
 
@@ -208,9 +215,44 @@ Return values with an ISO 8601 week number that is within an inclusive range of
 [`[datetime]`][datetime]
 [`[bool]`][bool]
 [`[relation]`][relation]
+[`[array]`][array]
+[`[structure]`][structure]
 
 Return values that are empty (`isnull = True`) or non-empty (`isnull = False`). 
 
 * For [`text`][text] and [`choice`][choice] types, 'empty' is defined as the empty string `""`. 
 * For the [`relation`][relation] type, 'empty' is defined as there being zero items linked to the record being evaluated.
-* For all other types, 'empty' is the SQL `null` value.
+* For the [`array`][array] type, 'empty' is defined as the empty array `[]`.
+* For the [`structure`][structure] type, 'empty' is defined as the empty structure `{}`.
+* For all other types, 'empty' is the SQL `null` value.
+
+## `contained_by`
+
+[`[array]`][array]
+[`[structure]`][structure]
+
+Return values that are equal to, or a subset of, the search value.
+
+## `overlap`
+
+[`[array]`][array]
+
+Return values that overlap with the search value.
+
+## `has_key`
+
+[`[structure]`][structure]
+
+Return values that have a top-level key which contains the search value.
+
+## `has_keys`
+
+[`[structure]`][structure]
+
+Return values that have top-level keys which contains all of the search values.
+
+## `has_any_keys`
+
+[`[structure]`][structure]
+
+Return values that have top-level keys which contains any of the search values.

docs/fields/types.md

@@ -22,6 +22,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[length__range]`][length__range]
 [`[isnull]`][isnull]
 
+A string of characters.
+
 **Examples:** `"C-1234567890"`, `"Details about something"`
 
 ## `choice`
@@ -32,6 +34,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[notin]`][notin]
 [`[isnull]`][isnull]
 
+A restricted set of options.
+
 **Examples:** `"ENG"`, `"WALES"`, `"SCOT"`, `"NI"`
 
 ## `integer`
@@ -47,6 +51,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[range]`][range]
 [`[isnull]`][isnull]
 
+A whole number.
+
 **Examples:** `1`, `-1`, `123`
 
 ## `decimal`
@@ -62,6 +68,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[range]`][range]
 [`[isnull]`][isnull]
 
+A decimal number.
+
 **Examples:** `1.234`, `1.0`, `23.456`
 
 ## `date`
@@ -83,6 +91,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[week__range]`][week__range]
 [`[isnull]`][isnull]
 
+A date.
+
 **Examples:** `"2023-03"`, `"2023-04-05"`, `"2024-01-01"` 
 
 ## `datetime`
@@ -104,6 +114,8 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[week__range]`][week__range]
 [`[isnull]`][isnull]
 
+A date and time.
+
 **Examples:** `"2023-01-01 15:30:03"`, `"2024-01-01 09:30:17"`
 
 ## `bool`
@@ -114,8 +126,41 @@ Each field belongs to a certain type. This dictates what kind of data the field
 [`[notin]`][notin]
 [`[isnull]`][isnull]
 
+A true or false value.
+
 **Examples:** `True`, `False`
 
 ## `relation`
 
-[`[isnull]`][isnull]
+[`[isnull]`][isnull]
+
+A link to a row, or multiple rows, in another table.
+
+## `array`
+
+[`[exact]`][exact]
+[`[contains]`][contains]
+[`[contained_by]`][contained_by]
+[`[overlap]`][overlap]
+[`[length]`][length]
+[`[length__in]`][length__in]
+[`[length__range]`][length__range]
+[`[isnull]`][isnull]
+
+A list of values.
+
+**Examples:** `[1, 2, 3]`, `["hello", "world", "!"]`
+
+## `structure`
+
+[`[exact]`][exact]
+[`[contains]`][contains]
+[`[contained_by]`][contained_by]
+[`[has_key]`][has_key]
+[`[has_keys]`][has_keys]
+[`[has_any_keys]`][has_any_keys]
+[`[isnull]`][isnull]
+
+An arbitrary JSON structure.
+
+**Examples:** `{"hello" : "world", "goodbye" : "!"}`, `{"numbers" : [1, 2, {"more_numbers" : [3, 4, 5]}]}`