Appearance
Entity: building
Entity Type: Database table
Description: A node in the location hierarchy representing any physical or organisational location whose energy consumption is tracked. Buildings form a self-referential tree of unlimited depth via parentId. Every gauge belongs to exactly one building node. The levelType attribute is a UI hint describing the role of the node (portfolio, campus, floor, etc.) but is not enforced as a structural constraint. Degree-day normalisation for this building is computed on demand from climate data (see climate data / degree-day normalisation) — it is not stored against the building itself. buildingParameter.temperatureReference supplies the building's reference temperature used as an input to that calculation.
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 | a1b2c3d4-… |
| tenantId | Tenant that owns this building. All queries are scoped to a tenant. | UUID | - | Yes | No | UUID v7 | Foreign Key → tenant; must exist | name: idx_building_tenantId, type: btree | e5f6a7b8-… |
| parentId | Reference to the parent building node. Null marks a root node (top of the hierarchy for this tenant). | UUID | null | No | No | UUID v7 | Foreign Key → building (self-referential); must not create a cycle | name: idx_building_parentId, type: btree | c9d0e1f2-… |
| levelType | UI hint describing what organisational level this node represents. Not enforced as a structural constraint. | Enum | null | No | No | enum | - | - | campus |
| name | Display name of the building node. | String | - | Yes | No | - | Max 255 characters | - | School Campus Brno |
| type | Object type controlling which form sections and fields are displayed. | Enum | - | Yes | No | enum | Immutable after creation without special role | - | building |
| sectorId | Sector classification from the tenant-defined codebook. | UUID | - | Yes | No | UUID v7 | Foreign Key → sector; must exist; immutable after creation without special role | - | d3e4f5a6-… |
| street | Street name of the building address. | String | null | No | No | - | Required when type = building; max 255 characters | - | Náměstí Svobody |
| houseNumber | House / descriptive number of the building (číslo popisné). | String | null | No | No | - | Required when type = building; max 20 characters | - | 12 |
| referenceNumber | Orientation number of the building (číslo orientační). Optional complement to houseNumber. Migrated from legacy reference_number column. | String | null | No | No | - | Max 20 characters | - | 4a |
| city | City of the building address. | String | null | No | No | - | Required when type = building; max 255 characters. Auto-populated from ZIP (when zip available); can be overridden manually. | - | Brno |
| zip | Postal code of the building address. | String | null | No | No | - | Required when type = building; exactly 5 digits | - | 60200 |
| address | Legacy raw address string, kept alongside the decomposed street/houseNumber/city/zip fields above as a separate, intentionally-retained legacy field. | String | null | No | No | - | - | - | Náměstí Svobody 8, 602 00 Brno |
| ownerId | Reference to the organisation acting as the building's owner. | UUID | null | No | No | UUID v7 | Foreign Key → organisation; must exist if set | - | 018fa51f-fda1-79f4-8461-2cb8f1cabc10 |
| managerId | Reference to the organisation acting as the building's manager. | UUID | null | No | No | UUID v7 | Foreign Key → organisation; must exist if set | - | 018fa51f-fda1-79f4-8461-2cb8f1cabc10 |
| delegatedManagerId | Reference to the organisation acting as the delegated manager (přenesená správa). | UUID | null | No | No | UUID v7 | Foreign Key → organisation; must exist if set | - | 018fa51f-fda1-79f4-8461-2cb8f1cabc10 |
| ownerIco | Czech company tax ID (IČO) of the building owner. Read-only snapshot of the linked organisation once ownerId is set; null for natural persons without IČO. | String | null | No | No | - | Exactly 8 digits; stored as zero-padded string; leading zeros preserved. Null when owner is a natural person. | - | 00064581 |
| ownerName | Name of the building owner. Read-only snapshot of the linked organisation once ownerId is set. | String | null | No | No | - | Max 255 characters | - | Statutární město Brno |
| managerIco | Czech company tax ID (IČO) of the building manager. Read-only snapshot of the linked organisation once managerId is set; null for natural persons without IČO. | String | null | No | No | - | Exactly 8 digits; stored as zero-padded string; leading zeros preserved. Null when manager is a natural person. | - | 44994575 |
| managerName | Name of the building manager. Read-only snapshot of the linked organisation once managerId is set. | String | null | No | No | - | Max 255 characters | - | Správa nemovitostí Brno s.r.o. |
| delegatedManagerIco | Czech company tax ID (IČO) of the delegated manager (přenesená správa). Read-only snapshot of the linked organisation once delegatedManagerId is set; null for natural persons without IČO. | String | null | No | No | - | Exactly 8 digits; stored as zero-padded string; leading zeros preserved. Null when delegated manager is a natural person. | - | 00064582 |
| delegatedManager | Name of the delegated manager (přenesená správa). Read-only snapshot of the linked organisation once delegatedManagerId is set. | String | null | No | No | - | Max 255 characters | - | Technická správa komunikací hl. m. Prahy |
| gid | Global identifier used in Prague-region asset management systems. Specific to Prague-region clients. Migrated from legacy gid column. | String | null | No | No | - | Max 255 characters | - | MHMP-12345 |
| uceh | Unique energy management identifier (UČEH). Client-specific code used in some energy management systems. Migrated from legacy uceh column on building_properties. | String | null | No | No | - | Max 255 characters | - | UCEH-2024-00123 |
| legacyId | Legacy-system identifier; migration provenance. | String | null | No | No | - | - | UNIQUE (tenantId, legacySource, legacyId) WHERE legacyId IS NOT NULL | 4821 |
| legacySource | Which legacy table this building was migrated from. | String (enum) | null | No | No | enum: ground, building | Must be one of the listed values, or null | (composite with legacyId above) | building |
| isPartOfEnms | Indicates whether the building is part of the client's energy management system scope. Migrated from legacy client_energy_management on building_properties. | Boolean | true | Yes | No | - | - | - | true |
| isOperationPartOfEnms | Indicates whether the operation of this building is part of the client's energy management system scope. Migrated from legacy client_working_energy_management on building_properties. | Boolean | true | Yes | No | - | - | - | true |
| lat | Geocoded GPS latitude of the building, derived automatically from the address. Used as fallback when latCustom is not set. Must be provided together with lng. Migrated from legacy map_lat. | Decimal | null | No | No | decimal(9,6) | Range -90 to 90; must be null if lng is null and vice versa | - | 49.195060 |
| lng | Geocoded GPS longitude of the building, derived automatically from the address. Used as fallback when lngCustom is not set. Must be provided together with lat. Migrated from legacy map_lng. | Decimal | null | No | No | decimal(9,6) | Range -180 to 180; must be null if lat is null and vice versa | - | 16.608660 |
| latCustom | User-defined GPS latitude override. When set, takes precedence over lat for map display and Mapy.com link generation. Must be provided together with lngCustom. Migrated from legacy map_lat_custom. | Decimal | null | No | No | decimal(9,6) | Range -90 to 90; must be null if lngCustom is null and vice versa | - | 49.195120 |
| lngCustom | User-defined GPS longitude override. When set, takes precedence over lng for map display and Mapy.com link generation. Must be provided together with latCustom. Migrated from legacy map_lng_custom. | Decimal | null | No | No | decimal(9,6) | Range -180 to 180; must be null if latCustom is null and vice versa | - | 16.608790 |
mapyComUrl (computed, not persisted) | Read-only URL to the building's location on Mapy.com. Generated on-the-fly from effective coordinates: latCustom/lngCustom if set, otherwise lat/lng. Not stored in the database. Null when no coordinates are available. | String | - | - | - | URL | Read-only; not writable via API. Not persisted. | Not indexed (not persisted) | https://mapy.com/cs?x=16.6088&y=49.1951&z=17 |
| showOnMap | Controls whether the building is displayed on the map view. | Boolean | true | Yes | No | - | - | - | true |
| yearBuilt | Year the building was constructed. Migrated from legacy built_year column. | Integer | null | No | No | smallint | Range 1800–current year | - | 1978 |
| description | Free-text description of the building. During migration, the legacy organization field (from building_properties) is appended here as "[Legacy organization: {value}]" for records where the value is not already present in ownerName or managerName. | String | null | No | No | - | - | - | Main administrative building of the campus. |
| photoFileId | Reference to the file entity containing the building photo. | UUID | null | No | No | UUID v7 | Foreign Key → file; JPEG or PNG; max 20 MB | - | f1e2d3c4-… |
| isHeritage | Indicates whether the building is a listed heritage site. Migrated from legacy protected column on building_properties. | Boolean | false | Yes | No | - | - | - | false |
| climateStationId | Reference to the WeatherStation linked to this building for degree-day normalisation. | UUID | null | No | No | UUID v7 | Foreign Key → weatherStation; must exist if set | - | b3c4d5e6-… |
| isArchived | Soft-delete flag. Archived buildings are excluded from active lists but retained for historical data. Derived during migration from legacy disabled_at IS NOT NULL. | Boolean | false | Yes | No | - | - | name: idx_building_tenantId_isArchived, type: btree (composite with tenantId) | false |
| archivedAt | Timestamp of when the building was archived. Migrated from legacy disabled_at column. | Timestamp | null | No | No | YYYY-MM-DDTHH:mm:ss.SSS+00 | Must be set when isArchived = true | - | 2025-01-15T10:00:00.000+00 |
| archiveReason | Reason for archiving the building. Migrated from legacy disabled_reason INT enum (1→saleDemolition, 2→transfer, 3→outOfScope, 8→other). | Enum | null | No | No | enum | Required when isArchived = true | - | transfer |
| showArchivedInReports | Controls whether historical data from this archived building appears in reports and charts. | Boolean | false | Yes | No | - | - | - | false |
| createdAt | Timestamp of when the record was created. | Timestamp | now() | Yes | No | YYYY-MM-DDTHH:mm:ss.SSS+00 | - | - | 2024-03-01T08:00:00.000+00 |
| updatedAt | Timestamp of the last update to the record. | Timestamp | now() | Yes | No | YYYY-MM-DDTHH:mm:ss.SSS+00 | - | - | 2024-06-15T14:22:00.000+00 |
| deletedAt | Timestamp of soft-deletion. Once set (non-null), this value is immutable and cannot be changed. Records where deletedAt IS NULL are considered active; all default queries must filter by this condition. Permanent deletion is an admin-only operation; for user-initiated end-of-life use isArchived instead. | Timestamp | null | No | No | YYYY-MM-DDTHH:mm:ss.SSS+00 | Once set, immutable — cannot be changed or unset | - | 2025-06-01T12:00:00.000+00 |
| createdBy | Identifier of the actor who created the record (user ID or system). | String | - | Yes | No | type:actor | Non-empty | - | user:a1b2c3d4 / system |
| updatedBy | Identifier of the actor who last updated the record (user ID or system). | String | - | Yes | No | type:actor | Non-empty | - | user:a1b2c3d4 / system |
Note: mapyComUrl is a computed, non-persisted read-only field kept in the DAT for documentation completeness (per source); it does not participate in the persisted attribute ordering (§3.2) since it has no storage.
Audited fields
Recorded on created (in full), updated (changed only) and deleted (in full): parentId, levelType, name, type, sectorId, street, houseNumber, referenceNumber, city, zip, address, ownerId, managerId, delegatedManagerId, ownerIco, ownerName, managerIco, managerName, delegatedManagerIco, delegatedManager, gid, uceh, isPartOfEnms, isOperationPartOfEnms, lat, lng, latCustom, lngCustom, showOnMap, yearBuilt, description, photoFileId, isHeritage, climateStationId, isArchived, archivedAt, archiveReason, showArchivedInReports, legacyId, legacySource.
Excluded:
mapyComUrl— computed at read time fromlat/lng(orlatCustom/lngCustomwhen set); not a persisted column, so it never appears inchangedFields.
Every other entity in this batch (buildingCalculatedConsumption, buildingEnergyBaseline, buildingEnergyProfile, buildingParameter, buildingSchedule) files its entries against this entity as subject, so a building's full history is one indexed read.
Registered for entityName resolution — resolves to name (architecture 61-audit-log.md §7.4 in the code repo).