Skip to content

feat(fts): show tokenized queries in analyze plan - #8414

Open
BubbleCal wants to merge 1 commit into
mainfrom
yang/oss-2007-analyze-plan-tokenized-query
Open

feat(fts): show tokenized queries in analyze plan#8414
BubbleCal wants to merge 1 commit into
mainfrom
yang/oss-2007-analyze-plan-tokenized-query

Conversation

@BubbleCal

Copy link
Copy Markdown
Contributor

What is the new feature?

analyze_plan now shows both the original FTS query and its execution-time tokenized representation, including token text and normalized positions.

Why do we need this feature?

Users need to see how the configured tokenizer transforms a query when debugging lowercasing, stemming, stop-word removal, phrase positions, and other analyzer behavior.

How does it work?

  • Capture the tokens produced by the actual execution tokenizer in a shared runtime snapshot.
  • Append tokenized_query to indexed and flat Match/Phrase nodes and posting-backed compound query leaves.
  • Preserve the snapshot when DataFusion replaces plan children.
  • Keep explain_plan unchanged because it does not execute the tokenizer.

Validation

  • cargo test -p lance test_analyze_plan_shows --lib: 3 passed
  • Adjacent parts-searched metric tests: 2 passed
  • uv run make lint from python/: passed
  • cargo fmt --all -- --check: passed
  • cargo clippy --all --tests --benches -- -D warnings: passed
  • git diff main...HEAD --check: passed

Limitations

Plans that resolve directly to EmptyExec do not execute an FTS tokenizer node, so they have no tokenization snapshot to display.

Linear: OSS-2007

@github-actions github-actions Bot added A-python Python bindings enhancement New feature or request labels Aug 7, 2026

@lance-gatekeeper lance-gatekeeper Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Gate recommendation: approve.

The change captures analyzer output at the execution boundary where tokenizer selection is authoritative, preserves it through plan replacement, and leaves non-executing explain plans unchanged. This is preferable to eager planning-time tokenization, which could observe the wrong tokenizer and blur the explain/analyze contract.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

A-python Python bindings enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant