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,pointsorbuildings, and that list is long (more than about a thousand items). - The query does not use
@deferor@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
| Buffered | Streamed | |
|---|---|---|
| Body | One JSON document. | The same JSON document. |
| Transfer | Content-Length. | Transfer-Encoding: chunked. The first bytes arrive before the last rows have been read. |
errors | Before or after data. | Always after data. |
| Billable headers | x-mapped-billable-bytes, x-mapped-billable-rus. | Not sent. See Response Headers. |
| A failure part-way | The 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.