Introduction
With the Coginiti Execution API, users can effortlessly fetch data sets defined in the analytics catalog, bringing ease of use along with increased governance. It is designed to be compatible with popular data visualization and analysis tools such as PowerBI, Excel, and Jupyter Notebooks. It also could be used with popular orchestration tools such as Dagster or Kestra to trigger CoginitiScript publications or run data quality tests, ensuring both data consistency and reliability.
Base URL
All API URLs referenced in this documentation have the following base URL unless otherwise specified:
{hostname}/api/v1
Authentication
The following API requires authentication with a personal access token created in the Coginiti UI. Please follow the instructions here on how to create a personal access token.
Executing catalog assets to get a single result set
The given endpoint is used to execute a given script from the catalog and get a single result set. If the script produces several result sets, for example, when there are multiple SELECT statements present, only the first one will be executed and returned to the client.
Endpoint: {hostname}/api/v1/exec/script
Type of request: POST
Result format: JSON
Request example using curl application:
curl -X POST '{hostname}/api/v1/exec/script' \
--header 'Authorization: Bearer _YOUR_ACCESS_TOKEN_HERE_' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
"path": "Teams/Engineering/Reports/performance",
"params": {
"start_date": "2012-01-01",
"end_date": "2012-12-31"
},
"connection": {
"name": "My Connection"
}
}'
Body payload:
| name | description |
|---|---|
| path | Absolute path to the catalog asset within the catalog. |
| params | Object with parameter names and their values that need to be passed into the script to be substituted instead of $params. |
| connection.name | Name of the connection |
Returns an object which represent result of the execution or an error otherwise.
| name | description |
|---|---|
| stats | Statistics object. |
| stats.started_at | Timestamp when execution started. |
| stats.finished_at | Timestamp when execution finished. |
| stats.duration_ms | Duration of execution in milliseconds. |
| result | Optional field. Contains result dataset if execution returns any data. |
Dataset object has the following structure:
| name | description |
|---|---|
| columns | A list of the names and types of the columns returned by the query. |
| data | A list of the rows returned by the query request. Each row is itself a list that holds values of the columns in the row, in the order specified by the columns attribute. |
The additional metadata which associated with the given execution is passed as HTTP headers.
| name | description |
|---|---|
| X-Coginiti-Execution-Started-At | Timestamp when execution started |
Example of the response (including HTTP headers):
HTTP/2 200
Date: Wed, 01 Nov 2023 10:03:17 GMT
Content-Type: application/json
X-Coginiti-Execution-Started-At: 2023-11-01T10:03:17.354799859Z
Vary: Accept-Encoding
Server: envoy
{ "result": { "columns": [ { "name": "col_1", "type": "INTEGER" }, { "name": "col_2", "type": "STRING" } ], "data": [ [ 1, "a" ], [ 2, "b" ] ] }, "stats": { "started_at": "2023-08-10T15:06:57.581939751Z", "finished_at": "2023-08-10T15:07:57.581939751Z", "duration_ms": 1000 } }
Specifying response format for single result
The Accept request HTTP header can be used by clients to specify in what format they want the result to be returned by the API. Supported options are:
- application/json (used as a default option when no
Acceptheader is specified) - text/csv (comming soon)
- application/vnd.apache.arrow.stream (comming soon)