cgm-remote-monitor/docs/data-schemas/entries-schema.md

Entries Schema Documentation

Document Version: 1.0
Last Updated: March 2026
Status: Active (2025 Standard)
Source: Code analysis (lib/server/entries.js)

---

Overview

The entries collection stores CGM (Continuous Glucose Monitor) sensor readings and related data. This includes SGV (sensor glucose values), MBG (meter blood glucose), and calibration data.

Collection Name: entries
Primary Key: sysTime + type (composite)
Primary Timestamp Field: sysTime (ISO 8601, derived from dateString or date)

---

Core Fields

Field	Type	Required	Constraints	Description
_id	ObjectId	Yes (auto)	MongoDB ObjectId	Primary key, auto-generated by server
type	String	Yes	sgv, mbg, cal, etc.	Type of entry
date	Number	Yes	Epoch milliseconds	When the reading was taken
dateString	String	Yes	ISO 8601	Same as date in string format
sysTime	String	Computed	ISO 8601	Normalized timestamp (computed from dateString or date)
utcOffset	Number	Computed	Minutes	UTC offset parsed from dateString

---

SGV Fields (type: "sgv")

Field	Type	Constraints	Description
sgv	Number	mg/dL or mmol/L	Sensor glucose value
direction	String	Trend arrows	Glucose trend direction
noise	Number	0-4	Signal noise level
filtered	Number	Raw value	Filtered sensor signal
unfiltered	Number	Raw value	Unfiltered sensor signal
rssi	Number	dBm	Signal strength (Dexcom)

---

Sync Identity Fields

Field	Type	Source	Description
identifier	String	Server-normalized	Unified client sync identity (see below)
device	String	CGM app	Device/app identifier (e.g., "xDrip-DexcomG6")

Identifier Field Normalization (REQ-SYNC-072)

As of v15.0.7, the server normalizes UUID values in _id into the identifier field when UUID_HANDLING=true (default):

Client	Sends	Server Action (UUID_HANDLING=true)	Server Action (UUID_HANDLING=false)
Trio	UUID in _id	Move to identifier, assign server ObjectId	Strip _id, assign ObjectId (UUID not preserved)
Loop (entries)	ObjectId (from cache)	Normal ObjectId behavior	Normal ObjectId behavior

Note: The UUID_HANDLING env var controls both write-path normalization (identifier extraction) and read-path queries (GET/DELETE by UUID).

Important: For entries, sysTime + type is ALWAYS the primary deduplication key. The identifier field is for client sync tracking only - it does NOT override the dedup logic.

---

Deduplication Behavior

Entries use sysTime + type as the composite unique key:

// Upsert query for entries (lib/server/entries.js)
{ sysTime: doc.sysTime, type: doc.type }

This means:

• Two SGV readings at the same sysTime will be deduplicated (one overwrites the other)
• Different entry types (SGV vs MBG) at the same time are allowed
• Re-uploading the same reading updates the existing document

UUID _id Handling

When a client sends a UUID as _id:

1. Extract: UUID is copied to identifier field (when UUID_HANDLING=true)
2. Strip: Non-ObjectId _id is removed before database operation
3. Upsert: Server uses sysTime + type for matching
4. Assign: Server-generated ObjectId becomes final _id

This prevents the MongoDB "immutable field '_id'" error while preserving client sync identity (when enabled).

---

UUID_HANDLING Feature Flag

The UUID_HANDLING environment variable controls both write-path normalization (identifier extraction) and read-path queries (GET/DELETE by UUID).

When UUID_HANDLING=true (default):

Operation	Behavior
POST/PUT with UUID _id	UUID moved to identifier, server assigns ObjectId
GET by UUID	Searches by identifier field
DELETE by UUID	Deletes by identifier field

When UUID_HANDLING=false:

Operation	Behavior
POST/PUT with UUID _id	UUID _id stripped, ObjectId assigned (UUID not preserved)
GET by UUID	Returns empty (no crash)
DELETE by UUID	Deletes nothing (no crash)

Note: This only affects cases where a UUID is passed as the _id field (writes) or as the _id parameter in API calls (reads), e.g., GET /api/v1/entries/{uuid}.

---

Example Entry Document

{
  "_id": "507f1f77bcf86cd799439011",
  "type": "sgv",
  "sgv": 120,
  "direction": "Flat",
  "date": 1704067200000,
  "dateString": "2024-01-01T00:00:00.000Z",
  "sysTime": "2024-01-01T00:00:00.000Z",
  "utcOffset": 0,
  "identifier": "550e8400-e29b-41d4-a716-446655440000",
  "device": "xDrip-DexcomG6",
  "noise": 1
}

---

Related Documents

• Treatments Schema - Similar identifier normalization
• GAP-SYNC-045 - Trio entries UUID issue
• REQ-SYNC-072 - Identifier normalization requirement