BDMS-139: Create Parameter table

api/search.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 # ===============================================================================
 from fastapi import APIRouter
-from sqlalchemy import select
+from sqlalchemy import select, func, text
 from sqlalchemy.orm import Session
 from api.pagination import CustomPage
 from fastapi_pagination import paginate
@@ -39,14 +39,14 @@
 
 def _get_contact_results(session: Session, q: str, limit: int) -> list[dict]:
     vector = (
-        Contact.search_vector
-        | Email.search_vector
-        | Phone.search_vector
-        | Address.search_vector
+        func.coalesce(Contact.search_vector, text("''::tsvector"))
+        .op("||")(func.coalesce(Email.search_vector, text("''::tsvector")))
+        .op("||")(func.coalesce(Phone.search_vector, text("''::tsvector")))
+        .op("||")(func.coalesce(Address.search_vector, text("''::tsvector")))
     )
 
     query = search(
-        select(Contact).join(Email).join(Phone).join(Address),
+        select(Contact).outerjoin(Email).outerjoin(Phone).outerjoin(Address),
         q,
         vector=vector,
         limit=limit,
@@ -66,7 +66,6 @@ def _get_contact_results(session: Session, q: str, limit: int) -> list[dict]:
         }
         for c in contacts
     ]
-
     return results
 
 

core/app.py

@@ -24,7 +24,7 @@
 )
 from fastapi.openapi.utils import get_openapi
 
-from .initializers import init_db, init_lexicon
+from .initializers import init_db, init_lexicon, init_parameter
 from .settings import settings
 
 
@@ -36,6 +36,7 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
     if settings.get_enum("MODE") == "development":
         init_db()
         init_lexicon()
+        init_parameter()
     yield
 
 

core/initializers.py

@@ -20,6 +20,7 @@
 
 from db import Base
 from db.engine import engine, session_ctx
+from db.parameter import Parameter
 from services.lexicon_helper import add_lexicon_term, add_lexicon_category
 
 
@@ -50,6 +51,36 @@ def init_hypertables():
     # session.close()
 
 
+def init_parameter(path: str = None) -> None:
+    """
+    Populate the parameter table to allow their use in creating and editing
+    observations
+    """
+    if path is None:
+        path = Path(__file__).parent / "parameter.json"
+
+    with open(path) as f:
+        import json
+
+        default_parameter = json.load(f)
+
+    with session_ctx() as session:
+        for param in default_parameter:
+            try:
+                parameter_obj = Parameter(
+                    parameter_name=param["parameter_name"],
+                    matrix=param["matrix"],
+                    parameter_type=param["parameter_type"],
+                    cas_number=param["cas_number"],
+                    default_unit=param["default_unit"],
+                )
+                session.add(parameter_obj)
+                session.commit()
+            except DatabaseError as e:
+                print(f"Failed to add parameter {param['parameter_name']}: error: {e}")
+                session.rollback()
+
+
 def init_lexicon(path: str = None) -> None:
     if path is None:
         path = Path(__file__).parent / "lexicon.json"

core/parameter.json

@@ -0,0 +1,16 @@
+[
+    {
+        "parameter_name": "groundwater level",
+        "matrix": "groundwater",
+        "parameter_type": "Field Parameter",
+        "cas_number": null,
+        "default_unit": "ft"
+    },
+    {
+        "parameter_name": "pH",
+        "matrix": "groundwater",
+        "parameter_type": "Field Parameter",
+        "cas_number": null,
+        "default_unit": "dimensionless"
+    }
+]

db/__init__.py

@@ -31,8 +31,10 @@
 from db.lexicon import *
 from db.location import *
 from db.observation import *
+from db.parameter import *
 from db.permission import *
 from db.publication import *
+from db.regulatory_limit import *
 from db.sample import *
 from db.sensor import *
 from db.status_history import *

db/lexicon.py

@@ -14,7 +14,7 @@
 # limitations under the License.
 # ===============================================================================
 from sqlalchemy import String, ForeignKey, Integer
-from sqlalchemy.orm import mapped_column, relationship
+from sqlalchemy.orm import mapped_column, relationship, Mapped
 from sqlalchemy.ext.associationproxy import association_proxy, AssociationProxy
 
 from db.base import AutoBaseMixin, Base, lexicon_term
@@ -27,8 +27,8 @@ class LexiconTerm(Base, AutoBaseMixin):
     """
 
     __tablename__ = "lexicon_term"
-    term = mapped_column(String(100), unique=True, nullable=False)
-    definition = mapped_column(String(255), nullable=False)
+    term: Mapped[str] = mapped_column(unique=True, nullable=False)
+    definition: Mapped[str] = mapped_column(nullable=False)
 
     category_associations = relationship(
         "LexiconTermCategoryAssociation",

db/observation.py

@@ -29,6 +29,7 @@
     from db.sample import Sample
     from db.sensor import Sensor
     from db.analysis_method import AnalysisMethod
+    from db.parameter import Parameter
 
 
 class Observation(Base, AutoBaseMixin, ReleaseMixin):
@@ -50,11 +51,14 @@ class Observation(Base, AutoBaseMixin, ReleaseMixin):
         Integer, ForeignKey("analysis_method.id"), nullable=True
     )
 
+    parameter_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("parameter.id"), nullable=False
+    )
+
     # --- Columns ---
     observation_datetime: Mapped[datetime] = mapped_column(
         DateTime(timezone=True), nullable=False, doc="Timestamp of the observation"
     )
-    observed_property: Mapped[str] = lexicon_term(nullable=False)
     value: Mapped[float] = mapped_column(
         nullable=True,
     )
@@ -88,5 +92,10 @@ class Observation(Base, AutoBaseMixin, ReleaseMixin):
         "AnalysisMethod", back_populates="observations"
     )
 
+    # Many-To-One: An Observation measures one Parameter.
+    parameter: Mapped["Parameter"] = relationship(
+        "Parameter", back_populates="observations", lazy="joined"
+    )
+
 
 # ============= EOF =============================================

db/parameter.py

@@ -0,0 +1,67 @@
+"""
+This table is a controlled vocabulary for all analytes, properties, and
+characteristics that can be measured or observed.
+"""
+
+from typing import List, TYPE_CHECKING
+
+from sqlalchemy.orm import relationship, Mapped, mapped_column
+
+from db.base import Base, AutoBaseMixin, ReleaseMixin, lexicon_term
+
+if TYPE_CHECKING:
+    from db.observation import Observation
+    from db.regulatory_limit import RegulatoryLimit
+
+
+class Parameter(Base, AutoBaseMixin, ReleaseMixin):
+    """
+
+    Represents an analyte or property that can be measured (e.g., Chloride).
+    """
+
+    __versioned__ = {}
+
+    # --- Columns ---
+    # TODO: Parameter names are currently associated with the 'observed_property' category in the lexicon. Should we update the lexicon category name to 'parameter_name'?
+    parameter_name: Mapped[str] = lexicon_term(
+        nullable=False,
+        comment="The official, full name of the parameter (e.g., 'Arsenic, Dissolved').",
+    )
+    matrix: Mapped[str] = lexicon_term(
+        nullable=False,
+        comment="A controlled vocabulary field defining the physical medium the analyte is measured in (e.g., 'Water', 'Soil', 'Air').",
+    )
+    parameter_type: Mapped[str] = lexicon_term(
+        nullable=True,
+        comment="A controlled vocabulary field defining the category of the parameter (e.g., 'Metals', 'Nutrients', 'Field Parameter'). Used for grouping and filtering.",
+    )
+    cas_number: Mapped[str] = mapped_column(
+        nullable=True,
+        comment="The Chemical Abstracts Service (CAS) registry number, a globally unique identifier for a chemical substance.",
+    )
+    default_unit: Mapped[str] = lexicon_term(
+        nullable=False,
+        comment="The standard, preferred unit for reporting this parameter (e.g., 'ug/L', 'mg/L', 'pH units').",
+    )
+
+    # --- Relationships ---
+    # One-To-Many: A Parameter can have many Observations.
+    observations: Mapped[List["Observation"]] = relationship(
+        "Observation", back_populates="parameter"
+    )
+
+    # One-To-Many: A Parameter can have many associated RegulatoryLimits.
+    # If a Parameter is deleted, all its associated limits are deleted as well.
+    regulatory_limits: Mapped[List["RegulatoryLimit"]] = relationship(
+        "RegulatoryLimit", back_populates="parameter", cascade="all, delete-orphan"
+    )
+
+    # --- Table Arguments ---
+    # An analyte is defined by its name and matrix. This constraint
+    # ensures a single, specific analyte can only be defined once.
+    from sqlalchemy import UniqueConstraint
+
+    __table_args__ = (
+        UniqueConstraint("parameter_name", "matrix", name="uq_parameter_name_matrix"),
+    )

db/regulatory_limit.py

@@ -0,0 +1,50 @@
+"""
+This table stores the various regulatory or health-based limits for a given
+parameter, sourced from different agencies or standards.
+
+The purpose of this table  is to solve the real-world problem where a single
+chemical (`Parameter`) can have multiple different limits set by various agencies
+(e.g., a federal EPA limit and a state-level NMED limit).
+"""
+
+from typing import TYPE_CHECKING
+
+from sqlalchemy import Integer, Numeric, ForeignKey
+from sqlalchemy.orm import relationship, Mapped, mapped_column
+
+from db.base import Base, AutoBaseMixin, ReleaseMixin, lexicon_term
+
+if TYPE_CHECKING:
+    from db.parameter import Parameter
+
+
+class RegulatoryLimit(Base, AutoBaseMixin, ReleaseMixin):
+    """
+    Represents a single, citable regulatory or health-based limit for a
+    specific Parameter.
+    """
+
+    __versioned__ = {}
+
+    # --- Foreign Keys ---
+    parameter_id: Mapped[int] = mapped_column(
+        Integer, ForeignKey("parameter.id"), nullable=False
+    )
+
+    # --- Columns ---
+    limit_source: Mapped[str] = lexicon_term(
+        nullable=False,
+        comment="The official source of the limit (e.g., 'EPA', 'NMED', 'EPA').",
+    )
+    limit_value: Mapped[float] = mapped_column(Numeric, nullable=False)
+    limit_unit: Mapped[str] = lexicon_term(nullable=False)
+    limit_type: Mapped[str] = lexicon_term(
+        nullable=True,
+        comment="A controlled vocabulary field to categorize the limit (e.g., 'MCL', 'PQL', 'MDL', etc.).",
+    )
+
+    # --- Relationships ---
+    # Many-To-One: A RegulatoryLimit is for one Parameter.
+    parameter: Mapped["Parameter"] = relationship(
+        "Parameter", back_populates="regulatory_limits"
+    )

schemas/observation.py

@@ -25,6 +25,7 @@
 from typing_extensions import Self
 
 from schemas import BaseCreateModel, BaseUpdateModel, BaseResponseModel
+from schemas.parameter import ParameterResponse
 
 
 # class GeothermalMixin:
@@ -36,7 +37,7 @@
 
 
 class ValidateObservation(BaseModel):
-    observed_property: str
+    parameter_id: int
     observation_datetime: AwareDatetime
 
     @field_validator("observation_datetime", check_fields=False)
@@ -60,7 +61,7 @@ class CreateBaseObservation(BaseCreateModel, ValidateObservation):
     observation_datetime: Annotated[AwareDatetime, PastDatetime()]
     sample_id: int
     sensor_id: int
-    observed_property: str
+    parameter_id: int
     release_status: str
     value: float | None
     unit: str | None
@@ -82,7 +83,7 @@ class UpdateBaseObservation(BaseUpdateModel, ValidateObservation):
     observation_datetime: Annotated[AwareDatetime, PastDatetime()] | None = None
     sample_id: int | None = None
     sensor_id: int | None = None
-    observed_property: str | None = None
+    parameter_id: int | None = None
     release_status: str | None = None
     value: float | None | None = None
     unit: str | None = None
@@ -98,11 +99,12 @@ class UpdateWaterChemistryObservation(UpdateBaseObservation):
 
 
 # -------- RESPONSE ----------
+# TODO: Return full sample and sensor objects
 class BaseObservationResponse(BaseResponseModel):
     sample_id: int
     sensor_id: int
     observation_datetime: AwareDatetime
-    observed_property: str
+    parameter: ParameterResponse
     release_status: str
     value: float | None
     unit: str

schemas/parameter.py

@@ -0,0 +1,15 @@
+from schemas import BaseResponseModel
+
+
+# -------- RESPONSE -------
+class ParameterResponse(BaseResponseModel):
+    """
+    Pydantic model for the response of a parameter.
+    This model can be extended to include additional fields as needed.
+    """
+
+    parameter_name: str
+    matrix: str
+    parameter_type: str | None
+    cas_number: str | None
+    default_unit: str