Skip to content

[FEATURE] Add PPL asynchronous query lifecycle core - #10

Open
penghuo wants to merge 12 commits into
mainfrom
feat/asyncquery-core
Open

penghuo wants to merge 12 commits into
mainfrom
feat/asyncquery-core

Conversation

@penghuo

@penghuo penghuo commented Sep 24, 2026 •

Copy link
Copy Markdown
Owner

Description

This PR extracts the execution contract and lifecycle core from #7 as the first reviewable implementation slice of opensearch-project#5765. It does not register REST routes or expose the asynchronous API. Existing synchronous PPL behavior remains unchanged.

The execution module exposes one lifecycle-facing contract:

public interface AsyncQueryExecution extends AutoCloseable {
    Optional<QueryResponse> currentResult();
    CompletionStage<Void> completion();
    void close();
}

DefaultAsyncQueryExecution adapts the existing callback execution and publishes only the final result. A successful result is visible through currentResult() before completion() completes normally.

The lifecycle module adds:

  • PPLAsyncQueryJob: synchronized state machine for one query.
  • PPLAsyncQueryService: registry, timeout race, retention, capacity, task ownership, cancellation, expiration, and cleanup.
  • PPLAsyncQueryJobId: opaque owner-routable identifier.
  • PPLAsyncQueryUser: retained-job owner identity.
  • Async duration and capacity settings.
flowchart LR
    S[PPLAsyncQueryService] --> J[PPLAsyncQueryJob]
    S --> E[AsyncQueryExecution]
    J -->|transition| S
    E -->|completion| S
    S -->|currentResult| E
    S --> T[TaskManager]
Loading

PPLAsyncQueryJob mutates only job-owned state while synchronized. It returns immutable transitions to the service, which performs task cancellation, registry updates, capacity accounting, listener notification, result materialization, and resource cleanup outside the job lock.

PPLQueryRequest changes, async field parsing and defaults, REST actions, owner-node transport routing, response formatting, FGAC integration tests, endpoint documentation, and plugin registration remain in the follow-up public API PR.

Validation

  • Contract and final-result ordering tests.
  • Job lifecycle, timeout race, lease, capacity, cancellation, cleanup, and concurrency tests.
  • Identity and job-ID tests.
  • Settings validation tests.
  • Spotless checks.

Related Issues

Check List

  • New functionality includes testing.
  • New public interfaces include Javadoc.
  • Commits are signed per the DCO using --signoff.
  • Public API documentation will be added in the follow-up PR.

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

@penghuo
penghuo requested a review from dai-chen as a code owner September 24, 2026 19:10
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
Signed-off-by: Peng Huo <penghuo@gmail.com>
@penghuo
penghuo force-pushed the feat/asyncquery-core branch from 772e356 to 7abe947 Compare September 24, 2026 22:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant