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.
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
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¶
is_away
is a numeric representation of theaway
tag, i.e.,home
as0
,away
as1
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,
}
},
]
Measurement¶
den
records thermostat data in a measurement named thermostat
.
Tags¶
- can_cool
- can_heat
- device_id
- fan_timer_active
- has_fan
- has_leaf
- hvac_mode
- hvac_state
- is_locked
- is_online
- is_using_emergency_heat
- label
- locale
- name_long
- name
- previous_hvac_mode
- software_version
- structure_id
- sunlight_correction_active
- sunlight_correction_enabled
- temperature_scale
- time_to_target_training
- time_to_target
- where_id
- where_name
Fields¶
- ambient_temperature_c
- ambient_temperature_f
- away_temperature_high_c
- away_temperature_high_f
- away_temperature_low_c
- away_temperature_low_f
- eco_temperature_high_c
- eco_temperature_high_f
- eco_temperature_low_c
- eco_temperature_low_f
- fan_timer_duration
- humidity
- locked_temp_max_c
- locked_temp_max_f
- locked_temp_min_c
- locked_temp_min_f
- target_temperature_c
- target_temperature_f
- target_temperature_high_c
- target_temperature_high_f
- target_temperature_low_c
- target_temperature_low_f
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¶
icon
precipType
Fields¶
apparentTemperature
cloudCover
dewPoint
humidity
nearestStormBearing
nearestStormDistance
ozone
precipIntensity
precipProbability
pressure
temperature
time
visibility
windBearing
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¶
device
name
address
status
orientation
fuelType
Fields¶
capacity
tank
temperature