diff --git a/docs/aio.md b/docs/aio.md index d48895a69..9feffb7d6 100644 --- a/docs/aio.md +++ b/docs/aio.md @@ -138,7 +138,7 @@ With `kill_on_interrupt` enabled, which is the default, cancelling the task whil requests cancellation of the query, waits until it reaches a terminal state, and then raises `asyncio.CancelledError`. Cancellation is a best-effort request, so the query can still end as `SUCCEEDED` or `FAILED`. The `query_id` property keeps the ID of the cancelled query. -If the cancellation request fails, `asyncio.CancelledError` is raised with the error as its cause. +If the cancellation request or that wait fails, `asyncio.CancelledError` is raised with the error as its cause. Cancelling the task while `execute()` is still starting the query first waits for the start request to finish, and then cancels the query it started in the same way. If the task is cancelled before `execute()` begins the request, the request is never sent. diff --git a/docs/spark.md b/docs/spark.md index 956a929d5..ed05caa3f 100644 --- a/docs/spark.md +++ b/docs/spark.md @@ -256,8 +256,10 @@ The `cancel()` method sends a [StopCalculationExecution](https://docs.aws.amazon request for the calculation. It does not terminate the session. Athena cancels the calculation on a best-effort basis: -- A running Spark job, such as a DataFrame action, stops within seconds. - The calculation ends in the `CANCELED` state, and the session remains usable for later calculations. +- A running Spark job, such as a DataFrame action, usually stops within seconds. + The calculation then ends in the `CANCELED` state, and the session remains usable for later calculations. +- A request sent right after the calculation starts can occasionally have no effect. + The calculation then runs as if it had not been canceled. - Python code that runs on the driver without a Spark job, such as `time.sleep()`, runs to completion. The calculation ends in the `COMPLETED` state, and the session rejects new calculations until then. - Canceling a calculation that has already finished does not raise an error or change its state. @@ -283,12 +285,14 @@ with conn.cursor() as cursor: With `kill_on_interrupt` enabled, which is the default, a `KeyboardInterrupt` while `execute()` waits for the calculation requests cancellation, waits until the calculation reaches a terminal state, and then propagates. The `state` property returns that terminal state. -If the cancellation request fails, the `KeyboardInterrupt` propagates with the error as its cause. +If the cancellation request or that wait fails, the `KeyboardInterrupt` propagates with the error as its cause, +and the `state` property returns `None`. A `KeyboardInterrupt` while `execute()` is still starting the calculation first waits for the [StartCalculationExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartCalculationExecution.html) request to finish, and then cancels the calculation it started in the same way. The `calculation_id` property returns that calculation's ID. +If `execute()` has not begun the request when the interrupt is handled, the request is never sent and `calculation_id` is `None`. A second `KeyboardInterrupt` during this wait propagates at once without cancelling the calculation. A cancellation request sent right after a calculation starts can occasionally have no effect, so the calculation can still end in the `COMPLETED` state. diff --git a/docs/usage.md b/docs/usage.md index 0638fc489..885ef3e1e 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -507,7 +507,7 @@ With `kill_on_interrupt` enabled, which is the default, a `KeyboardInterrupt` wh requests cancellation, waits until the query reaches a terminal state, and then propagates. Cancellation is a best-effort request, so the query can still end as `SUCCEEDED` or `FAILED`. The `query_id` property keeps the ID of the interrupted query. -If the cancellation request fails, the `KeyboardInterrupt` propagates with the error as its cause. +If the cancellation request or that wait fails, the `KeyboardInterrupt` propagates with the error as its cause. A `KeyboardInterrupt` while `execute()` is still starting the query first waits for the [StartQueryExecution](https://docs.aws.amazon.com/athena/latest/APIReference/API_StartQueryExecution.html)