Schema Reference

Complete column definitions for all Parquet entities and measurements (current v1 schema)

Data Types

All Parquet files use these Apache Arrow/Parquet data types:

Type	Description
`string`	UTF-8 encoded text
`bool`	Boolean (`true` / `false`)
`int64`	64-bit signed integer
`decimal128(38, 20)`	128-bit decimal, precision 38, scale 20 (default for `numeric` columns)
`decimal256`	256-bit decimal (used when inferred precision exceeds 38)
`timestamp[us, tz=UTC]`	Microsecond-precision UTC timestamp

Entity Schemas

Organization

Organization metadata.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`name`	string	✗	Organization name
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Device

IoT device inventory and properties.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`name`	string	✗	Device name
`modelType`	string	✗	Device model (e.g., `com.haltian.device.tsar02`)
`externalId`	string	✓	External system identifier
`tuid`	string	✓	Thingsee Unique Identifier
`manufacturingDate`	timestamp	✓	Manufacturing date
`shippingDate`	timestamp	✓	Shipping date
`warrantyDate`	timestamp	✓	Warranty expiration
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp
`lastSeen`	timestamp	✓	Last communication time
`wirepasNodeId`	int64	✓	Wirepas mesh node ID
`wirepasNetworkId`	int64	✓	Wirepas mesh network ID
`imei`	string	✓	IMEI (cellular devices)
`iccid`	string	✓	SIM card ICCID
`bleMac`	string	✓	Primary Bluetooth MAC
`bleMac2`	string	✓	Secondary Bluetooth MAC
`lanMac`	string	✓	LAN MAC address
`wifiMac`	string	✓	WiFi MAC address
`customerLabelId`	string	✓	Customer-assigned label
`vendorSerial`	string	✓	Vendor serial number
`spaceId`	string	✓	Space where device is installed
`fixedPositionGlobal`	string	✓	GeoJSON Point of fixed installation position

Device Group

Logical groupings of devices.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`modelType`	string	✗	Group model (e.g., `com.haltian.device-group`)
`externalId`	string	✓	External system identifier
`manufacturingDate`	timestamp	✓	Manufacturing date
`shippingDate`	timestamp	✓	Shipping date
`warrantyDate`	timestamp	✓	Warranty expiration
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Note

Device groups also appear in the device table. They exist in both device.parquet and deviceGroup.parquet.

Device Group Devices

Junction table linking devices to device groups.

Column	Type	Nullable	Description
`deviceGroupId`	string	✗	Reference to device group
`deviceId`	string	✗	Reference to device

Device Keyword

Tags and labels assigned to devices.

Column	Type	Nullable	Description
`deviceId`	string	✗	Reference to device
`keyword`	string	✗	Keyword/tag value
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Device Note

Freeform notes attached to devices.

Column	Type	Nullable	Description
`deviceId`	string	✗	Reference to device
`note`	string	✗	Note text
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Space

Spatial hierarchy: locations, buildings, floors.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`name`	string	✓	Space name
`parentId`	string	✓	Parent space (hierarchical)
`type`	string	✗	Type: `location`, `building`, `floor`
`positionGlobal`	string	✓	GeoJSON Point coordinates
`northVector`	decimal128(38, 20)	✓	North direction angle (degrees)
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Root Spaces

A null parentId indicates a root-level space with no parent.

Zone

Defined areas within spaces.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`spaceId`	string	✗	Parent space reference
`name`	string	✗	Zone name
`polygonGlobal`	string	✗	GeoJSON polygon boundaries
`createdAt`	timestamp	✗	Creation timestamp
`updatedAt`	timestamp	✓	Last update timestamp

Measurement Schemas

All measurement tables share common columns plus measurement-specific values.

Common Columns

Every measurement table includes:

Column	Type	Nullable	Description
`deviceId`	string	✗	Device that reported the measurement
`measuredAt`	timestamp	✗	Measurement timestamp

measurementAmbientTemperature

Ambient temperature readings.

Column	Type	Nullable	Description
`ambientTemperature`	decimal128(38, 20)	✗	Temperature in degrees Celsius

measurementBatteryPercentage

Battery charge level.

Column	Type	Nullable	Description
`batteryPercentage`	decimal128(38, 20)	✗	Battery level (0–100%)

measurementBatteryVoltage

Battery voltage readings.

Column	Type	Nullable	Description
`batteryVoltage`	decimal128(38, 20)	✗	Voltage in volts

measurementBootCount

Device restart events.

Column	Type	Nullable	Description
`bootCount`	int64	✗	Cumulative boot count
`bootReason`	string	✓	Reason for restart

measurementCO2

Carbon dioxide concentration.

Column	Type	Nullable	Description
`co2`	decimal128(38, 20)	✗	CO₂ level in ppm

measurementDirectionalMovement

Entry and exit counts (e.g., doorway sensors).

Column	Type	Nullable	Description
`entries`	int64	✗	Number of entries
`exits`	int64	✗	Number of exits

measurementDistance

Distance measurements.

Column	Type	Nullable	Description
`distance`	decimal128(38, 20)	✗	Distance (typically mm)

measurementOccupancySeconds

Duration of occupancy within measurement period.

Column	Type	Nullable	Description
`occupancySeconds`	decimal128(38, 20)	✗	Occupancy duration in seconds

measurementOccupancyStatus

Binary occupancy state.

Column	Type	Nullable	Description
`isOccupied`	bool	✗	`false` = unoccupied, `true` = occupied

measurementOccupantsCount

Number of people detected.

Column	Type	Nullable	Description
`occupantsCount`	int64	✗	Number of occupants

measurementPosition

Device location tracking.

Column	Type	Nullable	Description
`isStatic`	bool	✗	`false` = moving, `true` = stationary
`spaceId`	string	✗	Space where device is located
`positionGlobal`	string	✗	GeoJSON Point coordinates

measurementPositionZone

Zone-relative device position.

Column	Type	Nullable	Description
`zoneId`	string	✗	Zone where device is located

measurementSystemTemperature

Device internal (system) temperature readings.

Column	Type	Nullable	Description
`systemTemperature`	decimal128(38, 20)	✗	Internal temperature in degrees Celsius

measurementTVOC

Total Volatile Organic Compounds.

Column	Type	Nullable	Description
`tvoc`	decimal128(38, 20)	✗	TVOC level (ppb or index)

GeoJSON Formats

Point (position data)

{
  "type": "Point",
  "coordinates": [longitude, latitude]
}

Example: {"type":"Point","coordinates":[25.4686, 65.0592]}

Polygon (zone boundaries)

{
  "type": "Polygon",
  "coordinates": [[[lon1, lat1], [lon2, lat2], [lon3, lat3], [lon1, lat1]]]
}

UUID Format

All identifiers use lowercase hyphenated UUID format:

550e8400-e29b-41d4-a716-446655440000

Timestamp Format

All timestamps are:

Timezone: UTC
Precision: Milliseconds
Storage: Arrow timestamp type

When reading in most languages, timestamps convert automatically to native datetime types.