Can someone confirm that this is technically accurate (I've added it to the javadoc for NumericField):

You may add the same field name as a NumericField to the same document more than once. Range querying and filtering will be the logical OR of all values, and sorting will sort according to the first value added.

This is correct (first part), you can add a field more than once and it really works (there is a test about that: TestMultiValuedNumericRangeQuery). The results are the same like with a normal range query (so the trie terms do not interfere between each other). See SOLR-1322

I think your sentence is a little bit complicated. It would hit all documents in the range, where at least one of the values of a multi-valued doc is in the range.

About the second one: Sorting is not different from other numeric multi-value fields (in contrast to StringIndex where only one value/doc is allowed). The univerter assigns a value to each document. As it overrides values previously assigned to the document when iterating over all terms in the field, the last term would be the one saved in the FieldCache. So you would sort against the largest value per doc (because the smaller values are overridden by the larger ones in the field cache).

About the second one: Sorting is not different from other numeric multi-value fields (in contrast to StringIndex where only one value/doc is allowed). The univerter assigns a value to each document. As it overrides values previously assigned to the document when iterating over all terms in the field, the last term would be the one saved in the FieldCache. So you would sort against the largest value per doc (because the smaller values are overridden by the larger ones in the field cache).

Ahh right.

I'm confused on why it's the "largest" value? EG if I add 4, 17, 10 as a NumericField "x" on my doc, when I then try to sort, wouldn't 10 "win" since it was added last to the document?

I'm confused on why it's the "largest" value? EG if I add 4, 17, 10 as a NumericField "x" on my doc, when I then try to sort, wouldn't 10 "win" since it was added last to the document?

Because of the uninverter. It iterates over all terms, starting from the lowest one in the field. When he comes to term 4, it would add it to the field cache at the document's position. The same with 10 and then 17. Because the TermEnum lists 17 at last, it would win:

long[] retArray = null;
TermDocs termDocs = reader.termDocs();
TermEnum termEnum = reader.terms (new Term(field));
try {
  do {
    Term term = termEnum.term();
    if (term==null || term.field() != field) break;
    long termval = parser.parseLong(term.text());
    if (retArray == null) // late init
      retArray = new long[reader.maxDoc()];
    termDocs.seek (termEnum);
    while (termDocs.next()) {
      retArray[termDocs.doc()] = termval;
    }
  } while (termEnum.next());
} catch (StopFillCacheException stop) {
} finally {
  termDocs.close();
  termEnum.close();
}
if (retArray == null) // no values
  retArray = new long[reader.maxDoc()];

Because of the uninverter.

Ahh right!

I think it's best to document that the effect of sorting is undefined/not guaranteed, but filtering/searching by range is defined.

Thank you at all for looking after the documentation! A native speaker is always better than my "frankish" English (as my colleague call it).

Thank you at all for looking after the documentation! A native speaker is always better than my "frankish" English (as my colleague call it).

No problem! This is how open source works It's great.

Only javadoc fixes, mostly for Numeric* but also some small fixes to a few other classes.

Will we mark it as experimental or not? In some classes you remove the experimental warning, in others not. I will review it more detailed later!

By the way, I also reviewd the LIA chapter and have also seen the reference to DateTools (will send you my updates soon). ate to a String with a special date resolution and then convertin back to numeric is somehow ineffective. When indexing only hour resolution, I would take Date.getTime() / 3600L / 1000L.

Maybe you could copy some of your explanations also to NumericTokenStream, e.g. the example. In the original, both classes had similar introduction texts.

Will we mark it as experimental or not?

Yes, I think we should keep the experimental warning. I didn't mean to remove any – I'll make sure they're all still there.

By the way, I also reviewd the LIA chapter and have also seen the reference to DateTools (will send you my updates soon)

Excellent, thanks!

ate to a String with a special date resolution and then convertin back to numeric is somehow ineffective. When indexing only hour resolution, I would take Date.getTime() / 3600L / 1000L.

True, and that'll work for DAY as well, but not for MONTH / YEAR resolution.

Maybe you could copy some of your explanations also to NumericTokenStream, e.g. the example. In the original, both classes had similar introduction texts.

OK I'll update NumericTokenStream too.

New rev.

As far as I can tell, I didn't lose any of the experimental warnings – Uwe where did you see that?

I worked on NumericTokenStream's javadocs too.

Finally, I removed reference to DateTools entirely and suggested either quantizing by dividing getTime()'s returned result, or, using Date's getters (getYear, getMonth, etc.) to construct a numeric value.

As far as I can tell, I didn't lose any of the experimental warnings - Uwe where did you see that?

My fault. I did not see that you moved the warning to the top in NumericRangeQuery.

Looks good.

One small thing (I found this also in the LIA chapter):
"Trie" is the whole "prefix tree". So "trie" means the whole list of different precision terms for one numeric value. You have this explanation which suggests one trie is one term:

+ * <p>Within lucene, each numeric value is indexed as
+ * multiple encoded terms representing larger and larger
+ * pre-defined brackets called <em>trie</em>s.  The step
+ * size between each successive trie is called the
+ * <code>precisionStep</code> in this API.  Smaller

There should also be the explanation that the precStep is in "bits".

"Trie" is the whole "prefix tree".

OK – I tweaked NumericField to fix that. I'll fix LIA2's manuscript too... thanks!

State that precSteps is "bits", and trie is the entire data structure.

I think this is fine now! Thanks.

OK thanks Uwe!

Hi Mike, I made some small improvements in formatting and also added a relation between precisionStep and "brackets" which one would not understand (what is the relation between terms bracket and precisionStep). Also the term bracket does not appear anywhere else. So I added, that the larger brackets are simply lower-precision representations of the original value. I also added a link to NumericUtils which get lost, that describes the format (in the advanced section of NumericField).

I committed this, revision: 809284

The new changes look good – thanks Uwe!

Oh I thought you were still sleeping... Good morning!

Good morning!

Some small updates after discussion on java-user.

Some notes about cardinality and precision step.

Looks good Uwe!

Committed revision: 815195