SOLR-13309: Add IntRangeField for Lucenes IntRange

[gerlowskija]

https://issues.apache.org/jira/browse/SOLR-13309

Description

Lucene offers a variety of 'Range' field types, where the value stored in the field is itself a range (e.g. [1 TO 5]). Lucene then allows efficient search on these using its RangeFieldQuery.

Solr offers no similar functionality, despite having access to these underlying Lucene capabilities. We should expose start exposing these, starting with what's probably the most popular option, ints.

Solution

This commit adds a new field type, IntRangeField, that can be used to hold singular or multi-dimensional (up to 4) ranges of integers.

Field values are represented using brackets and the "TO" operator, with commas used to delimit dimensions (when a particular field is defined as having more than 1 dimension), e.g.

• [-1 TO 5]
• [1,2 TO 5,10]
• [1 TO 1]

IntRangeField does not support docValues or uninversion, meaning it's primarily only used for querying. The field can be stored and returned in search-results. Searches on these range-fields rely on a new QParserPlugin implementation, {!numericRange}, which supports "intersects", "crosses", "within", and "contains" semantics via a "criteria" local param. e.g.

• {!numericRange field=price_range criteria=within}[1 TO 5] Matches docs whose 'price_range' field falls fully within [1 TO 5]. A doc with [2 TO 3] would match; [3 TO 6] or [8 TO 10] would not.
• {!numericRange field=price_range criteria=crosses}[1,10 TO 5,20] Matches docs whose 'price_range' field is partially but not fully contained within [1,10 TO 5,20]. A doc with [2,11 TO 6,21] would match, but [3,11 TO 5,19] would not.

Tests

New test classes: IntRangeFieldTest and IntRangeQParserPluginTest.

Checklist

Please review the following and check all that apply:

• I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
• I have created a Jira issue and added the issue ID to my pull request title.
• I have given Solr maintainers access to contribute to my PR branch. (optional but recommended, not available for branches on forks living under an organisation)
• I have developed this patch against the main branch.
• I have run ./gradlew check.
• I have added tests for my changes.
• I have added documentation for the Reference Guide
• I have added a changelog entry for my change

[gerlowskija]

Still a lot of cleanup to be done here, but I thought this was ready to publish as a "draft" so folks can provide feedback on the general approach.

[gerlowskija]

So, I wanted to highlight some design choices for potential reviewers - these are decisions I made in putting this together that 100% need a second set of eyes:

1. Currently I've made no effort to integrate this new field type into lucene, dismax, or edismax query parsers. In other words, users must use the new {!numericRange} QParser for any queries against these fields.
2. Overall review of the naming around {!numericRange}. Is "numericRange" clear enough for users? Is "criteria" a decent name for indicating the match-criteria strategy, or do folks have other ideas there?
3. Currently, the {!numericRange} QParser treats "field" and "criteria" as required - users must specify them explicitly on each request. If we wanted, we could make a certain 'criteria' value the default to simplify invocation for some users. But I'm not sure what the most common 'criteria' would be in practice, so I've held off on this.
4. Users can achieve inclusive/exclusive semantics on queries by incrementing/decrementing the int vals in their queries. But if we could expose explicit parameters (e.g. lowerExclusive=true) to do this automatically if we think it's worth taking on a bit of extra complexity to simplify this for users.
5. I've put all the new classes in a 'numericrange' sub-package. This is a bit unnecessary currently, but I hope in follow-on PRs to add field types and query support for float, long, etc. So I suspect we'll end up with enough classes in the medium term to merit this being its own package.

Still TODO

• changelog
• performance tests

[gerlowskija]

I've made no effort to integrate this new field type into lucene, dismax, or edismax query parsers.

I ended up reversing course on this. The field can now be queried using the Lucene, etc. QParser. Queries sent in this way will assume "contains" semantics (i.e. match documents that have a field value that entirely contains the query-range). As a bit of syntax-sugar, users may specify only a single bound or point as a shorthand for [X TO X]. In other words: price_range:5 is equivalent to {!numericRange criteria=contains field=price_range}[5 TO 5]

I'm pretty uncertain about all the naming and other syntax here, so I've marked IntRangeQParser and the underlying field type as 'experimental' for now. The underlying implementation is unlikely to change, but IMO it's very likely we'll be tweaking the syntax a bit over time....