FAQ, Boolean (non-)use

ga4gh-beacon · Aug 8, 2023 · a793c8c · a793c8c
1 parent 89e3b9d
commit a793c8c
Show file tree

Hide file tree

Showing 2 changed files with 28 additions and 1 deletion.
diff --git a/docs/FAQ.md b/docs/FAQ.md
@@ -149,5 +149,18 @@
     representations and will be adopted by Beacon v2.n after reaching a release state.
 
 
+?? faq "Does the Beacon protocol support Boolean expressions?"
+
+!!! Note "Boolean Logic Between Filtering Terms"
+
+    No (...but). Beacon queries as of v2 always assume a logical **AND** between query parameters
+    and individual filters, _i.e._ all conditions have to be met. There is currently
+    no support for Boolean expressions.
+    However, a logical exception is the use of multiple filters for the same parameter which
+    a Beacon implementation should treat as a logical **OR** since they otherwise
+    would fail in most instances. E.g. the query using `NCIT:C3493` and `NCIT:C2926`
+    (mapped against `biosample.histological_diagnosis.id`) would match both
+    _Lung Non-Small Cell Carcinoma_ (NCIT:C2926) and _Lung Squamous Cell Carcinoma_
+    (NCIT:C3493) which are exclusive diagnoses. 
 
 
diff --git a/docs/filters.md b/docs/filters.md
@@ -79,7 +79,21 @@ Alphanumerical value Filter types contain:
 
 ## Using Filters in Queries
 
-For all query types, the logical `AND` is implied between Filters. The Filter `id` is required for all query types.
+The Filter `id` is required for all query types. For all query types, the logical
+**AND** is _implied_ between Filters. 
+
+!!! Note "Boolean Logic Between Filtering Terms"
+
+	Beacon queries as of v2 always assume a logical **AND** between query parameters
+	and individual filters, _i.e._ all conditions have to be met. There is currently
+	no support for Boolean expressions.
+	However, a logical exception is the use of multiple filters for the same parameter which
+	a Beacon implementation should treat as a logical **OR** since they otherwise
+	would fail in most instances. E.g. the query using `NCIT:C3493` and `NCIT:C2926`
+	(mapped against `biosample.histological_diagnosis.id`) would match both
+	_Lung Non-Small Cell Carcinoma_ (NCIT:C2926) and _Lung Squamous Cell Carcinoma_
+	(NCIT:C3493) which are exclusive diagnoses. 
+
 
 !!! Note "Filters in `GET` Requests"