start_query_execution¶

PlaygroundApi.start_query_execution(role_id, athena_query_post, content_type=None, _request_timeout=None, _request_auth=None, _content_type=None, _headers=None, _host_index=0)¶

Start a query execution

Submits a SQL statement for asynchronous execution against Athena or Redshift and returns the identifier of the new execution. A 200 means the query was accepted, not that it has finished: poll GET /queries/{queryid} for the state and GET /queries/{queryid}/results for the result set. Be aware that two input errors on this operation are returned as HTTP 500 rather than 400, because the handler raises them as backend exceptions: an unsupported WorkGroup (DWH-1033) and selecting QueryTargetLocation “redshift” in an environment whose datalake is not Redshift (GE-1036).

Parameters:

role_id (str) – Amorphic role ID the request is authorized against. Must be a role the caller belongs to. Missing or unknown role IDs are rejected with AUTH-1001. (required)
athena_query_post (AthenaQueryPost) – (required)
content_type (str) – Must be application/json.
_request_timeout (int, tuple(int, int), optional) – timeout setting for this request. If one number provided, it will be total request timeout. It can also be a pair (tuple) of (connection, read) timeouts.
_request_auth (dict, optional) – set to override the auth_settings for an a single request; this effectively ignores the authentication in the spec for a single request.
_content_type (str, Optional) – force content-type for the request.
_headers (dict, optional) – set to override the headers for a single request; this effectively ignores the headers in the spec for a single request.
_host_index (int, optional) – set to override the host_index for a single request; this effectively ignores the host_index in the spec for a single request.

Return type:

StartQueryExecutionResponse

Returns:

Returns the result object.

Request and Response Examples¶

HTTP: POST /queries

Parameter examples¶

Name	In	Example
`role_id`	header	`"role-admin"`

Request¶

Simple Athena SELECT

{
  "QueryString": "SELECT * FROM sales.monthly_orders LIMIT 100"
}

Query executed against Redshift

{
  "QueryString": "SELECT count(*) FROM public.orders",
  "QueryTargetLocation": "redshift"
}

Base64-encoded statement attached to a workbook

{
  "QueryString": "U0VMRUNUICogRlJPTSBzYWxlcy5tb250aGx5X29yZGVycyBMSU1JVCAxMDA=",
  "Encoding": "base64",
  "WorkbookId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

MERGE INTO, which requires the v3 engine workgroup

{
  "QueryString": "MERGE INTO target t USING source s ON t.id = s.id WHEN MATCHED THEN UPDATE SET t.amount = s.amount",
  "WorkGroup": "AmazonAthenaEngineV3"
}

Success (HTTP 200)¶

Query accepted for execution. The body carries the identifier to poll for status and results.

Request / response example

{
  "QueryId": "b1e6c2a0-9f4d-4c7a-8f2e-1a2b3c4d5e6f"
}

Errors¶

Documented error codes: IPV-1008, IPV-1045, IPV-1041, IPV-1069, IPV-1071, GE-1034, AUTH-1001, AUTH-1030, GE-1060, DWH-1033, GE-1036.

HTTP 400

Input validation or authorization failure. Body is {“Message”: “<CODE> - <text>”}. Codes: IPV-1008 (QueryString missing), IPV-1045 (QueryString or Encoding empty/invalid), IPV-1041 (unknown QueryTargetLocation), IPV-1069 (statement not supported for the selected engine), IPV-1071 (MERGE INTO run under the wrong workgroup), GE-1034 (QueryString is not valid base64), AUTH-1001 / AUTH-1030 / GE-1060 (authorization).

QueryString absent from the body

{
  "Message": "IPV-1008 - Invalid request body, missing key(s) - [QueryString]"
}

Unknown QueryTargetLocation

{
  "Message": "IPV-1041 - Invalid value for QueryTargetLocation"
}

Encoding is base64 but QueryString is not

{
  "Message": "GE-1034 - QueryString is not a valid base64 encoded string"
}

role_id header absent

{
  "Message": "AUTH-1001 - Missing role information in event header"
}

HTTP 500

Backend failure, and also two input conditions the handler raises as backend exceptions: DWH-1033 (unsupported WorkGroup) and GE-1036 (QueryTargetLocation “redshift” on a non-Redshift datalake). Body is {“Message”: “<CODE> - <text>”}.

WorkGroup outside the supported set

{
  "Message": "DWH-1033 - Invalid workgroup provided"
}

Redshift target requested on a non-Redshift datalake

{
  "Message": "GE-1036 - Redshift is not available in this environment"
}