The QuestDB REST API is based around standard HTTP features and is understood by off-the-shelf HTTP clients. It provides a simple way to interact with QuestDB and is compatible with most programming languages. API functions are fully keyed on the URL and they use query parameters as their arguments.
Responses are function specific, for example you can download query results as CSV files, directly from the API. You can also get JSON responses.
The REST API can be accessed interactively using Web Console that is a part of QuestDB distribution. Find out more in the section using the Web Console.
Other machines on your network can access the console and the REST API on
All strings need to be passed as url-encoded, for example by using
/imp - Loading data
/imp streams tabular text data directly into a table. It supports
CSV, TAB and Pipe (
|) delimited inputs and optional headers. There are no
restrictions on data size. Data type and structure is detected automatically and
usually without additional configuration. However in some cases additional
configuration can be provided to augment automatic detection results.
The structure detection algorithm analyses the chunk in the beginning and relies on relative uniformity of data. When the first chunk is non-representative of the rest of the data, automatic imports can yield errors.
/imp column names from header row as table columns. The following characters
are removed from column names:
When a header row is missing, column names are generated automatically.
/imp is fully ACID compliant, although Atomicity and Durability can be relaxed
to meet convenience and performance demands.
Atomicity is fully insured against any connection problems. If server
detects closed socket the entire request is rolled back instantly and
transparently for any existing readers. The only time data can be partially
imported is when atomicity is in
relaxed mode and data cannot be
converted to column type. In this scenario "defective" row of data is discarded
/imp continues to stream request data into table.
Consistency is guaranteed by consistency of append transactions against QuestDB storage engine.
Isolation Data is committed to QuestDB storage engine at end of request. Uncommitted transactions are not visible to readers.
/imp streams data from network socket buffer directly into
memory mapped files. At this point data is handed over to the OS and is
resilient against QuestDB internal errors and unlikely but hypothetically
possible crashes. This is default method of appending data and it is chosen for
its performance characteristics. In cases where transaction has to be resilient
against OS errors or power losses physical durability can be enforced. At a cost
of append performance QuestDB storage engine will also guarantee that each
memory block is flushed to physical device.
The following examples upload
ratings.csv. This file can be found at
grouplens.org. The response shows
table name, columns, types, error count in each column and total rows. When
column types are correct, error count must be
JSON response for the same request would be:
Import with user-defined schema
This example overrides types of
movieId by including
parameter. Schema is passed as a
Import with multiple options
This example shows the concatenation of several import parameters
/exec - Querying Data
/exec compiles and executes the SQL query supplied as an argument and returns
a JSON object with either data or an error. The error object contains
message and position in query text. Position is a number of characters from
beginning of query where error occurred.
The result of a successful execution is a JSON object containing an array of
data rows. Each data row is array of column values. The dataset metadata is
columns field - list of column names and their types.
Query execution terminates automatically when the socket connection is closed.
/exec is HTTP GET request with following query arguments:
|Paging argument. For example, |
|Counts the number of rows and returns this value in the message header. Default value is |
|Skips the metadata section of the response when set to |
The following will use
curl to send a query over http. The result will be sent
back over HTTP.
query text must be URL-encoded.
This is an example of successful query execution response. HTTP status code
Example of error response. HTTP status code
400 is used for query errors and
500 for internal server errors, which should not normally occur.
/exp - Export Data
/exp allows you to pass url-encoded queries. Instead of a
json, the results are returned in tabular form to be saved into a file such as
Server responds with HTTP
200 when query execution is successful and
when there is error and returns error text.
/exp is HTTP GET request with following query arguments: |Argument | Remarks |
query (required) |
URL-encoded query text. It can be multi-line |
limit (optional) | Paging argument. For example,
limit=10,20 will return
row numbers 10 thru to 20 inclusive.and
limit=20 will return first 20 rows,
which is equivalent to
limit=-20 will return the last 20 rows.|
Below is example of exporting data from command line using
When query contains syntax errors
/exp attempts to return as much diagnostic
information as possible. Example erroneous request: