The Mother of all Queries

Down the API query endpoints rabbit hole.

I got burnt one too many times by the intricacies of how queries work in Quantum Leap that I decided to put together some notes to help me cope with the hairy details. So here goes!

Each API query endpoint is backed by a front-end query handler in the Reporter component—e.g. the query_1TNENA function handles GETs on /v2/types/{entityType}. These front-end procedures extract query inputs from URL/HTTP headers and use them to call a back-end query function in the Crate translator component. Back-end query functions build SQL queries out of the given inputs, ask Crate to run the SQL, collect results into a list of dictionaries and finally return it to front-end functions in the Reporter. On getting this list back, the front-end function massages it into a JSON object and sends the object to the client in the HTTP response body unless the list is empty in which case the client gets a 404.

The query handler for the /v2/entities endpoint calls query_ids, a function defined in translators.crate, whereas all other front-end query handlers call the query function—also defined in the crate module. To understand how queries work we have to have a good grasp of the query method in the Crate translator. (query_ids is much simpler so we'll leave it out.)

In the upcoming sections we will

1. build a conceptual model of the back-end query function to help us understand and reason about what actually happens under the bonnet;
2. use that model to analyse success and failure scenarios and
3. pin down issues with the current spec/implementation.

---

Next