Schema Reference

Complete column definitions for all Parquet entities and measurements

Data Types

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

Type	Description
`string`	UTF-8 encoded text
`int8`	8-bit signed integer
`int32`	32-bit signed integer
`uint32`	32-bit unsigned integer
`float`	32-bit floating point
`decimal128(10, 0)`	128-bit decimal, precision 10, scale 0
`timestamp[ms, tz=UTC]`	Millisecond-precision UTC timestamp

Entity Schemas

Organization

Organization metadata.

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

Device

IoT device inventory and properties.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`name`	string	✗	Device name
`organizationId`	string	✓	Reference to organization
`model`	string	✗	Device model (e.g., `com.haltian.device.tsar02`)
`externalId`	string	✓	External system identifier
`tuid`	string	✓	Thingsee Unique Identifier
`installationStatus`	string	✗	Status: `new`, `installed`, etc.
`manufacturingDate`	timestamp	✓	Manufacturing date
`shippingDate`	timestamp	✓	Shipping date
`warrantyDate`	timestamp	✓	Warranty expiration
`createdTs`	timestamp	✗	Creation timestamp
`updatedTs`	timestamp	✓	Last update timestamp
`lastSeen`	timestamp	✓	Last communication time
`wirepasNodeId`	uint32	✓	Wirepas mesh node ID
`wirepasNetworkId`	uint32	✓	Wirepas mesh network ID
`imei`	string	✓	IMEI (cellular devices)
`iccid`	string	✓	SIM card ICCID
`bluetoothMac`	string	✓	Primary Bluetooth MAC
`bluetoothMac2`	string	✓	Secondary Bluetooth MAC
`lanMac`	string	✓	LAN MAC address
`wifiMac`	string	✓	WiFi MAC address
`customerLabelId`	string	✓	Customer-assigned label
`vendorSerial`	string	✓	Vendor serial number

Device Group

Logical groupings of devices.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`organizationId`	string	✓	Reference to organization
`model`	string	✗	Group model (e.g., `com.haltian.device-group`)
`externalId`	string	✓	External system identifier
`installationStatus`	string	✗	Installation status
`manufacturingDate`	timestamp	✓	Manufacturing date
`shippingDate`	timestamp	✓	Shipping date
`warrantyDate`	timestamp	✓	Warranty expiration
`createdTs`	timestamp	✗	Creation timestamp
`updatedTs`	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
`organizationId`	string	✓	Reference to organization

Device Keyword

Tags and labels assigned to devices.

Column	Type	Nullable	Description
`deviceId`	string	✗	Reference to device
`organizationId`	string	✗	Reference to organization
`keyword`	string	✗	Keyword/tag value
`createdTs`	timestamp	✗	Creation timestamp
`updatedTs`	timestamp	✓	Last update timestamp

Space

Spatial hierarchy: locations, buildings, floors.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`name`	string	✓	Space name
`organizationId`	string	✗	Reference to organization
`parentSpaceId`	string	✓	Parent space (hierarchical)
`type`	string	✗	Type: `location`, `building`, `floor`
`positionGlobal`	string	✓	GeoJSON Point coordinates
`northVector`	float	✓	North direction angle (degrees)
`createdTs`	timestamp	✗	Creation timestamp
`updatedTs`	timestamp	✓	Last update timestamp

Root Spaces

A parentSpaceId of 00000000-0000-0000-0000-000000000000 indicates a root-level space with no parent.

Zone

Defined areas within spaces.

Column	Type	Nullable	Description
`id`	string	✗	Unique identifier (UUID)
`organizationId`	string	✗	Reference to organization
`spaceId`	string	✗	Parent space reference
`name`	string	✗	Zone name
`polygonGlobal`	string	✗	GeoJSON polygon boundaries
`createdTs`	timestamp	✗	Creation timestamp
`updatedTs`	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
`ts`	timestamp	✗	Measurement timestamp
`organizationId`	string	✓	Reference to organization

measurementAmbientTemperature

Ambient temperature readings.

Column	Type	Nullable	Description
`ambientTemperature`	float	✗	Temperature in degrees Celsius

measurementBatteryPercentage

Battery charge level.

Column	Type	Nullable	Description
`batteryPercentage`	float	✗	Battery level (0–100%)

measurementBatteryVoltage

Battery voltage readings.

Column	Type	Nullable	Description
`batteryVoltage`	float	✗	Voltage in volts

measurementBootCount

Device restart events.

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

measurementCO2

Carbon dioxide concentration.

Column	Type	Nullable	Description
`co2`	float	✗	CO₂ level in ppm

measurementDirectionalMovement

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

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

measurementDistance

Distance measurements.

Column	Type	Nullable	Description
`distance`	decimal128(10,0)	✗	Distance (typically mm)

measurementOccupancySeconds

Duration of occupancy within measurement period.

Column	Type	Nullable	Description
`occupancySeconds`	float	✗	Occupancy duration in seconds

measurementOccupancyStatus

Binary occupancy state.

Column	Type	Nullable	Description
`status`	int8	✗	`0` = unoccupied, `1` = occupied

measurementOccupantsCount

Number of people detected.

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

measurementPosition

Device location tracking.

Column	Type	Nullable	Description
`isStatic`	int8	✗	`0` = moving, `1` = 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

measurementTVOC

Total Volatile Organic Compounds.

Column	Type	Nullable	Description
`tvoc`	float	✗	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.