fix: omit None fields from click inserts to stop bucket churn

repositories/indexes.py

@@ -122,7 +122,9 @@ async def ensure_indexes(
             timeseries={
                 "timeField": "clicked_at",
                 "metaField": "meta",
-                "granularity": "seconds",
+                # "hours" matches prod (collMod'd from "seconds"): sparse
+                # per-link series need the 30-day bucket span to pack.
+                "granularity": "hours",
             },
         )
     except (CollectionInvalid, OperationFailure) as e:

schemas/models/click.py

@@ -6,7 +6,7 @@
 Time-series schema:
   timeField  = "clicked_at"
   metaField  = "meta"
-  granularity = "seconds"
+  granularity = "hours"
 
 The `meta` subdocument groups clicks by URL for efficient range queries.
 owner_id always holds an ObjectId — anonymous clicks use ANONYMOUS_OWNER_ID
@@ -60,3 +60,8 @@ class ClickDoc(MongoBaseModel):
     utm_source: str | None = None
     utm_medium: str | None = None
     utm_campaign: str | None = None
+
+    def to_mongo(self) -> dict:
+        # None must be absent, not null: null↔string type flips hard-close
+        # time-series buckets (schema-change rollover).
+        return self.model_dump(by_alias=True, exclude_none=True)

tests/unit/repositories/test_indexes.py

@@ -185,7 +185,7 @@ async def test_ensure_indexes_creates_timeseries_collection(self):
             timeseries={
                 "timeField": "clicked_at",
                 "metaField": "meta",
-                "granularity": "seconds",
+                "granularity": "hours",
             },
         )
 

tests/unit/schemas/models/test_click.py

@@ -50,3 +50,25 @@ def test_to_mongo_round_trip(self):
         restored = ClickDoc.from_mongo(doc.to_mongo())
         assert restored.referrer == "google.com"
         assert restored.redirect_ms == doc.redirect_ms
+
+    def test_to_mongo_omits_none_fields(self):
+        data = self._make().to_mongo()
+        for field in (
+            "referrer",
+            "bot_name",
+            "device",
+            "utm_source",
+            "utm_medium",
+            "utm_campaign",
+        ):
+            assert field not in data
+        assert "domain" not in data["meta"]
+
+    def test_to_mongo_keeps_populated_fields(self):
+        data = self._make(
+            referrer="google.com", device="mobile", utm_source="tw"
+        ).to_mongo()
+        assert data["referrer"] == "google.com"
+        assert data["device"] == "mobile"
+        assert data["utm_source"] == "tw"
+        assert data["redirect_ms"] == 42

tests/unit/services/test_click_service.py

@@ -296,17 +296,18 @@ async def test_utm_tags_recorded_in_click_doc(self):
         assert doc["utm_campaign"] == "launch"
 
     @pytest.mark.asyncio
-    async def test_utm_tags_default_to_none(self):
+    async def test_utm_tags_omitted_when_absent(self):
+        # Absent, never null: explicit nulls hard-close time-series buckets.
         d = make_deps()
         handler = make_v2_handler(d.click_repo, d.url_repo, d.geoip, d.url_cache)
         url_data = make_v2_cache()
 
         await handler.handle(make_context(url_data))
 
         doc = d.click_repo.insert.call_args[0][0]
-        assert doc["utm_source"] is None
-        assert doc["utm_medium"] is None
-        assert doc["utm_campaign"] is None
+        assert "utm_source" not in doc
+        assert "utm_medium" not in doc
+        assert "utm_campaign" not in doc
 
     @pytest.mark.asyncio
     async def test_meta_carries_domain_from_cache(self):
@@ -320,17 +321,17 @@ async def test_meta_carries_domain_from_cache(self):
         assert doc["meta"]["domain"] == "links.acme.com"
 
     @pytest.mark.asyncio
-    async def test_meta_domain_none_when_cache_empty_string(self):
-        # Older cached entries pre-PR1 have domain="". Coerce to None so
-        # per-domain queries can distinguish "unknown" from a real value.
+    async def test_meta_domain_omitted_when_cache_empty_string(self):
+        # Older cached entries pre-PR1 have domain="". Coerced to None and
+        # omitted on insert so per-domain queries see it as unknown.
         d = make_deps()
         handler = make_v2_handler(d.click_repo, d.url_repo, d.geoip, d.url_cache)
         url_data = make_v2_cache(domain="")
 
         await handler.handle(make_context(url_data))
 
         doc = d.click_repo.insert.call_args[0][0]
-        assert doc["meta"]["domain"] is None
+        assert "domain" not in doc["meta"]
 
     @pytest.mark.asyncio
     async def test_blocked_bot_skips_analytics_no_error(self):