Skip to content

[feature](lance) Durable Lance index job infrastructure with fence, quota and replay - #67235

Draft
u70b3 wants to merge 3 commits into
apache:branch-4.1from
u70b3:pr3b-lance-index-jobs
Draft

[feature](lance) Durable Lance index job infrastructure with fence, quota and replay#67235
u70b3 wants to merge 3 commits into
apache:branch-4.1from
u70b3:pr3b-lance-index-jobs

Conversation

@u70b3

@u70b3 u70b3 commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

What problem does this PR solve?

Issue Number: #66497

Related PR: #66637 (merged), #67201 (PR3A, open — independent; this PR shares no files with it), #66671 (open — independent)

Problem Summary:

This is the second sub-PR (PR3B) of delivery slice 3 of the v5.1 design (final 4.2 contract, scope confirmed in this review): the durable Lance index job infrastructure — job records, the compact dual-state lifecycle, the same-name fence, three-level unresolved quotas, typed results, and replay semantics — behind a master-owned manager. This PR has no user-visible entry point: no SQL, no admission, no dispatcher, no worker, no enablement gate. It is the persistence and state-machine foundation that PR3C (admission + job SQL) and PR3D (dispatch + fake-worker fault tests) build on.

What this PR adds:

  • The minimal durable job record of Section 7.2 (LanceIndexJob): job identity/creator/revision/bounded timestamps, persisted target identity and same-name fence key material (catalog id, DIRECTORY provider tag, normalized dataset locator, display + normalized index name), mutation intent, admitted dataset version and the ordered schema-contract-v1 representation (Section 4.2), the independent mutation/refresh states, the typed result with bounded sanitized message, dispatch identity (backend id, BE process epoch, immutable invocation id, deadline), possible-live ownership with termination proof, and the FORCE audit fields (populated by PR3E; only replay semantics land here). The record carries no credentials and no unbounded values (Section 4.3/8).
  • The Section 6.1/6.2 dual state machines and the Section 6.3 provider-result classification table as data plus one pure classify function (13 typed result codes × CREATE/REPLACE/DROP × IF-flags × external-advancement), including IF_CONDITION_NOOP only for DROP IF EXISTS + LANCE_ERR_NOT_FOUND. Normalization v1 (Section 4.1) for index names (toLowerCase(Locale.ROOT)) and dataset locators (scheme case, trailing slashes, credential-bearing URL rejection); the fence key and the three-level (table-locator/catalog/global) unresolved-quota counters of Section 5.4.
  • LanceIndexJobManager (Appendix B seam: a master-owned minimal job/fence manager; it deliberately reuses neither the generic scheduling JobManager nor internal IndexChangeJob, neither of which provides external one-shot CAS, no-redispatch, same-name fence, or possible-live semantics). All durable transitions share one write-path shape — validate under the write lock (state legality, revision CAS, callback identity), append one upsert record to the edit log, then apply the same record locally — so master and followers run identical apply logic. Fence and unresolved quota live and die together exactly as Sections 5.4/6.4 require: held by PENDING/RUNNING, by terminal jobs until their required refresh is DONE, and by UNKNOWN until a durable FORCE_RELEASE; a quota or fence rejection precedes any durable write, leaving no job, no fence, and no record.
  • Replay per Section 7.3. replayUpsertJob is a verbatim replace with a monotonic-revision guard and performs no state transformation — a follower tailing a live master must keep a fresh RUNNING record RUNNING. The RUNNING→UNKNOWN transition happens only in the master-election sweep (Env.transferToMaster, after metadata replay and before any master daemon starts, mirroring the insertOverwriteManager.allTaskFail() precedent), which writes UNKNOWN upserts through the same identity-checked channel so followers converge and stale callbacks (revision/invocation/epoch mismatch) are rejected. Refresh RUNNING is downgraded to REQUIRED at the sweep so the idempotent external-table refresh can resume; replay never calls lance-c again.
  • Persistence wiring per Doris convention: one new edit-log op (OP_LANCE_INDEX_JOB_UPSERT = 500), JournalEntity/EditLog dispatch, a new lanceIndexJobManager image module appended to PersistMetaModules.MODULE_NAMES (no FeMetaVersion bump; old images simply never invoke the load method, and Env pre-initializes an empty manager).

Explicitly not in this PR: SQL/admission/IF preflight and job SQL (PR3C, including the Section 9.7 gating configuration — quota limits here are parameters, not Config); BE selection, dispatch, possible-live slot reservation on BEs, and worker invocation (PR3D); the FORCE_RELEASE transition and its auth protocol (PR3E — only the durable fields and the replay row exist); Arrow-schema→contract construction (PR3C admission); job-record retention/GC (follows the bounded-retention policy with PR3E). PR1's SHOW INDEX and PR2's inspection surface are untouched; this branch shares no files with PR3A.

Release note

None (internal infrastructure only; no user-visible behavior change).

Check List (For Author)

  • Test

    • Regression test
    • Unit Test
      • New suites under org.apache.doris.datasource.lance.job (105 cases, all green with checkstyle enabled): normalization v1 (incl. the Turkish-İ corner), locator normalization and rejection forms, the full Section 6.3 classification matrix (independently restated per cell), state-machine legality (UNKNOWN has no outgoing transitions; refresh independence; revision CAS), fence/quota co-release timing, quota three-level boundaries, the Section 7.3 replay matrix (PENDING re-dispatchable once; RUNNING swept to UNKNOWN and never redispatchable; terminal jobs resume only refresh; UNKNOWN rebuilds fence/quota/possible-live; force-released UNKNOWN frees the name), stale-callback rejection, replay idempotence and monotonic revision, corrupt-record tolerance, manager image write/read round-trip with derived-state rebuild, and JournalEntity op-500 round-trip.
      • Scoped regression green (469 cases): org.apache.doris.persist.**, org.apache.doris.journal.**, org.apache.doris.dictionary.**, org.apache.doris.indexpolicy.**, org.apache.doris.job.**, org.apache.doris.datasource.lance.** (cd fe && mvn test -pl fe-common,fe-core -am -DfailIfNoTests=false -Dtest='...', no -Dcheckstyle.skip).
    • Manual test
      • mvn compile -pl fe-common,fe-core -am green with checkstyle (validate phase); the new image module binding resolves at PersistMetaModules static init; the edit-log op code 500 verified unique repo-wide.
  • Behavior changed:

    • No. New code paths are unreachable from any SQL or RPC surface in this PR; existing edit-log ops, image modules, and manager behaviors are unchanged.
  • Does this need documentation?

Check List (For Reviewer who merge this PR)

  • Confirm the release note
  • Confirm test cases
  • Confirm document
  • Add branch pick label

u70b3 added 3 commits August 27, 2026 12:20
Second sub-PR (PR3B) of slice 3 of the Lance index lifecycle design
(apache#66497, v5.1 contract): the durable job model behind the
one-shot mutation lifecycle. No user-visible entry point; admission,
dispatch, and FORCE land in follow-up PRs.

Model pieces (design sections in parentheses):

- LanceIndexJob: the minimal durable job record (7.2) - identity,
  creator, revision, bounded timestamps, persisted target identity and
  same-name fence key material, mutation intent, admitted dataset
  version with the ordered schema-contract-v1 representation (4.2),
  independent mutation/refresh states, typed result with bounded
  sanitized message, dispatch identity (backend id, BE process epoch,
  immutable invocation id, deadline), possible-live ownership with
  termination proof, and the FORCE audit fields (populated by PR3E).
  No credentials, no unbounded values (4.3/8).
- Dual state machines: PENDING -> RUNNING -> COMMITTED|NOT_COMMITTED|
  UNKNOWN (6.1, UNKNOWN terminal with no outgoing transition) and the
  independent NOT_REQUIRED|REQUIRED|RUNNING|DONE|FAILED refresh state
  (6.2).
- LanceIndexJobResultCode: the provider-result classification table
  (6.3) as typed codes plus one pure classify(); IF_CONDITION_NOOP
  only for DROP IF EXISTS + LANCE_ERR_NOT_FOUND.
- Normalization v1 (4.1): index names via toLowerCase(Locale.ROOT);
  dataset locators via trim, lowercased scheme, trailing-slash strip,
  and rejection of credential-bearing or identity-less forms.
- LanceIndexFenceKey: (catalog id, DIRECTORY provider, normalized
  locator, normalized index name); display name is persisted on the
  job, never in the key. toString hides the locator.
…and quota

PR3B part 2: the master-owned job/fence manager (Appendix B seam) plus
edit-log and image wiring. It deliberately reuses neither the generic
scheduling JobManager nor internal IndexChangeJob: the external
one-shot CAS, no-redispatch rule, same-name fence, and possible-live
ownership required by the design are not provided by either.

- LanceIndexJobManager: every durable transition shares one write-path
  shape - validate under the write lock (state legality, revision CAS,
  callback identity), append one upsert record, then apply the same
  record locally - so master and followers run identical apply logic.
  Fence and unresolved quota (table-locator/catalog/global, 5.4) live
  and die together per 6.4: held by PENDING/RUNNING, by terminal jobs
  until their required refresh is DONE, and by UNKNOWN until a durable
  FORCE_RELEASE; rejection precedes any durable write, leaving no job,
  no fence, and no record.
- Replay per 7.3: replayUpsertJob is a verbatim replace with a
  monotonic-revision guard and performs no state transformation, so a
  follower tailing a live master keeps a fresh RUNNING record RUNNING.
  RUNNING without a complete terminal result becomes UNKNOWN only in
  the master-election sweep (Env.transferToMaster, after metadata
  replay and before master daemons start, mirroring the
  insertOverwriteManager.allTaskFail precedent) through the same
  identity-checked channel; refresh RUNNING is downgraded to REQUIRED
  so the idempotent external-table refresh can resume. Replay never
  redispatches and never calls lance-c again.
- Wiring: OP_LANCE_INDEX_JOB_UPSERT = 500 (verified unique),
  JournalEntity/EditLog dispatch, a lanceIndexJobManager image module
  appended to PersistMetaModules (no FeMetaVersion bump; old images
  never invoke the load method and Env pre-initializes an empty
  manager).
PR3B unit tests (105 cases, pure UT, no FE service):

- Normalization v1 incl. the Turkish dotted-I corner; locator forms
  and rejections (userinfo, empty scheme, relative path, no identity).
- Section 6.3 classification matrix independently restated per cell;
  IF_CONDITION_NOOP confined to DROP IF EXISTS + NOT_FOUND.
- State machine legality: UNKNOWN has no outgoing transitions, refresh
  transitions stay independent, revision CAS, blank invocation ids
  rejected at the dispatch boundary.
- Fence/quota co-release timing (immediate on NOT_REQUIRED, on refresh
  DONE, never for FAILED/UNKNOWN), three-level quota boundaries, and
  rebuild equivalence after image load.
- Section 7.3 replay matrix: PENDING re-dispatchable once; RUNNING
  swept to UNKNOWN at master transfer and never redispatchable;
  terminal jobs resume only refresh (REQUIRED and FAILED stay visible
  to the refresh driver); UNKNOWN rebuilds fence/quota/possible-live;
  force-released UNKNOWN frees the name; stale callbacks rejected on
  revision/invocation/epoch mismatch; replay idempotent with a
  monotonic revision guard; identity-less corrupt records tolerated
  without throwing, including follow-up upserts for the same job id.
- Manager image write/read round-trip rebuilds derived fence/quota;
  JournalEntity round-trip covers the new op-500 dispatch;
  over-bounds text fields rejected at construction.
@hello-stephen

Copy link
Copy Markdown
Contributor

Thank you for your contribution to Apache Doris.
Don't know what should be done next? See How to process your PR.

Please clearly describe your PR:

  1. What problem was fixed (it's best to include specific error reporting information). How it was fixed.
  2. Which behaviors were modified. What was the previous behavior, what is it now, why was it modified, and what possible impacts might there be.
  3. What features were added. Why was this function added?
  4. Which code was refactored and why was this part of the code refactored?
  5. Which functions were optimized and what is the difference before and after the optimization?

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.

2 participants