💻HTTP Interface

How to use the HTTP interface


The HTTP interface is composed of only two routes.



get schemas, tables, columns metadata

A JSON-formatted representation of the database catalog


process SQL queries

An SQL query in the HTTP request's body

A JSON-formatted result set


Various parameters of the query influence the caching behavior of the query endpoint. We try to stay as close to standard HTTP caching as possible and implement custom extensions only when needed. Cache-related parameters must be passed through the standard Cache-Control header (or cache-control query param).

supported directivesemantic


Bypass query cache


Do not store the result of this query in the query cache


The client can tolerate a result at most N seconds old

We support some custom request headers related to the caching behavior of the HTTP interface.



The value must be a float between 0 and 1. On cache hit, we compute the ratio Age / Max-Age with this value and trigger an asynchronous cache refresh when the value is higher than the aforementioned ratio.

Some cache-related headers are set on the response.



will be set to hit if the resultset comes from the cache, miss otherwise


max-age, no-cache and no-store directives will be set to ensure no intermediate (browser, proxy, ...) cache the response. This ensures we have complete control over caching so that features like asynchronous cache refresh work as expected.


this header is set on cache hit with the age (in seconds) of the served result

Last updated