sapiopycommons 2024.11.11a364__py3-none-any.whl → 2024.11.18a366__py3-none-any.whl

sapiopycommons/recordmodel/record_handler.py

@@ -1,11 +1,15 @@
+from __future__ import annotations
+
 from collections.abc import Iterable
-from typing import Any
+from weakref import WeakValueDictionary
 
 from sapiopylib.rest.DataRecordManagerService import DataRecordManager
 from sapiopylib.rest.User import SapioUser
+from sapiopylib.rest.pojo.CustomReport import CustomReportCriteria, RawReportTerm, ReportColumn
 from sapiopylib.rest.pojo.DataRecord import DataRecord
 from sapiopylib.rest.pojo.DataRecordPaging import DataRecordPojoPageCriteria
-from sapiopylib.rest.pojo.webhook.WebhookContext import SapioWebhookContext
+from sapiopylib.rest.pojo.datatype.FieldDefinition import FieldType
+from sapiopylib.rest.pojo.eln.SapioELNEnums import ElnBaseDataType
 from sapiopylib.rest.utils.autopaging import QueryDataRecordsAutoPager, QueryDataRecordByIdListAutoPager, \
     QueryAllRecordsOfTypeAutoPager
 from sapiopylib.rest.utils.recordmodel.PyRecordModel import PyRecordModel
@@ -14,8 +18,10 @@ from sapiopylib.rest.utils.recordmodel.RecordModelManager import RecordModelMana
 from sapiopylib.rest.utils.recordmodel.RecordModelWrapper import WrappedType, WrappedRecordModel
 from sapiopylib.rest.utils.recordmodel.RelationshipPath import RelationshipPath, RelationshipNode, \
     RelationshipNodeType
+from sapiopylib.rest.utils.recordmodel.ancestry import RecordModelAncestorManager
 
-from sapiopycommons.general.aliases import RecordModel, SapioRecord, FieldMap
+from sapiopycommons.general.aliases import RecordModel, SapioRecord, FieldMap, FieldIdentifier, AliasUtil, \
+    FieldIdentifierMap, FieldValue, UserIdentifier, FieldIdentifierKey
 from sapiopycommons.general.custom_report_util import CustomReportUtil
 from sapiopycommons.general.exceptions import SapioException
 
@@ -30,16 +36,38 @@ class RecordHandler:
     rec_man: RecordModelManager
     inst_man: RecordModelInstanceManager
     rel_man: RecordModelRelationshipManager
+    an_man: RecordModelAncestorManager
+
+    __instances: WeakValueDictionary[SapioUser, RecordHandler] = WeakValueDictionary()
+    __initialized: bool
+
+    def __new__(cls, context: UserIdentifier):
+        """
+        :param context: The current webhook context or a user object to send requests from.
+        """
+        user = AliasUtil.to_sapio_user(context)
+        obj = cls.__instances.get(user)
+        if not obj:
+            obj = object.__new__(cls)
+            obj.__initialized = False
+            cls.__instances[user] = obj
+        return obj
 
-    def __init__(self, context: SapioWebhookContext | SapioUser):
+    def __init__(self, context: UserIdentifier):
         """
         :param context: The current webhook context or a user object to send requests from.
         """
+        self.user = AliasUtil.to_sapio_user(context)
+        if self.__initialized:
+            return
+        self.__initialized = True
+
         self.user = context if isinstance(context, SapioUser) else context.user
         self.dr_man = DataRecordManager(self.user)
         self.rec_man = RecordModelManager(self.user)
         self.inst_man = self.rec_man.instance_manager
         self.rel_man = self.rec_man.relationship_manager
+        self.an_man = RecordModelAncestorManager(self.rec_man)
 
     def wrap_model(self, record: DataRecord, wrapper_type: type[WrappedType]) -> WrappedType:
         """
@@ -49,6 +77,7 @@ class RecordHandler:
         :param wrapper_type: The record model wrapper to use.
         :return: The record model for the input.
         """
+        self.__verify_data_type([record], wrapper_type)
         return self.inst_man.add_existing_record_of_type(record, wrapper_type)
 
     def wrap_models(self, records: Iterable[DataRecord], wrapper_type: type[WrappedType]) -> list[WrappedType]:
@@ -59,10 +88,11 @@ class RecordHandler:
         :param wrapper_type: The record model wrapper to use.
         :return: The record models for the input.
         """
+        self.__verify_data_type(records, wrapper_type)
         return self.inst_man.add_existing_records_of_type(list(records), wrapper_type)
 
-    def query_models(self, wrapper_type: type[WrappedType], field: str, value_list: Iterable[Any],
-                     page_limit: int | None = None) -> list[WrappedType]:
+    def query_models(self, wrapper_type: type[WrappedType], field: FieldIdentifier, value_list: Iterable[FieldValue],
+                     page_limit: int | None = None, page_size: int | None = None) -> list[WrappedType]:
         """
         Shorthand for using the data record manager to query for a list of data records by field value
         and then converting the results into a list of record models.
@@ -70,12 +100,63 @@ class RecordHandler:
         :param wrapper_type: The record model wrapper to use.
         :param field: The field to query on.
         :param value_list: The values of the field to query on.
-        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
         :return: The record models for the queried records.
         """
-        return self.query_models_with_criteria(wrapper_type, field, value_list, None, page_limit)[0]
+        criteria: DataRecordPojoPageCriteria | None = None
+        if page_size is not None:
+            criteria = DataRecordPojoPageCriteria(page_size=page_size)
+        return self.query_models_with_criteria(wrapper_type, field, value_list, criteria, page_limit)[0]
 
-    def query_models_with_criteria(self, wrapper_type: type[WrappedType], field: str, value_list: Iterable[Any],
+    def query_and_map_models(self, wrapper_type: type[WrappedType], field: FieldIdentifier,
+                             value_list: Iterable[FieldValue], page_limit: int | None = None,
+                             page_size: int | None = None, *, mapping_field: FieldIdentifier | None = None) \
+            -> dict[FieldValue, list[WrappedType]]:
+        """
+        Shorthand for using query_models to search for records given values on a specific field and then using
+        map_by_field to turn the returned list into a dictionary mapping field values to records.
+
+        :param wrapper_type: The record model wrapper to use.
+        :param field: The field to query and map on.
+        :param value_list: The values of the field to query on.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
+        :param mapping_field: If provided, use this field to map against instead of the field that was queried on.
+        :return: The record models for the queried records mapped by field values to the records with that value.
+        """
+        if mapping_field is None:
+            mapping_field = field
+        return self.map_by_field(self.query_models(wrapper_type, field, value_list, page_limit, page_size),
+                                 mapping_field)
+
+    def query_and_unique_map_models(self, wrapper_type: type[WrappedType], field: FieldIdentifier,
+                                    value_list: Iterable[FieldValue], page_limit: int | None = None,
+                                    page_size: int | None = None, *, mapping_field: FieldIdentifier | None = None) \
+            -> dict[FieldValue, WrappedType]:
+        """
+        Shorthand for using query_models to search for records given values on a specific field and then using
+        map_by_unique_field to turn the returned list into a dictionary mapping field values to records.
+        If any two records share the same field value, throws an exception.
+
+        :param wrapper_type: The record model wrapper to use.
+        :param field: The field to query and map on.
+        :param value_list: The values of the field to query on.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
+        :param mapping_field: If provided, use this field to map against instead of the field that was queried on.
+        :return: The record models for the queried records mapped by field values to the record with that value.
+        """
+        if mapping_field is None:
+            mapping_field = field
+        return self.map_by_unique_field(self.query_models(wrapper_type, field, value_list, page_limit, page_size),
+                                        mapping_field)
+
+    def query_models_with_criteria(self, wrapper_type: type[WrappedType], field: FieldIdentifier,
+                                   value_list: Iterable[FieldValue],
                                    paging_criteria: DataRecordPojoPageCriteria | None = None,
                                    page_limit: int | None = None) \
             -> tuple[list[WrappedType], DataRecordPojoPageCriteria]:
@@ -88,26 +169,33 @@ class RecordHandler:
         :param value_list: The values of the field to query on.
         :param paging_criteria: The paging criteria to start the query with.
         :param page_limit: The maximum number of pages to query from the starting criteria. If None, exhausts all
-            possible pages.
+            possible pages. This parameter only functions if you set a page size in the paging criteria or the platform
+            enforces a page size.
         :return: The record models for the queried records and the final paging criteria.
         """
         dt: str = wrapper_type.get_wrapper_data_type_name()
+        field: str = AliasUtil.to_data_field_name(field)
         pager = QueryDataRecordsAutoPager(dt, field, list(value_list), self.user, paging_criteria)
         pager.max_page = page_limit
         return self.wrap_models(pager.get_all_at_once(), wrapper_type), pager.next_page_criteria
 
     def query_models_by_id(self, wrapper_type: type[WrappedType], ids: Iterable[int],
-                           page_limit: int | None = None) -> list[WrappedType]:
+                           page_limit: int | None = None, page_size: int | None = None) -> list[WrappedType]:
         """
         Shorthand for using the data record manager to query for a list of data records by record ID
         and then converting the results into a list of record models.
 
         :param wrapper_type: The record model wrapper to use.
         :param ids: The list of record IDs to query.
-        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
         :return: The record models for the queried records.
         """
-        return self.query_models_by_id_with_criteria(wrapper_type, ids, None, page_limit)[0]
+        criteria: DataRecordPojoPageCriteria | None = None
+        if page_size is not None:
+            criteria = DataRecordPojoPageCriteria(page_size=page_size)
+        return self.query_models_by_id_with_criteria(wrapper_type, ids, criteria, page_limit)[0]
 
     def query_models_by_id_with_criteria(self, wrapper_type: type[WrappedType], ids: Iterable[int],
                                          paging_criteria: DataRecordPojoPageCriteria | None = None,
@@ -121,7 +209,8 @@ class RecordHandler:
         :param ids: The list of record IDs to query.
         :param paging_criteria: The paging criteria to start the query with.
         :param page_limit: The maximum number of pages to query from the starting criteria. If None, exhausts all
-            possible pages.
+            possible pages. This parameter only functions if you set a page size in the paging criteria or the platform
+            enforces a page size.
         :return: The record models for the queried records and the final paging criteria.
         """
         dt: str = wrapper_type.get_wrapper_data_type_name()
@@ -129,16 +218,38 @@ class RecordHandler:
         pager.max_page = page_limit
         return self.wrap_models(pager.get_all_at_once(), wrapper_type), pager.next_page_criteria
 
-    def query_all_models(self, wrapper_type: type[WrappedType], page_limit: int | None = None) -> list[WrappedType]:
+    def query_models_by_id_and_map(self, wrapper_type: type[WrappedType], ids: Iterable[int],
+                                   page_limit: int | None = None, page_size: int | None = None) \
+            -> dict[int, WrappedType]:
+        """
+        Shorthand for using the data record manager to query for a list of data records by record ID
+        and then converting the results into a dictionary of record ID to the record model for that ID.
+
+        :param wrapper_type: The record model wrapper to use.
+        :param ids: The list of record IDs to query.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
+        :return: The record models for the queried records mapped in a dictionary by their record ID.
+        """
+        return {x.record_id: x for x in self.query_models_by_id(wrapper_type, ids, page_limit, page_size)}
+
+    def query_all_models(self, wrapper_type: type[WrappedType], page_limit: int | None = None,
+                         page_size: int | None = None) -> list[WrappedType]:
         """
         Shorthand for using the data record manager to query for all data records of a given type
         and then converting the results into a list of record models.
 
         :param wrapper_type: The record model wrapper to use.
-        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
+        :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages. This parameter
+            only functions if you set a page size or the platform enforces a page size.
+        :param page_size: The size of the pages to query. If None, the page size may be limited by the platform.
         :return: The record models for the queried records.
         """
-        return self.query_all_models_with_criteria(wrapper_type, None, page_limit)[0]
+        criteria: DataRecordPojoPageCriteria | None = None
+        if page_size is not None:
+            criteria = DataRecordPojoPageCriteria(page_size=page_size)
+        return self.query_all_models_with_criteria(wrapper_type, criteria, page_limit)[0]
 
     def query_all_models_with_criteria(self, wrapper_type: type[WrappedType],
                                        paging_criteria: DataRecordPojoPageCriteria | None = None,
@@ -151,7 +262,8 @@ class RecordHandler:
         :param wrapper_type: The record model wrapper to use.
         :param paging_criteria: The paging criteria to start the query with.
         :param page_limit: The maximum number of pages to query from the starting criteria. If None, exhausts all
-            possible pages.
+            possible pages. This parameter only functions if you set a page size in the paging criteria or the platform
+            enforces a page size.
         :return: The record models for the queried records and the final paging criteria.
         """
         dt: str = wrapper_type.get_wrapper_data_type_name()
@@ -160,24 +272,58 @@ class RecordHandler:
         return self.wrap_models(pager.get_all_at_once(), wrapper_type), pager.next_page_criteria
 
     def query_models_by_report(self, wrapper_type: type[WrappedType],
-                               report_name: str,
-                               filters: dict[str, Iterable[Any]] | None = None,
-                               page_limit: int | None = None) -> list[WrappedType]:
+                               report_name: str | RawReportTerm | CustomReportCriteria,
+                               filters: dict[FieldIdentifierKey, Iterable[FieldValue]] | None = None,
+                               page_limit: int | None = None,
+                               page_size: int | None = None,
+                               page_number: int | None = None) -> list[WrappedType]:
         """
-        Run a system report that contains a RecordId column and query for the records with those IDs.
-        First runs the custom report, then runs a data record manager query on the results of the custom report.
+        Run a report and use the results of that report to query for and return the records in the report results.
+        First runs the report, then runs a data record manager query on the results of the custom report.
 
-        Will throw an exception if the given system report does not have a RecordId column.
+        Will throw an exception if given the name of a system report that does not have a RecordId column.
+        Quick and custom reports are guaranteed to have a record ID column.
+
+        Any given custom report criteria should only have columns from a single data type.
 
         :param wrapper_type: The record model wrapper to use.
-        :param report_name: The name of the system report to run.
+        :param report_name: The name of a system report, or a raw report term for a quick report, or custom report
+            criteria for a custom report.
         :param filters: If provided, filter the results of the report using the given mapping of headers to values to
             filter on. This filtering is done before the records are queried.
         :param page_limit: The maximum number of pages to query. If None, exhausts all possible pages.
-        :return: The record models for the queried records.
-        """
-        results: list[dict[str, Any]] = CustomReportUtil.run_system_report(self.user, report_name, filters, page_limit)
-        # Using the bracket operators because we want to throw an exception if RecordId doesn't exist in the report.
+        :param page_size: The size of each page of results in the search. If None, the page size is set by the server.
+            If the input report is a custom report criteria, uses the value from the criteria, unless this value is
+            not None, in which case it overwrites the given report's value.
+        :param page_number: The page number to start the search from, If None, starts on the first page.
+            If the input report is a custom report criteria, uses the value from the criteria, unless this value is
+            not None, in which case it overwrites the given report's value.
+        :return: The record models for the queried records that matched the given report.
+        """
+        if isinstance(report_name, str):
+            results: list[dict[str, FieldValue]] = CustomReportUtil.run_system_report(self.user, report_name, filters,
+                                                                                      page_limit, page_size, page_number)
+        elif isinstance(report_name, RawReportTerm):
+            results: list[dict[str, FieldValue]] = CustomReportUtil.run_quick_report(self.user, report_name, filters,
+                                                                                     page_limit, page_size, page_number)
+        elif isinstance(report_name, CustomReportCriteria):
+            dt: str = wrapper_type.get_wrapper_data_type_name()
+            # Ensure that the root data type is the one we're looking for.
+            report_name.root_data_type = dt
+            # Raise an exception if any column in the report doesn't match the given data type.
+            if any([x.data_type_name != dt for x in report_name.column_list]):
+                raise SapioException("You may only query records from a report containing columns from that data type.")
+            # Enforce that the given custom report has a record ID column.
+            if not any([x.data_type_name == dt and x.data_field_name == "RecordId" for x in report_name.column_list]):
+                report_name.column_list.append(ReportColumn(dt, "RecordId", FieldType.LONG))
+            results: list[dict[str, FieldValue]] = CustomReportUtil.run_custom_report(self.user, report_name, filters,
+                                                                                      page_limit, page_size, page_number)
+        else:
+            raise SapioException("Unrecognized report object.")
+
+        # Using the bracket accessor because we want to throw an exception if RecordId doesn't exist in the report.
+        # This should only possibly be the case with system reports, as quick reports will include the record ID and
+        # we forced any given custom report to have a record ID column.
         ids: list[int] = [row["RecordId"] for row in results]
         return self.query_models_by_id(wrapper_type, ids)
 
@@ -200,7 +346,8 @@ class RecordHandler:
         """
         return self.inst_man.add_new_records_of_type(num, wrapper_type)
 
-    def add_models_with_data(self, wrapper_type: type[WrappedType], fields: list[FieldMap]) -> list[WrappedType]:
+    def add_models_with_data(self, wrapper_type: type[WrappedType], fields: list[FieldIdentifierMap]) \
+            -> list[WrappedType]:
         """
         Shorthand for using the instance manager to add new models of the given type, and then initializing all those
         models with the given fields.
@@ -210,11 +357,50 @@ class RecordHandler:
         :return: The newly added record models with the provided fields set. The records will be in the same order as
             the fields in the fields list.
         """
+        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
         models: list[WrappedType] = self.add_models(wrapper_type, len(fields))
-        for model, field in zip(models, fields):
-            model.set_field_values(field)
+        for model, field_list in zip(models, fields):
+            model.set_field_values(field_list)
         return models
 
+    def find_or_add_model(self, wrapper_type: type[WrappedType], primary_identifier: FieldIdentifier,
+                          id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) -> WrappedType:
+        """
+        Find a unique record that matches the given field values. If no such records exist, add a record model to the
+        cache with the identifying fields set to the desired values. This record will be created in the system when
+        you store and commit changes. If more than one record with the identifying values exists, throws an exception.
+
+        The record is searched for using the primary identifier field name and value. If multiple records are returned
+        by the query on this primary identifier, then the secondary identifiers are used to filter the results.
+
+        Makes a webservice call to query for the existing record.
+
+        :param wrapper_type: The record model wrapper to use.
+        :param primary_identifier: The data field name of the field to search on.
+        :param id_value: The value of the identifying field to search for.
+        :param secondary_identifiers: Optional fields used to filter the records that are returned after searching on
+            the primary identifier.
+        :return: The record model with the identifying field value, either pulled from the system or newly created.
+        """
+        # PR-46335: Initialize the secondary identifiers parameter if None is provided to avoid an exception.
+        # If no secondary identifiers were provided, use an empty dictionary.
+        if secondary_identifiers is None:
+            secondary_identifiers = {}
+
+        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
+        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
+        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
+                                                              secondary_identifiers)
+        # If a unique record matched the identifiers, return it.
+        if unique_record is not None:
+            return unique_record
+
+        # If none of the results matched the identifiers, create a new record with all identifiers set.
+        # Put the primary identifier and value into the secondary identifiers list and use that as the fields map
+        # for this new record.
+        secondary_identifiers.update({primary_identifier: id_value})
+        return self.add_models_with_data(wrapper_type, [secondary_identifiers])[0]
+
     def create_models(self, wrapper_type: type[WrappedType], num: int) -> list[WrappedType]:
         """
         Shorthand for creating new records via the data record manager and then returning them as wrapped
@@ -229,7 +415,7 @@ class RecordHandler:
         dt: str = wrapper_type.get_wrapper_data_type_name()
         return self.wrap_models(self.dr_man.add_data_records(dt, num), wrapper_type)
 
-    def create_models_with_data(self, wrapper_type: type[WrappedType], fields: list[FieldMap]) \
+    def create_models_with_data(self, wrapper_type: type[WrappedType], fields: list[FieldIdentifierMap]) \
             -> list[WrappedType]:
         """
         Shorthand for creating new records via the data record manager with field data to initialize the records with
@@ -243,10 +429,12 @@ class RecordHandler:
         :return: The newly created record models.
         """
         dt: str = wrapper_type.get_wrapper_data_type_name()
+        fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(fields)
         return self.wrap_models(self.dr_man.add_data_records_with_data(dt, fields), wrapper_type)
 
-    def find_or_create_model(self, wrapper_type: type[WrappedType], primary_identifier: str, id_value: Any,
-                             secondary_identifiers: FieldMap | None = None) -> WrappedType:
+    def find_or_create_model(self, wrapper_type: type[WrappedType], primary_identifier: FieldIdentifier,
+                             id_value: FieldValue, secondary_identifiers: FieldIdentifierMap | None = None) \
+            -> WrappedType:
         """
         Find a unique record that matches the given field values. If no such records exist, create one with the
         identifying fields set to the desired values. If more than one record with the identifying values exists,
@@ -270,24 +458,10 @@ class RecordHandler:
         if secondary_identifiers is None:
             secondary_identifiers = {}
 
-        # Query for all records that match the primary identifier.
-        results: list[WrappedType] = self.query_models(wrapper_type, primary_identifier, [id_value])
-
-        # Find the one record, if any, that matches the secondary identifiers.
-        unique_record: WrappedType | None = None
-        for result in results:
-            matches_all: bool = True
-            for field, value in secondary_identifiers.items():
-                if result.get_field_value(field) != value:
-                    matches_all = False
-                    break
-            if matches_all:
-                # If a previous record in the results already matched all identifiers, then throw an exception.
-                if unique_record is not None:
-                    raise SapioException(f"More than one record of type {wrapper_type.get_wrapper_data_type_name()} "
-                                         f"encountered in system that matches all provided identifiers.")
-                unique_record = result
-
+        primary_identifier: str = AliasUtil.to_data_field_name(primary_identifier)
+        secondary_identifiers: FieldMap = AliasUtil.to_data_field_names_dict(secondary_identifiers)
+        unique_record: WrappedType | None = self.__find_model(wrapper_type, primary_identifier, id_value,
+                                                              secondary_identifiers)
         # If a unique record matched the identifiers, return it.
         if unique_record is not None:
             return unique_record
@@ -329,6 +503,29 @@ class RecordHandler:
             return_dict[model] = model.get_parents_of_type(parent_type)
         return return_dict
 
+    @staticmethod
+    def map_by_parent(models: Iterable[RecordModel], parent_type: type[WrappedType]) \
+            -> dict[WrappedType, RecordModel]:
+        """
+        Take a list of record models and map them by their parent. Essentially an inversion of map_to_parent.
+        If two records share the same parent, an exception will be thrown. The parents must already be loaded.
+
+        :param models: A list of record models.
+        :param parent_type: The record model wrapper of the parents.
+        :return: A dict[ParentType, ModelType]. If an input model doesn't have a parent of the given parent type,
+            then it will not be in the resulting dictionary.
+        """
+        to_parent: dict[RecordModel, WrappedType] = RecordHandler.map_to_parent(models, parent_type)
+        by_parent: dict[WrappedType, RecordModel] = {}
+        for record, parent in to_parent.items():
+            if parent is None:
+                continue
+            if parent in by_parent:
+                raise SapioException(f"Parent {parent.data_type_name} {parent.record_id} encountered more than once "
+                                     f"in models list.")
+            by_parent[parent] = record
+        return by_parent
+
     @staticmethod
     def map_by_parents(models: Iterable[RecordModel], parent_type: type[WrappedType]) \
             -> dict[WrappedType, list[RecordModel]]:
@@ -379,6 +576,29 @@ class RecordHandler:
             return_dict[model] = model.get_children_of_type(child_type)
         return return_dict
 
+    @staticmethod
+    def map_by_child(models: Iterable[RecordModel], child_type: type[WrappedType]) \
+            -> dict[WrappedType, RecordModel]:
+        """
+        Take a list of record models and map them by their children. Essentially an inversion of map_to_child.
+        If two records share the same child, an exception will be thrown. The children must already be loaded.
+
+        :param models: A list of record models.
+        :param child_type: The record model wrapper of the children.
+        :return: A dict[ChildType, ModelType]. If an input model doesn't have a child of the given child type,
+            then it will not be in the resulting dictionary.
+        """
+        to_child: dict[RecordModel, WrappedType] = RecordHandler.map_to_child(models, child_type)
+        by_child: dict[WrappedType, RecordModel] = {}
+        for record, child in to_child.items():
+            if child is None:
+                continue
+            if child in by_child:
+                raise SapioException(f"Child {child.data_type_name} {child.record_id} encountered more than once "
+                                     f"in models list.")
+            by_child[child] = record
+        return by_child
+
     @staticmethod
     def map_by_children(models: Iterable[RecordModel], child_type: type[WrappedType]) \
             -> dict[WrappedType, list[RecordModel]]:
@@ -399,7 +619,7 @@ class RecordHandler:
         return by_children
 
     @staticmethod
-    def map_to_forward_side_link(models: Iterable[WrappedRecordModel], field_name: str,
+    def map_to_forward_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, WrappedType]:
         """
         Map a list of record models to their forward side link. The forward side link must already be loaded.
@@ -410,14 +630,15 @@ class RecordHandler:
         :return: A dict[ModelType, SlideLink]. If an input model doesn't have a forward side link of the given type,
             then it will map to None.
         """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
         return_dict: dict[WrappedRecordModel, WrappedType] = {}
         for model in models:
             return_dict[model] = model.get_forward_side_link(field_name, side_link_type)
         return return_dict
 
     @staticmethod
-    def map_by_forward_side_link(models: Iterable[WrappedRecordModel], field_name: str,
-                                 side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
+    def map_by_forward_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
         """
         Take a list of record models and map them by their forward side link. Essentially an inversion of
         map_to_forward_side_link. Input models that share a forward side link will end up in the same list.
@@ -429,9 +650,10 @@ class RecordHandler:
         :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have a forward side link of the given type
             pointing to it, then it will not be in the resulting dictionary.
         """
-        to_side_link: dict[RecordModel, WrappedType] = RecordHandler\
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        to_side_link: dict[WrappedRecordModel, WrappedType] = RecordHandler\
             .map_to_forward_side_link(models, field_name, side_link_type)
-        by_side_link: dict[WrappedType, list[RecordModel]] = {}
+        by_side_link: dict[WrappedType, list[WrappedRecordModel]] = {}
         for record, side_link in to_side_link.items():
             if side_link is None:
                 continue
@@ -439,8 +661,35 @@ class RecordHandler:
         return by_side_link
 
     @staticmethod
-    def map_to_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: str,
-                                  side_link_type: type[WrappedType]) -> dict[RecordModel, list[WrappedRecordModel]]:
+    def map_by_forward_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType]) -> dict[WrappedType, WrappedRecordModel]:
+        """
+        Take a list of record models and map them by their forward side link. Essentially an inversion of
+        map_to_forward_side_link, but if two records share the same forward link, an exception is thrown.
+        The forward side link must already be loaded.
+
+        :param models: A list of record models.
+        :param field_name: The field name on the record models where the side link is located.
+        :param side_link_type: The record model wrapper of the forward side links.
+        :return: A dict[SideLink, ModelType]. If an input model doesn't have a forward side link of the given type
+            pointing to it, then it will not be in the resulting dictionary.
+        """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        to_side_link: dict[WrappedRecordModel, WrappedType] = RecordHandler\
+            .map_to_forward_side_link(models, field_name, side_link_type)
+        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
+        for record, side_link in to_side_link.items():
+            if side_link is None:
+                continue
+            if side_link in by_side_link:
+                raise SapioException(f"Side link {side_link.data_type_name} {side_link.record_id} encountered more "
+                                     f"than once in models list.")
+            by_side_link[side_link] = record
+        return by_side_link
+
+    @staticmethod
+    def map_to_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                  side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, list[WrappedType]]:
         """
         Map a list of record models to a list reverse side links of a given type. The reverse side links must already
         be loaded.
@@ -452,13 +701,38 @@ class RecordHandler:
         :return: A dict[ModelType, list[SideLink]]. If an input model doesn't have reverse side links of the given type,
             then it will map to an empty list.
         """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
         return_dict: dict[WrappedRecordModel, list[WrappedType]] = {}
         for model in models:
             return_dict[model] = model.get_reverse_side_link(field_name, side_link_type)
         return return_dict
 
     @staticmethod
-    def map_by_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: str,
+    def map_to_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType]) -> dict[WrappedRecordModel, WrappedType]:
+        """
+        Map a list of record models to the reverse side link of a given type. If a given record has more than one
+        reverse side link of this type, an exception is thrown. The reverse side links must already be loaded.
+
+        :param models: A list of record models.
+        :param field_name: The field name on the side linked model where the side link to the given record models is
+            located.
+        :param side_link_type: The record model wrapper of the reverse side links.
+        :return: A dict[ModelType, SideLink]. If an input model doesn't have reverse side links of the given type,
+            then it will map to None.
+        """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        return_dict: dict[WrappedRecordModel, WrappedType] = {}
+        for model in models:
+            links: list[WrappedType] = model.get_reverse_side_link(field_name, side_link_type)
+            if len(links) > 1:
+                raise SapioException(f"Model {model.data_type_name} {model.record_id} has more than one reverse link "
+                                     f"of type {side_link_type.get_wrapper_data_type_name()}.")
+            return_dict[model] = links[0] if links else None
+        return return_dict
+
+    @staticmethod
+    def map_by_reverse_side_links(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
                                   side_link_type: type[WrappedType]) -> dict[WrappedType, list[WrappedRecordModel]]:
         """
         Take a list of record models and map them by their reverse side links. Essentially an inversion of
@@ -472,14 +746,43 @@ class RecordHandler:
         :return: A dict[SideLink, list[ModelType]]. If an input model doesn't have reverse side links of the given type
             pointing to it, then it will not be in the resulting dictionary.
         """
-        to_side_links: dict[RecordModel, list[WrappedType]] = RecordHandler\
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        to_side_links: dict[WrappedRecordModel, list[WrappedType]] = RecordHandler\
             .map_to_reverse_side_links(models, field_name, side_link_type)
-        by_side_links: dict[WrappedType, list[RecordModel]] = {}
+        by_side_links: dict[WrappedType, list[WrappedRecordModel]] = {}
         for record, side_links in to_side_links.items():
             for side_link in side_links:
                 by_side_links.setdefault(side_link, []).append(record)
         return by_side_links
 
+    @staticmethod
+    def map_by_reverse_side_link(models: Iterable[WrappedRecordModel], field_name: FieldIdentifier,
+                                 side_link_type: type[WrappedType]) -> dict[WrappedType, WrappedRecordModel]:
+        """
+        Take a list of record models and map them by their reverse side link. Essentially an inversion of
+        map_to_reverse_side_link. If two records share the same reverse side link, an exception is thrown.
+        The reverse side links must already be loaded.
+
+        :param models: A list of record models.
+        :param field_name: The field name on the side linked model where the side link to the given record models is
+            located.
+        :param side_link_type: The record model wrapper of the reverse side links.
+        :return: A dict[SideLink, ModelType]. If an input model doesn't have a reverse side link of the given type
+            pointing to it, then it will not be in the resulting dictionary.
+        """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        to_side_link: dict[WrappedRecordModel, WrappedType] = RecordHandler\
+            .map_to_reverse_side_link(models, field_name, side_link_type)
+        by_side_link: dict[WrappedType, WrappedRecordModel] = {}
+        for record, side_link in to_side_link.items():
+            if side_link is None:
+                continue
+            if side_link in by_side_link:
+                raise SapioException(f"Side link {side_link.data_type_name} {side_link.record_id} encountered more "
+                                     f"than once in models list.")
+            by_side_link[side_link] = record
+        return by_side_link
+
     @staticmethod
     def map_by_id(models: Iterable[SapioRecord]) -> dict[int, SapioRecord]:
         """
@@ -494,7 +797,8 @@ class RecordHandler:
         return ret_dict
 
     @staticmethod
-    def map_by_field(models: Iterable[SapioRecord], field_name: str) -> dict[Any, list[SapioRecord]]:
+    def map_by_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, list[SapioRecord]]:
         """
         Map the given records by one of their fields. If any two records share the same field value, they'll appear in
         the same value list.
@@ -503,14 +807,16 @@ class RecordHandler:
         :param field_name: The field name to map against.
         :return: A dict mapping field values to the records with that value.
         """
-        ret_dict: dict[Any, list[SapioRecord]] = {}
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        ret_dict: dict[FieldValue, list[SapioRecord]] = {}
         for model in models:
-            val: Any = model.get_field_value(field_name)
+            val: FieldValue = model.get_field_value(field_name)
             ret_dict.setdefault(val, []).append(model)
         return ret_dict
 
     @staticmethod
-    def map_by_unique_field(models: Iterable[SapioRecord], field_name: str) -> dict[Any, SapioRecord]:
+    def map_by_unique_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) \
+            -> dict[FieldValue, SapioRecord]:
         """
         Uniquely map the given records by one of their fields. If any two records share the same field value, throws
         an exception.
@@ -519,16 +825,17 @@ class RecordHandler:
         :param field_name: The field name to map against.
         :return: A dict mapping field values to the record with that value.
         """
-        ret_dict: dict[Any, SapioRecord] = {}
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        ret_dict: dict[FieldValue, SapioRecord] = {}
         for model in models:
-            val: Any = model.get_field_value(field_name)
+            val: FieldValue = model.get_field_value(field_name)
             if val in ret_dict:
                 raise SapioException(f"Value {val} encountered more than once in models list.")
             ret_dict.update({val: model})
         return ret_dict
 
     @staticmethod
-    def sum_of_field(models: Iterable[SapioRecord], field_name: str) -> float:
+    def sum_of_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) -> float:
         """
         Sum up the numeric value of a given field across all input models. Excepts that all given models have a value.
         If the field is an integer field, the value will be converted to a float.
@@ -537,13 +844,14 @@ class RecordHandler:
         :param field_name: The name of the numeric field to sum.
         :return: The sum of the field values for the collection of models.
         """
+        field_name: str = AliasUtil.to_data_field_name(field_name)
         field_sum: float = 0
         for model in models:
             field_sum += float(model.get_field_value(field_name))
         return field_sum
 
     @staticmethod
-    def mean_of_field(models: Iterable[SapioRecord], field_name: str) -> float:
+    def mean_of_field(models: Iterable[SapioRecord], field_name: FieldIdentifier) -> float:
         """
         Calculate the mean of the numeric value of a given field across all input models. Excepts that all given models
         have a value. If the field is an integer field, the value will be converted to a float.
@@ -584,8 +892,8 @@ class RecordHandler:
         return oldest
 
     @staticmethod
-    def values_to_field_maps(field_name: str, values: Iterable[Any], existing_fields: list[FieldMap] | None = None) \
-            -> list[FieldMap]:
+    def values_to_field_maps(field_name: FieldIdentifier, values: Iterable[FieldValue],
+                             existing_fields: list[FieldIdentifier] | None = None) -> list[FieldMap]:
         """
         Add a list of values for a specific field to a list of dictionaries pairing each value to that field name.
 
@@ -596,6 +904,8 @@ class RecordHandler:
         :return: A fields map list that contains the given values mapped by the given field name.
         """
         # Update the existing fields map list if one is given.
+        field_name: str = AliasUtil.to_data_field_name(field_name)
+        existing_fields: list[FieldMap] = AliasUtil.to_data_field_names_list_dict(existing_fields)
         if existing_fields:
             values = list(values)
             # The number of new values must match the length of the existing fields list.
@@ -616,8 +926,6 @@ class RecordHandler:
         path, if any. The hierarchy must be linear (1:1 relationship between data types at every step) and the
         relationship path must already be loaded.
 
-        Currently, the relationship path may only contain parent/child nodes.
-
         :param models: A list of record models.
         :param path: The relationship path to follow.
         :param wrapper_type: The record model wrapper to use.
@@ -628,15 +936,44 @@ class RecordHandler:
         # PR-46832: Update path traversal to account for changes to RelationshipPath in Sapiopylib.
         path: list[RelationshipNode] = path.path
         for model in models:
-            current: PyRecordModel = model if isinstance(model, PyRecordModel) else model.backing_model
+            current: PyRecordModel | None = model if isinstance(model, PyRecordModel) else model.backing_model
             for node in path:
-                direction = node.direction
+                data_type: str = node.data_type_name
+                direction: RelationshipNodeType = node.direction
                 if current is None:
                     break
                 if direction == RelationshipNodeType.CHILD:
-                    current = current.get_child_of_type(node.data_type_name)
+                    current = current.get_child_of_type(data_type)
                 elif direction == RelationshipNodeType.PARENT:
-                    current = current.get_parent_of_type(node.data_type_name)
+                    current = current.get_parent_of_type(data_type)
+                elif direction == RelationshipNodeType.ANCESTOR:
+                    ancestors: list[PyRecordModel] = list(self.an_man.get_ancestors_of_type(current, data_type))
+                    if not ancestors:
+                        current = None
+                    elif len(ancestors) > 1:
+                        raise SapioException(f"Hierarchy contains multiple ancestors of type {data_type}.")
+                    else:
+                        current = ancestors[0]
+                elif direction == RelationshipNodeType.DESCENDANT:
+                    descendants: list[PyRecordModel] = list(self.an_man.get_descendant_of_type(current, data_type))
+                    if not descendants:
+                        current = None
+                    elif len(descendants) > 1:
+                        raise SapioException(f"Hierarchy contains multiple descendants of type {data_type}.")
+                    else:
+                        current = descendants[0]
+                elif direction == RelationshipNodeType.FORWARD_SIDE_LINK:
+                    current = current.get_forward_side_link(node.data_field_name)
+                elif direction == RelationshipNodeType.REVERSE_SIDE_LINK:
+                    field_name: str = node.data_field_name
+                    reverse_links: list[PyRecordModel] = current.get_reverse_side_link(field_name, data_type)
+                    if not reverse_links:
+                        current = None
+                    elif len(reverse_links) > 1:
+                        raise SapioException(f"Hierarchy contains multiple reverse links of type {data_type} on field "
+                                             f"{field_name}.")
+                    else:
+                        current = reverse_links[0]
                 else:
                     raise SapioException("Unsupported path direction.")
             ret_dict.update({model: self.inst_man.wrap(current, wrapper_type) if current else None})
@@ -649,8 +986,6 @@ class RecordHandler:
         path, if any. The hierarchy may be non-linear (1:Many relationships between data types are allowed) and the
         relationship path must already be loaded.
 
-        Currently, the relationship path may only contain parent/child nodes.
-
         :param models: A list of record models.
         :param path: The relationship path to follow.
         :param wrapper_type: The record model wrapper to use.
@@ -665,14 +1000,23 @@ class RecordHandler:
             next_search: set[PyRecordModel] = set()
             # Exhaust the records at each step in the path, then use those records for the next step.
             for node in path:
-                direction = node.direction
+                data_type: str = node.data_type_name
+                direction: RelationshipNodeType = node.direction
                 if len(current_search) == 0:
                     break
                 for search in current_search:
                     if direction == RelationshipNodeType.CHILD:
-                        next_search.update(search.get_children_of_type(node.data_type_name))
+                        next_search.update(search.get_children_of_type(data_type))
                     elif direction == RelationshipNodeType.PARENT:
-                        next_search.update(search.get_parents_of_type(node.data_type_name))
+                        next_search.update(search.get_parents_of_type(data_type))
+                    elif direction == RelationshipNodeType.ANCESTOR:
+                        next_search.update(self.an_man.get_ancestors_of_type(search, data_type))
+                    elif direction == RelationshipNodeType.DESCENDANT:
+                        next_search.update(self.an_man.get_descendant_of_type(search, data_type))
+                    elif direction == RelationshipNodeType.FORWARD_SIDE_LINK:
+                        next_search.add(search.get_forward_side_link(node.data_field_name))
+                    elif direction == RelationshipNodeType.REVERSE_SIDE_LINK:
+                        next_search.update(search.get_reverse_side_link(node.data_field_name, data_type))
                     else:
                         raise SapioException("Unsupported path direction.")
                 current_search = next_search
@@ -690,11 +1034,9 @@ class RecordHandler:
         relationship path must already be loaded.
 
         The path is "flattened" by only following the first record at each step. Useful for traversing 1-to-Many-to-1
-        relationships (e.g. a sample with is aliquoted to a number of samples, then those aliquots are pooled back
+        relationships (e.g. a sample which is aliquoted to a number of samples, then those aliquots are pooled back
         together into a single sample).
 
-        Currently, the relationship path may only contain parent/child nodes.
-
         :param models: A list of record models.
         :param path: The relationship path to follow.
         :param wrapper_type: The record model wrapper to use.
@@ -707,22 +1049,64 @@ class RecordHandler:
         for model in models:
             current: list[PyRecordModel] = [model if isinstance(model, PyRecordModel) else model.backing_model]
             for node in path:
-                direction = node.direction
+                data_type: str = node.data_type_name
+                direction: RelationshipNodeType = node.direction
                 if len(current) == 0:
                     break
                 if direction == RelationshipNodeType.CHILD:
-                    current = current[0].get_children_of_type(node.data_type_name)
+                    current = current[0].get_children_of_type(data_type)
                 elif direction == RelationshipNodeType.PARENT:
-                    current = current[0].get_parents_of_type(node.data_type_name)
+                    current = current[0].get_parents_of_type(data_type)
+                elif direction == RelationshipNodeType.ANCESTOR:
+                    current = list(self.an_man.get_ancestors_of_type(current[0], data_type))
+                elif direction == RelationshipNodeType.DESCENDANT:
+                    current = list(self.an_man.get_descendant_of_type(current[0], data_type))
+                elif direction == RelationshipNodeType.FORWARD_SIDE_LINK:
+                    current = [current[0].get_forward_side_link(node.data_field_name)]
+                elif direction == RelationshipNodeType.REVERSE_SIDE_LINK:
+                    current = current[0].get_reverse_side_link(node.data_field_name, data_type)
                 else:
                     raise SapioException("Unsupported path direction.")
             ret_dict.update({model: self.inst_man.wrap(current[0], wrapper_type) if current else None})
         return ret_dict
 
-    def __exhaust_query_pages(self, data_type_name: str, field: str, value_list: list[Any],
-                              paging_criteria: DataRecordPojoPageCriteria | None,
-                              page_limit: int | None) \
-            -> tuple[list[DataRecord], DataRecordPojoPageCriteria | None]:
-        pager = QueryDataRecordsAutoPager(data_type_name, field, value_list, self.user, paging_criteria)
-        pager.max_page = page_limit
-        return pager.get_all_at_once(), pager.next_page_criteria
+    def __find_model(self, wrapper_type: type[WrappedType], primary_identifier: str, id_value: FieldValue,
+                     secondary_identifiers: FieldIdentifierMap | None = None) -> WrappedType | None:
+        """
+        Find a record from the system that matches the given field values. The primary identifier and value is used
+        to query for the record, then the secondary identifiers may be optionally provided to further filter the
+        returned results. If no record is found with these filters, returns None.
+        """
+        # Query for all records that match the primary identifier.
+        results: list[WrappedType] = self.query_models(wrapper_type, primary_identifier, [id_value])
+
+        # Find the one record, if any, that matches the secondary identifiers.
+        unique_record: WrappedType | None = None
+        for result in results:
+            matches_all: bool = True
+            for field, value in secondary_identifiers.items():
+                if result.get_field_value(field) != value:
+                    matches_all = False
+                    break
+            if matches_all:
+                # If a previous record in the results already matched all identifiers, then throw an exception.
+                if unique_record is not None:
+                    raise SapioException(f"More than one record of type {wrapper_type.get_wrapper_data_type_name()} "
+                                         f"encountered in system that matches all provided identifiers.")
+                unique_record = result
+        return unique_record
+
+    @staticmethod
+    def __verify_data_type(records: Iterable[DataRecord], wrapper_type: type[WrappedType]) -> None:
+        """
+        Throw an exception if the data type of the given records and wrapper don't match.
+        """
+        model_type: str = wrapper_type.get_wrapper_data_type_name()
+        for record in records:
+            record_type: str = record.data_type_name
+            # Account for ELN data type records.
+            if ElnBaseDataType.is_eln_type(record_type):
+                record_type = ElnBaseDataType.get_base_type(record_type).data_type_name
+            if record_type != model_type:
+                raise SapioException(f"Data record of type {record_type} cannot be wrapped by the record model wrapper "
+                                     f"of type {model_type}")