SOLR-13764: Introduce IntervalsQParserPlugin by mkhludnev · Pull Request #4582 · apache/solr

mkhludnev · 2026-07-01T12:31:58Z

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

This pull request adds support for the Intervals Query Parser in Solr, enabling users to construct Lucene interval queries using a JSON-based DSL. The changes include the core implementation, integration with the standard query parser plugins, documentation updates, and new tests to ensure distributed and JSON query support.

Intervals Query Parser Implementation and Integration:

Added the IntervalsQParserPlugin to the set of standard query parser plugins in QParserPlugin.java, allowing interval queries to be parsed and executed.
Updated RequestUtil.java to recognize and correctly handle the new json_queries key in JSON requests, ensuring it is passed through for use by query parsers.

The syntax proposed

q={!intervals df=title}$myQuery&json={json_queries:{myQuery:{match:{query:quick}}, q2:{},..}}

this QP refers to json.json_queries. I propose to introduce it since I expect more usages for pure json parsing.

The considerable alternatives are

?q={!intervals json_query=q1 df=subject}&json={json_queries:{q1:{match:{query:quick}}, q2:{},..}}
?q={!intervals param_ref=q1 df=subject}&json={param:{q1:{match:{query:quick}}, q2:{},..}}

or even param_ref=$q1 like here

Propose yours syntax in comments.

Testing and Validation:

Introduced a new test class, DistributedQParserTest.java, which verifies distributed search support for the new intervals query parser alongside existing parsers.
Expanded TestJsonRequest.java to test the handling and preservation of the json_queries key in JSON requests.
Especially interesting to see a test case proving an advantage of intervals over spans test

Documentation:

Added a new changelog entry describing the addition of the Intervals Query Parser.
Updated the Solr Reference Guide to document the new query parser and linked its dedicated documentation page in the navigation and parser overview.

Checklist

Please review the following and check all that apply:

[v] I have reviewed the guidelines for How to Contribute and my code conforms to the standards described there to the best of my ability.
[v] I have created a Jira issue and added the issue ID to my pull request title.
[v] 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)
[v] I have developed this patch against the main branch.
[v] I have run ./gradlew check.
[v] I have added tests for my changes.
[v] I have added documentation for the Reference Guide
[v] I have added a changelog entry for my change

…ns MatchNoDocsQuery

…tend, unordered_no_overlaps, not_within, within, at_least, no_intervals

…ry formats

…13764-intervals-query-parser.yml

Updated the section title and removed outdated content regarding query formats.

Updated the description to reference JSON DSL documentation.

…ucene, dismax, edismax parsers

…ns-job fix: merge split QueryRequest constructor calls to satisfy Spotless

Copilot

Pull request overview

Adds a new built-in intervals query parser to Solr that constructs Lucene IntervalQuery instances from a JSON-based DSL carried in the request body (under json_queries), with accompanying ref-guide documentation and tests (standalone + SolrCloud + JSON request handling).

Changes:

Introduces IntervalsQParserPlugin and registers it as a standard query parser plugin.
Extends JSON request processing to accept/pass-through a new json_queries top-level key.
Adds ref-guide documentation and new tests covering standalone parsing, distributed execution, and JSON preservation.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
solr/solr-ref-guide/modules/query-guide/querying-nav.adoc	Adds navigation entry for the new Intervals query parser page.
solr/solr-ref-guide/modules/query-guide/pages/other-parsers.adoc	Adds a short overview section for the Intervals query parser.
solr/solr-ref-guide/modules/query-guide/pages/intervals-query-parser.adoc	New detailed documentation page for the Intervals query parser DSL.
solr/core/src/test/org/apache/solr/search/TestIntervalsQParserPlugin.java	New unit tests for interval rule parsing/execution.
solr/core/src/test/org/apache/solr/search/json/TestJsonRequest.java	Adds coverage ensuring `json_queries` is preserved in parsed JSON.
solr/core/src/test/org/apache/solr/search/DistributedQParserTest.java	New SolrCloud test ensuring `intervals` works in distributed search.
solr/core/src/java/org/apache/solr/search/QParserPlugin.java	Registers `intervals` as a standard plugin.
solr/core/src/java/org/apache/solr/search/IntervalsQParserPlugin.java	Core implementation of the JSON-to-Intervals DSL parser.
solr/core/src/java/org/apache/solr/request/json/RequestUtil.java	Allows `json_queries` as a recognized JSON request top-level key.
changelog/unreleased/SOLR-13764-intervals-query-parser.yml	Adds an unreleased changelog entry for the feature.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+        Analyzer analyzer = resolveAnalyzer(params, field, "wildcard");
+        String normalizedPattern = normalizeMultiTerm(field, pattern, analyzer);


+        Analyzer analyzer = resolveAnalyzer(params, field, "fuzzy");
+        String normalizedTerm = normalizeMultiTerm(field, term, analyzer);
+
+        String fuzziness = getOptionalString(params, "fuzziness", "fuzzy");
+        int maxEdits = resolveFuzziness(fuzziness, normalizedTerm);
+        int prefixLength = getInt(params, "prefix_length", 0, "fuzzy");
+        boolean transpositions = getBoolean(params, "transpositions", true, "fuzzy");
+


+        Object termsObj = params.get("terms");
+        Object intervalsObj = params.get("intervals");
+        if (termsObj == null && intervalsObj == null) {
+          throw new SolrException(
+              SolrException.ErrorCode.BAD_REQUEST,
+              "Rule 'phrase' requires either 'terms' (string array) or 'intervals' (rule array)");
+        }


+        int maxExpansions =
+            getInt(params, "max_expansions", Intervals.DEFAULT_MAX_EXPANSIONS, "regexp");
+        IntervalsSource source = Intervals.regexp(new BytesRef(pattern), maxExpansions);


+        int maxExpansions =
+            getInt(params, "max_expansions", Intervals.DEFAULT_MAX_EXPANSIONS, "range");
+        BytesRef lowerTerm = lowerTermStr == null ? null : new BytesRef(lowerTermStr);
+        BytesRef upperTerm = upperTermStr == null ? null : new BytesRef(upperTermStr);
+        return Intervals.range(lowerTerm, upperTerm, includeLower, includeUpper, maxExpansions);


+
+The Intervals Query Parser (`IntervalsQParserPlugin`) builds Lucene interval queries from a xref:json-request-api.adoc[JSON DSL] description.
+Interval queries allow you to express positional constraints such as "these terms must appear within N positions of each other" or "this phrase must appear before that one".
+See the https://lucene.apache.org/core/10_4_0/queries/org/apache/lucene/queries/intervals/package-summary.html[Lucene Intervals package documentation] for a detailed description of the underlying interval machinery.


+|`query`
+|Yes
+|—
+|The text to analyse and match.


+        String analyzerName = getOptionalString(params, "analyzer", ruleName);
+        if (analyzerName == null) {
+          return req.getSchema().getQueryAnalyzer();
+        }


+        } else if ("json_queries".equals(key)) {
+          // passed through as a parsed object for use by SearchComponent.prepare() at subordinate
+          // nodes; not processed here
+          continue;


Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

multiterm analyzer and QueryEqualityTest

hiSandog · 2026-07-02T02:47:31Z

The JSON DSL and distributed-query pass-through are substantial additions. One edge case worth testing explicitly is validation behavior when json_queries contains multiple named queries and a subordinate node receives a request with only the selected json_query local param. The new RequestUtil exemption for json_queries is important, so a distributed test that uses two named interval queries and selects one would guard against accidental request-param flattening or loss during shard forwarding.

dsmiley

Glad to see Solr finally having a native intervals query parser?

Not sure I'm glad to see it require JSON... but I sympathize. It'd be nice if it could support QParser parsed Strings -> Query and then convert Query to Interval. Could come later.

dsmiley · 2026-07-02T14:15:46Z

+ * Distributed search tests for the standard query parsers: {@code lucene}, {@code dismax}, {@code
+ * edismax}, and {@code intervals}.
+ */
+public class DistributedQParserTest extends SolrCloudTestCase {


Why have this... shouldn't this be only for intervals?

And if the intent is testing distributed... well we have a whole test framework for that which is quite good: BaseDistributedSearchTestCase. Doesn't even require SolrCloud!

afiak SolrCloudTestCase is rather faster and convenient. It's a little bit redundant for local-only QP, but there's a https://github.com/apache/solr/pull/4582#issuecomment-4861727946 regarding transferring new JSON request entries. I've decided to double check.
We cad drop it if you wish.

dsmiley · 2026-07-02T14:33:47Z

+
+[source,text]
+----
+q={!intervals json_query=myQuery df=title}


This looks abnormal... a normal query parser parses v. If v needs to refer to something else that's a string, it'd just be $paramName but I see here there's an attempt to retain the JSON structure, not using a string. If the paramName itself contains "json", maybe we can enhance Solr to reognize that to pass it as parsed JSON? This would mean the referenced json in question would be apart from json=. I wonder if there's precedent in Solr for this. I confess I don't use the Json query stuff regularly so I'm less familiar.

Just brainstorming a bit here, that's all.

Pardon, just changed it to

q={!intervals df=title}$myQuery & json={ "json_queries": { "myQuery": { "match": { "query": "apache solr" } } } }

Also, we might name parser as jintervals or json_intervals to give a clue where to look at.

dsmiley · 2026-07-02T14:40:24Z

 *** xref:json-combined-query-dsl.adoc[]
 ** xref:searching-nested-documents.adoc[]
 ** xref:block-join-query-parser.adoc[]
+** xref:intervals-query-parser.adoc[]


This is placed illogically, shoved between two join query parser pages

moved

** xref:other-parsers.adoc[] *** xref:intervals-query-parser.adoc[]

does it make sense ?

dsmiley · 2026-07-02T14:43:49Z

+      public Query parse() {
+        String jsonQueryName = localParams.get(JSON_QUERY_PARAM);
+        if (jsonQueryName == null) {
+          return new MatchNoDocsQuery("No " + JSON_QUERY_PARAM + " parameter specified");


sounds more like user error to me

right. now it's more strict

dsmiley · 2026-07-02T14:53:08Z

+      private Analyzer resolveAnalyzer(Map<String, Object> params, String field, String ruleName) {
+        String analyzerName = getOptionalString(params, "analyzer", ruleName);
+        if (analyzerName == null) {
+          return req.getSchema().getFieldTypeNoEx(field).getQueryAnalyzer();


Why call getFieldTypeNoEx -- wouldn't we want to throw if not found?

dsmiley · 2026-07-02T14:53:42Z

+        String analyzerName = getOptionalString(params, "analyzer", ruleName);
+        FieldType fieldType =
+            analyzerName == null
+                ? req.getSchema().getFieldTypeNoEx(field)


same -- why getFieldTypeNoEx

dsmiley · 2026-07-02T15:00:34Z

+        return source;
+      }
+
+      private IntervalsSource parseWildcardRule(Map<String, Object> params, String topField) {


here and everywhere, "topField" is passed. Not sure what "top" means. Anyway, it would be more typed to use SchemaField. From the SchemaField, you can resolve the field type easily. Strings are essentially typeless and can lead to confusion/bugs of wrong parameters. And use of SchemaField could avoid repeated type lookups.

topFiled - means the field we build itervals against, until we explicit override it. Exactly the same we have with spans "{!xmlparser df=v_ws}" ok. it's better for name it df. Thanks for typing suggestion. I try to apply it.

extract JSON_QUERIES_KEY constant and update documentation for new syntax

use typed SchemaField

ercsonusharma · 2026-07-03T02:19:59Z

+        "intervals qparser should support all_of with nested any_of via df local param",
+        req(
+            "q",
+            "{!intervals df=title_t}$second_query",


I see the proposed query request structure as combination of Standard query and JSON query syntax. It could even work if the q parameter were moved into the json request as the query field, either using the local-params string format or the expanded form shown in this example from documentation. Since this is intended for use with the JSON syntax, it would be more consistent and convenient IMHO.

We could also use json query string for readability purpose across the tests.

Copilot AI and others added 30 commits June 30, 2026 21:01

Introduce json_queries key in JSON DSL, pass-through to req.getJSON()

3a52030

Introduce IntervalsQParserPlugin ({!intervals json_query=...}), retur…

d13108e

…ns MatchNoDocsQuery

Improve TestIntervalsQParserPlugin: add json_queries pass-through test

de1cf82

Implement IntervalsQParserPlugin term interval query from JSON DSL

5e892d5

Implement OpenSearch-style intervals JSON rule parser

643c95e

Fix intervals DSL parser warnings and finalize validation

a402594

Clarify fuzzy expansion constant in intervals parser

e0841a3

Add interval rule support: term, phrase, regexp, range, max_width, ex…

c76d287

…tend, unordered_no_overlaps, not_within, within, at_least, no_intervals

Add Intervals Query Parser documentation page and references

1d9f1e8

Fix spelling: analyse -> analyze in intervals-query-parser.adoc

363eb9e

Add SOLR-13764 changelog fragment

e2047c3

fix changelog

655b511

Support df local/query param as field for IntervalsQParser; update tests

53c8730

Update intervals-query-parser.adoc to document both df and legacy que…

d42e02c

…ry formats

Remove legacy format support from IntervalsQParserPlugin

81b3464

Rename SOLR-13764-intervals-query-parser-reference-guide.yml to SOLR-…

92ec988

…13764-intervals-query-parser.yml

Change type to 'added' for intervals query parser

73e50a9

Revise intervals query parser documentation

a45e9f4

Updated the section title and removed outdated content regarding query formats.

Add Lucene intervals package link to intervals-query-parser.adoc

b9b9846

Fix spotless formatting in TestIntervalsQParserPlugin

4a7e58f

Fix the guide

168ff13

Change source format from json to text in intervals query

d644ea9

Add intervals vs xmlparser nested query comparison test

a9a1007

Clarify JSON DSL reference in intervals query parser

6d7d239

Updated the description to reference JSON DSL documentation.

Fix typo in author URL field

5755f59

Fix tidy and checkSiteLinks CI failures

5f29a8f

Add DistributedQParserTest: cloud-based distributed search test for l…

003d263

…ucene, dismax, edismax parsers

Add testIntervalsQParser to DistributedQParserTest

f8652de

fix: reformat DistributedQParserTest.java per spotless rules

88e4c3b

Merge pull request #3 from mkhludnev/copilot/fix-failing-github-actio…

b7e85da

…ns-job fix: merge split QueryRequest constructor calls to satisfy Spotless

Fix Spotless formatting violation in DistributedQParserTest.java

223440d

mkhludnev requested a review from Copilot July 1, 2026 12:32

github-actions Bot added documentation Improvements or additions to documentation tests cat:search labels Jul 1, 2026

mkhludnev requested review from dsmiley and epugh July 1, 2026 12:32

Copilot started reviewing on behalf of mkhludnev July 1, 2026 12:32 View session

mkhludnev requested a review from gerlowskija July 1, 2026 12:32

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Potential fix for pull request finding

11ccd1e

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

mkhludnev requested a review from Copilot July 1, 2026 13:18

Copilot started reviewing on behalf of mkhludnev July 1, 2026 13:19 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

mkhludnev and others added 4 commits July 1, 2026 16:32

Apply suggestions from code review

ce87c95

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

multiterm analyzer and QueryEqualityTest

6f2f3ce

Merge pull request #4 from mkhludnev/add-json-queries-key

002e8a4

multiterm analyzer and QueryEqualityTest

fix tests

a61b90f

mkhludnev added 4 commits July 2, 2026 10:52

review

2f3141b

Delete solr/.vscode/settings.json

da96d7c

fix test compile

50130b5

check prefix len

abde6b2

dsmiley reviewed Jul 2, 2026

View reviewed changes

mkhludnev added 2 commits July 3, 2026 00:27

change syntax to {!intervals df=title}$foobar

e52214d

extract JSON_QUERIES_KEY constant and update documentation for new syntax

strict field check

dde6a64

use typed SchemaField

ercsonusharma reviewed Jul 3, 2026

View reviewed changes

		Analyzer analyzer = resolveAnalyzer(params, field, "wildcard");
		String normalizedPattern = normalizeMultiTerm(field, pattern, analyzer);

Uh oh!

Conversation

mkhludnev commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hiSandog commented Jul 2, 2026

Uh oh!

dsmiley left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ercsonusharma Jul 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

mkhludnev commented Jul 1, 2026 •

edited

Loading

ercsonusharma Jul 3, 2026 •

edited

Loading