From f99ccea36ee1a2b39b5ffae367270ec0ce5e9570 Mon Sep 17 00:00:00 2001 From: Kelsey Smuczynski Date: Thu, 27 Aug 2026 12:59:48 -0600 Subject: [PATCH] docs(ogc): record the null measuring-point height default water_well_summary, depth_to_water_trend_wells and water_elevation_wells layers all substitute zero for a missing measuring-point height, treating the measuring point as ground surface. That has been in the SQL since those views were written (COALESCE(measuring_point_height, 0)), but nothing said whether zero was the intended default or an accident. BDMS-974 surfaced the question and deferred it here rather than change the views on a guess. Cris Morton and Ethan Mamer confirmed on 2026-08-26 that zero (ground surface) is the right default, so the views are correct as written and there is no code change to make. What was missing was the record: the next person to read that substitution would ask the same question, and without an answer on file the safe-looking move is to exclude those rows, which would silently drop wells from three published layers. The doc keeps the consequence visible rather than acting on it. Wells with no recorded measuring point are less certain than the rest and nothing in the output says so. Adding a flag column would touch three view definitions and the field descriptions for a subset nobody has sized yet, so the decision records the condition for revisiting it instead. Refs BDMS-980 --- docs/measuring-point-height-null-handling.md | 26 ++++++++++++++++++++ 1 file changed, 26 insertions(+) create mode 100644 docs/measuring-point-height-null-handling.md diff --git a/docs/measuring-point-height-null-handling.md b/docs/measuring-point-height-null-handling.md new file mode 100644 index 00000000..0611e580 --- /dev/null +++ b/docs/measuring-point-height-null-handling.md @@ -0,0 +1,26 @@ +# Measuring-point height: null handling + +**Status:** Accepted +**Date:** 2026-08-26 +**Decided by:** Cris Morton + Ethan Mamer +**Recorded by:** Kelsey Smuczynski + +## Context + +Three OGC layers compute depth-to-water and water-elevation values from measuring-point height: + +- `water_well_summary` +- `depth_to_water_trend_wells` +- `water_elevation_wells` + +Each uses `COALESCE(measuring_point_height, 0)` in the calculation. When `measuring_point_height` is null, this treats the measuring point as ground surface level (0), rather than excluding the record or flagging it for review. + +## Decision + +A missing or null measuring-point height defaults to zero (ground surface level) in these calculations. Cris Morton confirmed this is the correct default on 2026-08-26. + +## Consequences + +- Depth-to-water and water-elevation values for wells with no recorded measuring-point height are calculated as if the measurement were taken at ground surface. These values carry more uncertainty than wells with a known measuring point, but nothing in the output currently distinguishes them. +- If a future review determines this default introduces meaningful error for a subset of wells (for example, wells with a well casing or stickup that's unusually tall), revisit this decision and consider flagging affected records instead of silently defaulting to zero. +- Any new analytic layer that calculates depth-to-water or water-elevation from measuring-point height should follow this same convention, or explicitly document why it doesn't.