Create extended_age_query.md

Author: CarolineDenis

sphinx/technical_decisions/extended_age_query.md

@@ -0,0 +1,67 @@
+# Extended Age Query (EAQ) Design & Implementation
+
+## Overview
+
+The Extended Age Query (EAQ) feature enhances query capabilities for **Collection Objects (COs)** in the Query Builder by enabling filters based on geological age. Available in Geology, Invertebrate Paleontology, and Vertebrate Paleontology disciplines, EAQ supports both named time periods and explicit numerical ranges using start/end values (in Millions of Years Ago, MYA).
+
+## Core Logic & Filtering Criteria
+
+- **Numeric-Based Logic**  
+  EAQ exclusively uses numerical start and end values; no names are directly used for computation—names are converted into numeric ranges by the system.
+
+- **Valid Periods Only**  
+  Only Chronostratigraphy nodes from the `GeologicTimePeriod` table with valid `StartPeriod` and `EndPeriod` values (where StartPeriod > EndPeriod) are considered for queries.
+
+- **Range Calculation**  
+  The query computes its range using:
+  - **Lowest** `EndPeriod` across relevant nodes
+  - **Highest** `StartPeriod` across relevant nodes  
+  Because MYA increases into the past, higher StartPeriod means older boundary.
+
+## User Interface & Workflow
+
+1. **Add Age Field**  
+   In the Query Builder, users select "Age" on their Collection Object query.
+
+2. **Select Query Method**  
+   - **Name**: User enters a geological time period name, which the system converts into start/end values and displays the name in the UI.  
+   - **Range**: User enters explicit start and end numeric values (e.g., `15` and `5` for 15–5 MYA).
+
+3. **Choose Search Mode**  
+   - **Strict**: Returns COs whose entire age range lies within the specified window.  
+   - **Non-strict**: Returns COs whose age ranges overlap at all with the specified window.
+
+4. **Execute Query**  
+   The system determines the applicable age range using either the named period or numeric values and filters results accordingly.
+
+## Search Scope Across Age Fields
+
+EAQ applies to the following age contexts within Collection Objects:
+
+- **Relative Age**  
+  Uses `AgeNameID` (FK to `GeologicTimePeriod`) to establish a chronostratigraphic linkage and then applies the underlying start/end values.
+
+- **Absolute Age**  
+  Computes a range using: AbsoluteAge + AgeUncertainty to AbsoluteAge – AgeUncertainty
+- **Paleo Context**  
+Bound by `ChronosStratID` (and optionally `ChronosStratEndID`). The system determines the widest combined range across both IDs using start/end values.
+
+These three contexts are searched independently according to their respective logic.
+
+## MVP Scope
+
+For the Minimum Viable Product (MVP), the EAQ will only operate on **Collection Objects**.
+
+## Summary Table
+
+| Feature                 | Behavior                                                                 |
+|------------------------|--------------------------------------------------------------------------|
+| Numeric Logic Only     | Only start/end MYA values are used—names are converted internally        |
+| Valid Periods Only     | Filters apply only to Chronostrat nodes with valid start/end values      |
+| Range Computation      | Uses lowest EndPeriod and highest StartPeriod for range boundaries       |
+| Query Methods          | Supports both named period and explicit numeric range input              |
+| Strict vs Non-strict   | Determines whether results must fully fall within or just overlap range  |
+| Search Contexts        | Applies across Relative Age, Absolute Age, and Paleo Context             |
+| Availability           | Limited to Collection Object queries for MVP                            |
+
+