Folder Structure

S3 bucket organization and file naming conventions

Directory Layout

Parquet files are organized in a predictable hierarchy within your S3 bucket:

downloads/parquet/
└── {organizationId}/                    # Your organization UUID
    ├── device/
    │   └── {year}/
    │       └── {month}/
    │           └── {year}_{month}_{day}_{hour}_{entityType}.parquet
    ├── deviceGroup/
    ├── deviceGroupDevices/
    ├── deviceKeyword/
    ├── measurementAmbientTemperature/
    ├── measurementBatteryPercentage/
    ├── measurementBatteryVoltage/
    ├── measurementBootCount/
    ├── measurementCO2/
    ├── measurementDirectionalMovement/
    ├── measurementDistance/
    ├── measurementOccupancySeconds/
    ├── measurementOccupancyStatus/
    ├── measurementOccupantsCount/
    ├── measurementPosition/
    ├── measurementPositionZone/
    ├── measurementTVOC/
    ├── organization/
    ├── space/
    └── zone/

Entity Folders

Each entity type has its own top-level folder:

Folder	Content Type	Description
`organization/`	Entity	Organization metadata
`device/`	Entity	Device inventory and properties
`deviceGroup/`	Entity	Device group definitions
`deviceGroupDevices/`	Relationship	Device-to-group mappings
`deviceKeyword/`	Entity	Device tags and labels
`space/`	Entity	Locations, buildings, floors
`zone/`	Entity	Areas within spaces
`measurementXxx/`	Time-series	Sensor readings by type

File Naming Convention

Files follow the pattern:

{YYYY}_{MM}_{DD}_{HH}_{entityType}.parquet

Component	Format	Description
`YYYY`	4 digits	Year (e.g., `2026`)
`MM`	2 digits	Month (`01`-`12`)
`DD`	2 digits	Day (`01`-`31`)
`HH`	2 digits	Hour in 24h format (`00`-`23`)
`entityType`	string	Entity or measurement type

Examples

2026_01_28_08_device.parquet
2026_01_28_14_measurementOccupancyStatus.parquet
2025_12_31_23_measurementAmbientTemperature.parquet

Time-Based Organization

Files are partitioned by time within each entity folder:

measurementOccupancyStatus/
├── 2025/
│   ├── 10/
│   │   ├── 2025_10_01_00_measurementOccupancyStatus.parquet
│   │   ├── 2025_10_01_01_measurementOccupancyStatus.parquet
│   │   └── ...
│   ├── 11/
│   └── 12/
└── 2026/
    └── 01/
        ├── 2026_01_01_00_measurementOccupancyStatus.parquet
        └── ...

Note

Empty parquet files may exist for time periods with no data. This is normal and ensures consistent file structure.

Accessing Files

AWS CLI Example

List available files for your organization:

aws s3 ls s3://your-bucket/downloads/parquet/{org-id}/device/2026/01/

Download all device data for January 2026:

aws s3 cp s3://your-bucket/downloads/parquet/{org-id}/device/2026/01/ ./device/ --recursive

Programmatic Access

Most data platforms support direct S3 access. See Integration Examples for platform-specific code samples.

Storage Considerations

Aspect	Details
Compression	Snappy compression (Parquet default)
File size	Varies by data volume; typically 1KB–100MB
Retention	Contact Haltian for retention policy details
Updates	New files each export cycle; historical files unchanged