Folder Structure

Directory Layout

New path format (current)

parquet/
└── v1/
    └── {organizationId}/
        ├── devices/
        │   └── {year}/
        │       └── {month}/
        │           └── {YYYY_MM_DD_HHMM}_{YYYY_MM_DD_HHMM}_devices.parquet
        ├── organizations/
        ├── spaces/
        ├── zones/
        ├── deviceGroups/
        ├── deviceGroupDevices/
        ├── deviceKeywords/
        ├── deviceNotes/
        ├── measurementAmbientTemperature/
        ├── measurementBatteryPercentage/
        ├── measurementBatteryVoltage/
        ├── measurementBootCount/
        ├── measurementCO2/
        ├── measurementDirectionalMovement/
        ├── measurementDistance/
        ├── measurementOccupancySeconds/
        ├── measurementOccupancyStatus/
        ├── measurementOccupantsCount/
        ├── measurementPosition/
        ├── measurementPositionZone/
        ├── measurementSystemTemperature/
        └── measurementTVOC/

Old path format (legacy)

parquet/
└── {organizationId}/
    ├── device/
    │   └── {year}/
    │       └── {month}/
    │           └── {YYYY_MM_DD_HH}_{dataType}.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 names differ slightly between the old and new path formats (singular vs. plural):

File Naming Convention

New format

Files include both the start and end timestamp of the export window:

{YYYY_MM_DD_HHMM}_{YYYY_MM_DD_HHMM}_{dataType}.parquet

Examples:

2026_03_20_1400_2026_03_20_1500_measurementCO2.parquet
2026_03_20_0000_2026_03_20_0100_devices.parquet

Old format

Files use only the start hour of the export window:

{YYYY_MM_DD_HH}_{dataType}.parquet

Examples:

2026_01_28_08_device.parquet
2026_01_28_14_measurementOccupancyStatus.parquet

Time-Based Organization

Files are partitioned by year and month within each entity folder:

measurementOccupancyStatus/
├── 2025/
│   ├── 11/
│   │   ├── 2025_11_01_0000_2025_11_01_0100_measurementOccupancyStatus.parquet
│   │   ├── 2025_11_01_0100_2025_11_01_0200_measurementOccupancyStatus.parquet
│   │   └── ...
│   └── 12/
└── 2026/
    └── 03/
        ├── 2026_03_20_1400_2026_03_20_1500_measurementOccupancyStatus.parquet
        └── ...

Accessing Files

AWS CLI Example

List available files (new format):

aws s3 ls s3://<BUCKET>/parquet/v1/{organizationId}/devices/2026/03/

Download all device data for March 2026 (new format):

aws s3 cp s3://<BUCKET>/parquet/v1/{organizationId}/devices/2026/03/ ./devices/ --recursive

Programmatic Access

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

Storage Considerations