Entity: calorificValue

Entity Type: Database table

Description: A calorific value stated inside a tenant, at one of two scopes: for a whole client, or for a single gauge. gaugeId is what distinguishes them — set means the value applies to that gauge alone, null means it applies to every gauge of the client with the same medium and primary source that has no value of its own.

The columns are identical to the platform-wide defaultCalorificValue, so a resolver walking gauge → client → platform compares the same fields at every step and applies the same validity rule. The two tables are separate only because platform defaults must live in the cross-tenant schema and a per-gauge value must not.

Every scope is dated. A value carries validFrom and runs until the next value at the same scope begins. This is what makes a historical consumption figure reproducible: energy computed for last January uses the value that was valid last January, and correcting that value recomputes that period rather than silently repricing it.

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key of the entity.	UUID	Generated in code (app layer)	Yes	Yes	UUID v7	-	Primary Key	018f9c4d-2c11-7a3e-9b77-4f0d3a5e6b51
tenantId	Tenant this record belongs to.	UUID	-	Yes	No	UUID v7	Foreign Key → tenant; must exist	name: idx_calorific_value_tenantId, type: btree	018fa51f-fda1-79f4-8461-2cb8f1cabc10
clientId	Client the value belongs to. Set on both scopes: a gauge-scoped value still belongs to the client that owns the gauge, so one client's values can be listed without joining.	UUID	-	Yes	Part of composite unique	UUID v7	Foreign Key → client; must exist	Part of the unique index below	018fa51f-fda1-79f4-8461-2cb8f1cabc10
gaugeId	The gauge this value applies to, or null for a value that applies to the whole client. The column is the scope discriminator.	UUID	null	No	Part of composite unique	UUID v7	Foreign Key → gauge; must exist if set. Its medium and primarySource must match the two columns below.	name: idx_calorific_value_gauge_id, type: btree	018f6e2a-…
medium	Medium the value applies to.	Enum	-	Yes	Part of composite unique	Enum - GaugeMedium	An entry from the enum.	Part of the unique index below	gas
primarySource	Fuel or source within the medium.	Integer	-	Yes	Part of composite unique	Enum - PrimarySource	An entry from the enum.	Part of the unique index below	1
value	The conversion factor: how much energy one unit of unitFrom yields, expressed in unitTo.	Decimal	-	Yes	No	numeric(12,6)	Must be > 0.	-	9.500000
unitFrom	Unit the factor converts from.	Enum	-	Yes	No	Enum - Unit	Must be a volume or mass unit.	-	m³
unitTo	Unit the factor converts to.	Enum	-	Yes	No	Enum - Unit	Must be an energy unit.	-	kWh
validFrom	First day the value applies at this scope. No explicit end: it runs until the next value at the same scope begins.	Date	-	Yes	Part of composite unique	YYYY-MM-DD	Unique per (clientId, gaugeId, medium, primarySource, validFrom) among rows where deletedAt is null.	Part of the unique index below	2026-01-01
note	Where the value comes from — typically the supplier's certificate or declaration, with its reference.	String	null	No	No	-	Max 500 characters.	-	Certifikát dodavatele 2026-Q1
createdAt	Timestamp of record creation.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null.	-	2026-01-05T08:00:00Z
updatedAt	Timestamp of the last update.	Timestamp with time zone	now() — set in code	Yes	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Cannot be null.	-	2026-01-05T08:00:00Z
deletedAt	Soft-delete marker. Null means active. A superseded value is never deleted — it reproduces the consumption of the period it covered.	Timestamp with time zone	null	No	No	ISO 8601 — YYYY-MM-DDTHH:mm:ss.SSSZ	Immutable once set. Active rows: WHERE deletedAt IS NULL.	-	null
createdBy	Actor who created the record.	String	-	Yes	No	type:actor	Non-empty.	-	user:018ed0b3-…
updatedBy	Actor who last updated the record.	String	-	Yes	No	type:actor	Non-empty.	-	user:018ed0b3-…

Indexes

Name	Columns	Type	Why
uq_calorific_value_scope	clientId, gaugeId, medium, primarySource, validFrom where deletedAt is null — nulls not distinct	Unique, partial	One value per scope and start date, with gaugeId null treated as its own scope rather than as "any".
idx_calorific_value_gauge_id	gaugeId	btree	The gauge-scope lookup, which is the first step of every resolution.
idx_calorific_value_tenantId	tenantId	btree	Tenant predicate.

Row-level security

Enabled and forced, with the tenant-isolation policy every tenant-schema table carries.

Audited fields

Recorded on created (in full), updated (changed only) and deleted (in full): clientId, gaugeId, medium, primarySource, value, unitFrom, unitTo, validFrom, note.

Excluded: none — every column of a calorific value changes the energy figures derived from it.

Not registered for entityName resolution, and has no independent human-readable attribute to register — identified by its clientId/gaugeId/medium/primarySource/validFrom scope.