apache / apache/lucene

XXXDocValuesField javadocs are confusing about storing [LUCENE-4331]

Open
#5,398 1 comment 0 reactions 0 assignees View on GitHub
legacy-jira-priority:Major type:bug
Dominant language
Java
Stars
3.6k
Forks
1.4k
Avg merge
2d 11h
Merged PRs (30d)
88

Description

These all say:

> If you also need to store the value, you should add a
> separate {`@link` StoredField} instance\.

This is a little awkward. I can see how it makes sense in the (expert) case where you keep the DVs on disk, and you somehow need somethings as a DV for fast access, but also in summary results (so you dont seek to stored fields for the doc, and also to each DV field).

But I'm not sure the current wording makes this less confusing: it would be nice to elaborate on this specific case, but in general if someone has dv fields loaded up with the default IR.docValues impl (which is a cached Source right?), then putting this crap in the stored fields does no good.

---
Migrated from [LUCENE-4331](https://issues.apache.org/jira/browse/LUCENE-4331) by Robert Muir (@rmuir)

Contributor guide

Open the contributing guide

Research direction

Inspect the javadocs for the XXXDocValuesField classes and compare their guidance about adding StoredField instances with the documented doc-values behavior. Clarify the wording around when storing a separate value is useful, then verify that the affected javadocs consistently explain the distinction.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.