[IGNITE-23430] Sql. Provide an ability to cancel query before first page ready

• Type: Improvement
• Status: Resolved
• Priority: Major
• Resolution: Fixed
• Component/s: sql
• Labels: ignite-3
• Epic Link: Kill Queries
• Ignite Flags: Docs Required, Release Notes Required
• Assignee: Maksim Zhuravkov
• Reporter: Konstantin Orlov
• Created: 15/Oct/24 06:08
• Updated: 1 week ago 11:23
• Resolved: 11/Nov/24 06:23

Description

Currently, the only possible way to cancel a query prematurely is by invoking cancel() on a ResultSet object. The problem is the result set is returned only when first page is ready. For statements like DML and DDL this means that result set will be returned only when operation is complete.

Proposed solution is to introduce new pair of entities to public API:

/**
 * A handle which may be used to request the cancellation of execution.
 */
public interface CancelHandle {
    /** A factory method to create a handle. */
    static CancelHandle create() {}

    /**
     * Abruptly terminates an execution of an associated process.
     *
     * <p>Control flow will return after the process has been terminated and the resources associated with that process have been freed.
     */
    void cancel();

    /**
     * Abruptly terminates an execution of a associated process.
     *
     * @return A future that will be completed after the process has been terminated and the resources associated with that process have
     *         been freed.
     */
    CompletableFuture<Void> cancelAsync();

    /**
     * Flag indicating whether cancellation was requested or not.
     *
     * <p>This method will return true even if cancellation has not been completed yet.
     *
     * @return {@code true} when cancellation was requested.
     */
    boolean isCancelled();

    /**
     * Issue a token associated with this handle.
     * 
     * <p>Token is reusable, meaning the same token may be used to link several executions into a single cancellable.
     */
    CancellationToken token();
}

public interface CancellationToken { }

Also, a new group of execute<*> methods accepting optional CancellationToken parameter must be introduced to sql facade:

public interface IgniteSql {
    <...>
    
    ResultSet<SqlRow> execute(
        @Nullable Transaction transaction,
        @Nullable CancellationToken cancellationToken,
        String query,
        @Nullable Object... arguments
    );
    
    <...>
}

When user need a better control over query lifecycle, they should create handle and propagate token to the execution:

IgniteSql sql = <acquire sql api>;

// create cancellation handle
CancelHandle handle = CancelHandle.create();

// propagate cancellation token to an execution
sql.executeAsync(null, handle.token(), "<query text>");

// propagate token from the same handle to more executions, if needed
sql.executeAsync(null, handle.token(), "<query text>");

// cancel everything at once
handle.cancel();

Definition of Done: new entities are introduced to public API and integrated with single statement execution flow from embedded API.

Issue Links

• Blocked: IGNITE-23646 Java thin 3.0: Client side support for CancelHandle
• blocks: IGNITE-23439 Client. Implement query cancellation in C++ client
• blocks: IGNITE-23492 Implement cancelation in ODBC
• blocks: IGNITE-23441 Cancellation of script execution
• blocks: IGNITE-23464 Implement cancellation in JDBC
• blocks: IGNITE-23487 Support cancellation tokens in IgniteCompute
• links to: GitHub Pull Request #4615