Data

InfluxDB

All data is stored in InfluxDB. The following sections describe how the data is stored.

Measurement

The part of InfluxDB’s structure that describes the data stored in the associated fields. Measurements are strings.

InfluxDB measurement documentation

Tags

The key-value pair in InfluxDB’s data structure that records metadata. Tags are an optional part of InfluxDB’s data structure but they are useful for storing commonly-queried metadata; tags are indexed so queries on tags are performant. Query tip: Compare tags to fields; fields are not indexed.

InfluxDB tag documentation

Note

The tag values are always interpreted as strings.

Each tag value should have very few possible values which yields a low series cardinality.

Fields

The key-value pair in InfluxDB’s data structure that records metadata and the actual data value. Fields are required in InfluxDB’s data structure and they are not indexed - queries on field values scan all points that match the specified time range and, as a result, are not performant relative to tags. Query tip: Compare fields to tags; tags are indexed

InfluxDB field documentation

Structure

Data Model

An example of the structures data model, limited to thermostat read/write permissions, from the Nest Data Model Viewer (as JSON):

{
    "structures": {
        "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw": {
            "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw",
            "thermostats": [ "peyiJNo0IldT2YlIVtYaGQ", ... ],
            "smoke_co_alarms": [ "RTMTKxsQTCxzVcsySOHPxKoF4OyCifrs", ... ],
            "cameras": [ "awJo6rH…", ... ],
            "devices": {
            },
            "away": "home",
            "name": "Home",
            "country_code": "US",
            "postal_code": "94304",
            "peak_period_start_time": "2016-10-31T23:59:59.000Z",
            "peak_period_end_time": "2016-10-31T23:59:59.000Z",
            "time_zone": "America/Los_Angeles",
            "eta": {
            },
            "rhr_enrollment": true,
            "wheres": {
                "Fqp6wJI...": {
                }
            }
        }
    }
}

InfluxDB Point

The Data Model example transformed into a list containing a single InfluxDB point (as Python):

[
    {
        "measure": "structure",
        "tags": {
            "away": "home",
            "country_code": "US",
            "name": "Home",
            "postal_code": "94304",
            "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw",
            "thermostat_id": "peyiJNo0IldT2YlIVtYaGQ",
            "time_zone": "America/Los_Angeles"
        },
        "fields": {
            "is_away": 0
        }
    }
]

Note

The Data Model thermostats list is denormalized into a point per thermostat id.

Measurement

den records structure data in a measurement named structure.

Fields

  1. is_away is a numeric representation of the away tag, i.e., home as 0, away as 1

Thermostat

Data Model

An example of the devices data model, limited to thermostat read/write permissions, from the Nest Data Model Viewer (as JSON):

{
    "devices": {
        "thermostats": {
            "peyiJNo0IldT2YlIVtYaGQ": {
                "ambient_temperature_c": 21.5,
                "ambient_temperature_f": 72,
                "away_temperature_high_c": 24.5,
                "away_temperature_high_f": 80,
                "away_temperature_low_c": 19.5,
                "away_temperature_low_f": 65,
                "can_cool": true,
                "can_heat": true,
                "device_id": "peyiJNo0IldT2YlIVtYaGQ",
                "eco_temperature_high_c": 24.5,
                "eco_temperature_high_f": 80,
                "eco_temperature_low_c": 19.5,
                "eco_temperature_low_f": 65,
                "fan_timer_active": true,
                "fan_timer_duration": 15,
                "fan_timer_timeout": "2016-10-31T23:59:59.000Z",
                "has_fan": true,
                "has_leaf": true,
                "humidity": 40,
                "hvac_mode": heat,
                "hvac_state": "heating",
                "is_locked": true,
                "is_online": true,
                "is_using_emergency_heat": true,
                "label": "Pat's room",
                "last_connection": "2016-10-31T23:59:59.000Z",
                "locale": "en-US",
                "locked_temp_max_c": "24.5",
                "locked_temp_max_f": "80",
                "locked_temp_min_c": "19.5",
                "locked_temp_min_f": "65",
                "name": "Hallway (upstairs)",
                "name_long": "Hallway Thermostat (upstairs)",
                "previous_hvac_mode": heat,
                "software_version": "4.0",
                "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw",
                "sunlight_correction_active": true,
                "sunlight_correction_enabled": true,
                "target_temperature_c": 21.5,
                "target_temperature_f": 72,
                "target_temperature_high_c": 24.5,
                "target_temperature_high_f": 80,
                "target_temperature_low_c": 19.5,
                "target_temperature_low_f": 65,
                "temperature_scale": "C",
                "time_to_target": "~15",
                "time_to_target_training": "training",
                "where_id": "UNCBGUnN24...",
                "where_name": "Hallway"
            }
        }
    }
}

InfluxDB Point

The Data Model example transformed into a list containing a single InfluxDB point (as Python):

[
    {
        "measurement": "thermostat",
        "tags": {
            "can_cool": True,
            "can_heat": True,
            "device_id": "peyiJNo0IldT2YlIVtYaGQ",
            "fan_timer_active": True,
            "has_fan": True,
            "has_leaf": True,
            "hvac_mode": "heat",
            "hvac_state": "heating",
            "is_locked": True,
            "is_online": True,
            "is_using_emergency_heat": True,
            "label": "Pat's room",
            "locale": "en-US",
            "name": "Hallway (upstairs)",
            "name_long": "Hallway Thermostat (upstairs)",
            "previous_hvac_mode": "heat",
            "software_version": "4.0",
            "structure_id": "VqFabWH21nwVyd4RWgJgNb292wa7hG_dUwo2i2SG7j3-BOLY0BA4sw",
            "sunlight_correction_active": True,
            "sunlight_correction_enabled": True ,
            "temperature_scale": "C",
            "time_to_target": "~15",
            "time_to_target_training": "training" ,
            "where_id": "UNCBGUnN24...",
            "where_name": "Hallway"
        },
        "fields": {
            "ambient_temperature_c": 21.5,
            "ambient_temperature_f": 72,
            "away_temperature_high_c": 24.5,
            "away_temperature_high_f": 80,
            "away_temperature_low_c": 19.5,
            "away_temperature_low_f": 65,
            "eco_temperature_high_c": 24.5,
            "eco_temperature_high_f": 80,
            "eco_temperature_low_c": 19.5,
            "eco_temperature_low_f": 65,
            "fan_timer_duration": 15,
            "humidity": 40,
            "locked_temp_max_c": 24.5,
            "locked_temp_max_f": 80,
            "locked_temp_min_c": 19.5,
            "locked_temp_min_f": 65,
            "target_temperature_c": 21.5,
            "target_temperature_f": 72,
            "target_temperature_high_c": 24.5,
            "target_temperature_high_f": 80,
            "target_temperature_low_c": 19.5,
            "target_temperature_low_f": 65,
        }
    },
]

Note

The following parameters are not recorded:

Measurement

den records thermostat data in a measurement named thermostat.

Weather

Data Model

An example of the weather data model Powered by Dark Sky, a “currently” data point object (as JSON):

Note

time is the only value guaranteed to be present in a data point object.

{
  "apparentTemperature": 46.93,
  "cloudCover": 0.73,
  "dewPoint": 47.7,
  "humidity": 0.96,
  "icon": "rain",
  "nearestStormDistance": 0,
  "ozone": 328.35,
  "precipIntensity": 0.1685,
  "precipIntensityError": 0.0067,
  "precipProbability": 1,
  "precipType": "rain",
  "pressure": 1009.7,
  "summary": "Rain",
  "temperature": 48.71,
  "time": 1453402675,
  "visibility": 4.3,
  "windBearing": 186,
  "windSpeed": 4.64
}

InfluxDB Point

The Data Model example transformed into a list containing a single InfluxDB point (as Python):

Note

The summary property “has millions of possible values” according to the data point object documentation. This would result in a high series cardinality. It is therefore not included as a tag. It also has no value as field so it is not included in the measurement at all.

[
    {
        "measurement": "weather",
        "tags": {
            "icon": "rain",
            "precipType": "rain"
        },
        "fields": {
            "apparentTemperature": 46.93,
            "cloudCover": 0.73,
            "dewPoint": 47.7,
            "humidity": 0.96,
            "nearestStormDistance": 0,
            "ozone": 328.35,
            "precipIntensity": 0.1685,
            "precipIntensityError": 0.0067,
            "precipProbability": 1,
            "pressure": 1009.7,
            "temperature": 48.71,
            "time": 1453402675,
            "visibility": 4.3,
            "windBearing": 186,
            "windSpeed": 4.64
        }
    }
]

Measurement

den records weather data in a measurement named weather.

Tags

  1. icon
  2. precipType

Fields

  1. apparentTemperature
  2. cloudCover
  3. dewPoint
  4. humidity
  5. nearestStormBearing
  6. nearestStormDistance
  7. ozone
  8. precipIntensity
  9. precipProbability
  10. pressure
  11. temperature
  12. time
  13. visibility
  14. windBearing
  15. windSpeed

Propane

Data Model

{
    "device": {
        "name": "Sample Device",
        "address": "6 Dane St., Somerville, MA 02143, USA",
        "capacity": 100,
        "status": "deployed",
        "orientation": "horizontal",
        "fuelType": "propane",
        "lastReading": {
            "tank": 20,
            "temperature": 72.12,
            "time": 1444338760345,
            "time_iso": "2015-10-08T21:12:40.345Z"
        }
    }
}

InfluxDB Point

Measurement

den records propane data in a measurement named propane.

Tags

  1. device
  2. name
  3. address
  4. status
  5. orientation
  6. fuelType

Fields

  1. capacity
  2. tank
  3. temperature