apache / apache/lucene

Document DocValuesSkipper

Open
#15,996 7 comments 0 reactions 0 assignees View on GitHub
type:documentation
Dominant language
Java
Stars
3.6k
Forks
1.4k
Avg merge
2d 11h
Merged PRs (30d)
88

Description

### Description

This class exposes a bunch of new capabilities, but they aren't adequately documented. In order to make use of the skipper, you need a mental model of the skip list data structure and the implicit assumptions that are being made by this class. Some things I found out that weren't clear at first:

1. Level 0 is the "top" level with the largest blocks; higher numbered levels represent successively nested sub-blocks.
2. The skipper only really works with fields that are primary index sort keys (I think?). What happens if you try to use the skipper with non-sorted fields? Can you still read block level statistics? Maybe - but how does skipping function in that case?
3. advance(docId) is forward-only, but what are the expectations around `advance(minValue, maxValue)`? Is it possible to reverse using this API?

I can try to improve the docs, but my understanding is only superficial, and I don't want to add to the confusion, so for now I'm just asking questions :)

Contributor guide

Open the contributing guide

Research direction

Start with the DocValuesSkipper class and its existing documentation. Trace the skip-list levels, field sort assumptions, and advance(docId)/advance(minValue, maxValue) behavior to establish the requested mental model. Done means the class documents these points and explains behavior for sorted and non-sorted fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
search
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.