#1056 Proposal: enhancements to hisRead/hisWrite for batch read/write

Brian Frank Wed 19 Apr 2023

I'd like to propose an enhancement to the HTTP API for hisRead and hisWrite to allow batch reads/writes.

This comes up quite a bit. There was previous discussion in topics 339 and 347 (way back in 2015).  The design I propose is in-line with those discussions.

This proposal keeps the existing behavior untouched and fully backward compatible.   But adds the ability to read and write multiple history points in one request.


Current design for one read:

// request

// reponse
ver:"3.0" id:@someTemp hisStart:2012-10-01T00:00:00-04:00 New_York hisEnd:2012-10-02T00:00:00-04:00 New_York
2012-10-01T00:15:00-04:00 New_York,72.1°F

Proposed design for batch read

// request
ver:"3.0" range:"2012-10-01" 

// response
ver:"3.0" hisStart:2012-10-01T00:00:00-04:00 New_York hisEnd:2012-10-02T00:00:00-04:00 New_York
ts,                                  v0 id:@hisA,  v1 id:@hisB,  v2 id:@hisB  
2012-10-01T00:15:00-04:00 New_York,  72.1°F,       10%,          80°F
2012-10-01T00:30:00-04:00 New_York,  73.0°F,       N,            N 
2012-10-01T00:45:00-04:00 New_York,  N,            20%,          N 


  • range moved to meta
  • can have one or more rows of ids
  • response includes multiple value columns with the corresponding ids
  • can include the whole point dict in the column meta (this is what we do)
  • first column must be timestamp
  • values are joined by timestamp, use null cells to indicate sparse data
  • points must have the same timezone or meta tz tag is required to specify the timezone to use and timezones are converted by server


Current design for one write:

// request
ver:"3.0" id:@hisId
2012-04-21T08:30:00-04:00 New_York,72.2
2012-04-21T08:45:00-04:00 New_York,76.3

Proposed design for batch write:

// request
ts,                                 v0 id:@hisA,  v1 id:@hisB 
2012-04-21T08:30:00-04:00 New_York, 72.2,         10 
2012-04-21T08:45:00-04:00 New_York, 76.3,         N 
2012-04-21T09:00:00-04:00 New_York, N,            12


  • first column must be named ts and contain timestamps
  • any additional columns can history data (can be named anything)
  • each value column specifies an id of the point being written
  • use null for value cells without a value for that row's timestamp

Jay Herron Thu 20 Apr 2023

I love these suggestions! I was recently surprised to find that hisRead only supported a single individual point.

Not that I think it should be part of this effort, but what are your thoughts on allowing a filter input for hisRead? Or do you think it's best as a 2-step process - a read followed by a hisRead?

Brian Frank Wed 31 May 2023

I did add to the docs for more thorough review. Also I added a little bit of JS so you can see all the examples in both Zinc and JSON (very simple toggle right now).

Login or Signup to reply.