...
Jira server Jira Cloud columnIds issuekey,summary,issuetype,created,updated,duedate,assignee,reporter,priority,status,resolution columns key,summary,type,created,updated,due,assignee,reporter,priority,status,resolution serverId 6dd774b6-00ac-3344-8265-fe491188c468 key DM-42617 Jira server Jira Cloud serverId 6dd774b6-00ac-3344-8265-fe491188c468 key DM-43465 Jira server Jira Cloud serverId 6dd774b6-00ac-3344-8265-fe491188c468 key DM-43497
The frontend complements the existing one based on mysql-proxy.
...
| Note | ||||||||
|---|---|---|---|---|---|---|---|---|
The API adheres to the optional version control mechanism introduced in:
Application developers are encouraged to use the mechanism to reinforce the integrity of the applications. The document corresponds to version number 32 33 of the API. |
Each implementation of the API has a specific version. The version number will change if any changes to the implementation or the API that might affect users will be made. The current document will be also kept updated to reflect the latest available version of the API.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"kind":"qserv-czar-query-frontend",
"name":"http",
"id":8,
"instance_id":"qserv-prod",
"version":3233,
"success":1,
...
} |
Push mode
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl 'http://localhost:4041/query-async/status/1234?version=3233' -X GET |
For other HTTP methods used by the API, the number is required to be provided within the body of a request as shown below:
| Code Block | ||||
|---|---|---|---|---|
| ||||
curl 'http://localhost:4041/query-async' -X POST -H 'Content-Type: application/json' -d'{"version":3233,"query":"SELECT ..."}' |
If the number does not match expectations, such a request will fail and the service return the following response. Here is an example of what will happen if the wrong version number 29 is specified instead of 32 33 (as per the current version of the API):
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"success":0,
"error":"The requested version 29 of the API is not in the range supported by the service.",
"error_ext":{
"max_version":32,
"min_version":32
},
"warning":""
} |
Submitting queries
| Anchor | ||||
|---|---|---|---|---|
|
The following REST service implements the synchronous interface:
...
A client is required to pass the JSON object in the request body of the request to specify what query needs to be executed. The object has the following schema:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"query":<string>,
"database":<string>,
"binary_encoding":<string>
} |
Where:
| attr | description | default |
|---|---|---|
query | The query text in which the default database may be missing. In the latter case, a client |
| needs to provide the name in a separate parameter. | ||
database | The optional name of the default database for queries where no such name was provided explicitly. | "" |
A call to this service will block a client application until one of the following events will happen:
- The query will be successfully processed and its result returned to a caller.
- The query will fail and the corresponding error will be returned to the caller.
- The frontend will become unavailable (due to a crash, restart, or networking problem, etc.) and a network connection will be lost.
In case of the successful completion of the request, the service will return a result set in the JSON object explained in the section Result sets.
Asynchronous interface
The following REST service implements the asynchronous interface:
...
A client is required to pass the JSON object in the body of the request to specify what query needs to be executed. The object has the following schema:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"query":<string>,
"database":<string>
} |
Where:
...
query...
binary_encoding | The optional format for encoding the binary data into JSON, where the following options for the values of the parameter are allowed:
The missing parameter will be treated as if the hexadecimal encoding was requested. Here is an example of the same sequence of 4-bytes encoded into the hexadecimal format:
The array representation of the same binary sequence would look like this:
| "hex" |
A call to this service will block a client application until one of the following events will happen:
- The query will be successfully processed and its result is returned to a caller.
- The query will fail and the corresponding error will be returned to the caller.
- The frontend will become unavailable (due to a crash, restart, or networking problem, etc.) and a network connection will be lost.
In case of the successful completion of the request, the service will return a result set in the JSON object explained in the section Result sets.
Asynchronous interface
The following REST service implements the asynchronous interface:
| method | resource name |
|---|---|
| POST | /query-async |
A client is required to pass the JSON object in the request body to specify what query needs to be executed. The object has the following schema:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"query":<string>,
"database":<string>
} |
Where:
| attr | description | default |
|---|---|---|
query | The query text in which the default database may be missing. In the latter case, a client needs to provide the name in a separate parameter. | |
database | The optional name of the default database for queries where no such name was provided explicitly. | "" |
A call to this service will normally block a client application for a short period until one of the following events will happen:
- The query will be successfully analyzed and queued for asynchronous processing by Qserv and a response object with the unique identifier of the query returned to a caller.
- The query will fail and the corresponding error will be returned to the caller.
- The frontend will become unavailable (due to a crash, restart, or networking problem, etc.) and a network connection will be lost.
In case of the successful completion of the request, the service will return the following JSON object:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"queryId":<number>} |
The number reported in the object should be further used for making the following requests explained in the dedicated subsections below:
- checking the status of the query to see when it's finished
- requesting a result set of the query
- or, canceling the query if needed
Checking the status of the ongoing query
This service can be also used for checking the status of queries submitted via the synchronous interface, provided the unique identifier of such query is known to a
...
database...
A call to this service will normally block a client application for a short period until one of the following events will happen:
- The query will be successfully analyzed and queued for asynchronous processing by Qserv and a response object with the unique identifier of the query returned to a caller.
- The query will fail and the corresponding error will be returned to the caller.
- The frontend will become unavailable (due to a crash, restart, or networking problem, etc.) and a network connection will be lost.
In case of the successful completion of the request, the service will return the following JSON object:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"queryId":<number>} |
The number reported in the object should be further used for making the following requests explained in the dedicated subsections below:
- checking the status of the query to see when it's finished
- requesting a result set of the query
- or, canceling the query if needed
Checking the status of the ongoing query
This service can be also used for checking the status of queries submitted via the synchronous interface, provided the unique identifier of such query is known to a user.
The status of the query can be checked using:
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"success":1,
"status":{
"queryId":310554,
"status":"EXECUTING",
"totalChunks":1477,
"completedChunks":112,
"queryBeginEpoch":1708141345,
"lastUpdateEpoch":1708141359
}
} |
The status service could be used by users to make rough estimates of Users could use the status service to estimate when the query will finish. However, normallyNormally, the client applications are encouraged to wait before the query reaches the status "COMPLETED" and fetch a result set by calling another service explained next.
| Anchor | ||||
|---|---|---|---|---|
|
The result sets resultsets could be retrieved by calling the following service:
| method | resource name |
|---|---|
| GET | /query-async/result/<queryId>[?binary_encoding=<encoding>] |
Where:
| attr | type | description | default |
|---|---|---|---|
queryId | number | The unique identifier of the previously submitted query. |
Like in the case of the status inquiry request, if the identifier of the query is not valid then the service will report an error in the response object. Otherwise, a JSON object explained in the section Result sets will be returned.
...
encoding | string | The optional format for encoding the binary data into JSON, where the following options for the values of the parameter are allowed:
The missing parameter will be treated as if the hexadecimal encoding was requested. Here is an example of the same sequence of 4-bytes encoded into the hexadecimal format:
The array representation of the same binary sequence would look like this:
| "hex" |
Like in the case of the status inquiry request, if the query identifier is not valid then the service will report an error in the response object. Otherwise, a JSON object explained in the section Result sets will be returned.
| Anchor | ||||
|---|---|---|---|---|
|
Both flavors of the query submission services will return the following JSON object in case of the successful completion of the queries:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"schema":[
[{"table":<string>, "column":<string>, "type":<string>, "is_binary":<number>], // Col 0
|
Both flavors of the query submission services will return the following JSON object in case of the successful completion of the queries:
| Code Block | ||||
|---|---|---|---|---|
| ||||
{"schema":[ [{"table":<string>, "column":<string>, "type":<string>], // Col 0 [{"table":<string>, "column":<string>, "type":<string>], // Col 1 ... [{"table":<string>, "column":<string>, "type":<string>, "is_binary":<number>], // Col (NUM_COLUMNS - 1) ], "rows":[ // Col 1 ... [{"table":<string>, "column":<string>, "type":<string>, "is_binary":<number>], // Col (NUM_COLUMNS - 1) ], "rows":[ // Col 0 Col 1 Col (NUM_COLUMNS - 1) // ------ -------- -------- [<string>, <string>, ... <string>], // Result row 0 [<string>, <string>, ... <string>], // Result row 1 ... [<string>, <string>, ... <string>], // Result row (NUM_ROWS - 1) ], ... } |
Where:
],
...
} |
Where:
| attr | type | description | |||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
schema | array | A collection of rows, in which each row is a dictionary representing a definition of the corresponding column of the result set:
| |||||||||||||||
| attr | type | description | |||||||||||||||
schema | array | A collection of rows, in which each row is a dictionary representing a definition of the corresponding column of the result set:
| |||||||||||||||
rows | array | A collection of the result rows, where each row is a row of strings representing values at positions of the corresponding columns (see schema attribute above). |
...
Canceling queries
This service can be also used for terminating queries submitted via the synchronous interface, provided the unique identifier of such query is known to a user.
...