Skip to main content

Streamed Responses

A query for every thing or every point of a large portfolio can produce a response of hundreds of megabytes. The API does not build such a response in memory and then send it. It writes the response while it reads the data, a window of rows at a time, and tells you so with x-mapped-response-mode: streamed.

The body is the same JSON document you would get otherwise. Nothing in your query asks for this, and a client that reads the whole body and parses it does not need to change.

When a Response Is Streamed​

A response is streamed when all of these hold:

  • The request carries one query. A batch of several operations in one request is answered in one piece.
  • The query selects a list at its top level, such as things, points or buildings, and that list is long (more than about a thousand items).
  • The query does not use @defer or @stream. Those are answered in parts instead.

Everything else is buffered. Do not rely on a particular request being streamed: the threshold can change, and the same query is buffered for a small organization and streamed for a large one.

What Is Different​

BufferedStreamed
BodyOne JSON document.The same JSON document.
TransferContent-Length.Transfer-Encoding: chunked. The first bytes arrive before the last rows have been read.
errorsBefore or after data.Always after data.
Billable headersx-mapped-billable-bytes, x-mapped-billable-rus.Not sent. See Response Headers.
A failure part-wayThe request fails with an error response.The connection is closed early. See A Response That Is Cut Off.

Two more things follow from writing while reading:

  • The list is not a snapshot. A row that is deleted while the response is being written may be missing from it, and a row that is added may not be in it.
  • The API reads as fast as you do. If your client reads slowly, the API waits instead of buffering the rest. If your client closes the connection, the API stops reading.

Reading a Streamed Response​

If the response fits comfortably in memory, do nothing: let your HTTP client collect the body and parse it.

For a very large response, parse the body as a stream, so your process holds one row at a time instead of the whole document. Use a streaming JSON parser (for example ijson in Python or stream-json in Node.js), point it at the top-level list, data.things in the query below, and handle each item as it arrives.

query {
things {
id
name
exactType
}
}

Whichever way you read it, check for errors once the body has ended, and treat a connection that closes early as a failed request.

Choosing What Arrives First​

Streaming decides how a response is written, not what is in it or in which order. To choose what your application receives first, page through a list with the paginated fields, or use @defer and @stream.