diff --git a/changelog/unreleased/SOLR-13764-intervals-query-parser.yml b/changelog/unreleased/SOLR-13764-intervals-query-parser.yml new file mode 100644 index 000000000000..edc9477856fa --- /dev/null +++ b/changelog/unreleased/SOLR-13764-intervals-query-parser.yml @@ -0,0 +1,10 @@ +# See https://github.com/apache/solr/blob/main/dev-docs/changelog.adoc +title: Add Intervals Query Parser +type: added +authors: + - name: Mikhail Khludnev + nick: mkhludnev + url: https://home.apache.org/phonebook.html?uid=mkhl +links: + - name: SOLR-13764 + url: https://issues.apache.org/jira/browse/SOLR-13764 diff --git a/solr/.gitignore b/solr/.gitignore index 8d643687405e..71c14a078728 100644 --- a/solr/.gitignore +++ b/solr/.gitignore @@ -24,3 +24,4 @@ lib/ test-lib/ +.vscode/ \ No newline at end of file diff --git a/solr/core/src/java/org/apache/solr/request/json/RequestUtil.java b/solr/core/src/java/org/apache/solr/request/json/RequestUtil.java index 39bc03dc5623..60f53793db36 100644 --- a/solr/core/src/java/org/apache/solr/request/json/RequestUtil.java +++ b/solr/core/src/java/org/apache/solr/request/json/RequestUtil.java @@ -38,6 +38,12 @@ import org.noggit.ObjectBuilder; public class RequestUtil { + /** + * Top-level JSON key holding the map of named query definitions, referenced elsewhere (e.g. by + * {@link org.apache.solr.search.IntervalsQParserPlugin}) via a {@code $name} local param value. + */ + public static final String JSON_QUERIES_KEY = "json_queries"; + /** * Set default-ish params on a SolrQueryRequest as well as do standard macro processing and JSON * request parsing. @@ -254,6 +260,10 @@ public static void processParams( SolrException.ErrorCode.BAD_REQUEST, "Expected Map for 'queries', received " + queriesJsonObj); } + } else if (JSON_QUERIES_KEY.equals(key)) { + // passed through as a parsed object for use by SearchComponent.prepare() at subordinate + // nodes; not processed here + continue; } else if ("params".equals(key) || "facet".equals(key)) { // handled elsewhere continue; diff --git a/solr/core/src/java/org/apache/solr/search/IntervalsQParserPlugin.java b/solr/core/src/java/org/apache/solr/search/IntervalsQParserPlugin.java new file mode 100644 index 000000000000..9b37c229e444 --- /dev/null +++ b/solr/core/src/java/org/apache/solr/search/IntervalsQParserPlugin.java @@ -0,0 +1,699 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.solr.search; + +import java.io.IOException; +import java.util.ArrayList; +import java.util.List; +import java.util.Map; +import org.apache.lucene.analysis.Analyzer; +import org.apache.lucene.queries.intervals.IntervalQuery; +import org.apache.lucene.queries.intervals.Intervals; +import org.apache.lucene.queries.intervals.IntervalsSource; +import org.apache.lucene.search.Query; +import org.apache.lucene.util.BytesRef; +import org.apache.solr.common.SolrException; +import org.apache.solr.common.params.CommonParams; +import org.apache.solr.common.params.SolrParams; +import org.apache.solr.request.SolrQueryRequest; +import org.apache.solr.request.json.RequestUtil; +import org.apache.solr.schema.FieldType; +import org.apache.solr.schema.SchemaField; +import org.apache.solr.schema.TextField; + +/** + * A query parser that builds interval queries from a JSON DSL description. Invoked with the syntax + * {@code {!intervals df=title}$foobar}. + * + *

The {@code $foobar} reference (the query string following the local params) names an entry in + * the {@code json_queries} map (passed via the JSON DSL). The top-level key of the named query must + * be a rule name (e.g., {@code match}, {@code all_of}). The target field is read from the {@code + * df} local param, falling back to the {@code df} query param. Example: {@code {all_of: {...}}} + * with {@code df=title}. + */ +public class IntervalsQParserPlugin extends QParserPlugin { + public static final String NAME = "intervals"; + private static final int DEFAULT_FUZZY_MAX_EXPANSIONS = Intervals.DEFAULT_MAX_EXPANSIONS; + + /** Syntax reminder included in exceptions thrown for malformed/missing input. */ + private static final String SYNTAX_HELP = + "Expected syntax '{!intervals df=}$', where refers to an entry " + + "in the 'json_queries' map of the JSON request body, e.g. " + + "q={!intervals df=title}$myQuery with json={\"json_queries\":{\"myQuery\":{...}}}"; + + @Override + public QParser createParser( + String qstr, SolrParams localParams, SolrParams params, SolrQueryRequest req) { + return new QParser(qstr, localParams, params, req) { + @Override + public Query parse() { + if (qstr == null || qstr.isEmpty() || qstr.charAt(0) != '$' || qstr.length() < 2) { + throw new SolrException(SolrException.ErrorCode.BAD_REQUEST, SYNTAX_HELP); + } + String jsonQueryName = qstr.substring(1); + + Map json = req.getJSON(); + if (json == null) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, "No JSON request body found; " + SYNTAX_HELP); + } + + Object jsonQueriesObj = json.get(RequestUtil.JSON_QUERIES_KEY); + if (!(jsonQueriesObj instanceof Map)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "No '" + + RequestUtil.JSON_QUERIES_KEY + + "' map found in JSON request body; " + + SYNTAX_HELP); + } + + @SuppressWarnings("unchecked") + Map jsonQueries = (Map) jsonQueriesObj; + Object queryDef = jsonQueries.get(jsonQueryName); + + if (!(queryDef instanceof Map)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Query '" + + jsonQueryName + + "' not found in '" + + RequestUtil.JSON_QUERIES_KEY + + "' or is not an object; " + + SYNTAX_HELP); + } + + Map queryDefMap = asStringObjectMap(queryDef, "json query definition"); + + String field = getParam(CommonParams.DF); + if (field == null || field.isEmpty()) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Query '" + jsonQueryName + "' requires a 'df' parameter to specify the field"); + } + SchemaField defaultField = req.getSchema().getField(field); + + IntervalsSource source = parseRuleObject(queryDefMap, defaultField); + return new IntervalQuery(defaultField.getName(), source); + } + + private IntervalsSource parseRuleObject( + Map ruleObject, SchemaField defaultField) { + if (ruleObject.size() != 1) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Each rule object must contain exactly one rule key, got " + ruleObject.keySet()); + } + Map.Entry entry = ruleObject.entrySet().iterator().next(); + String ruleName = entry.getKey(); + Map ruleParams = + asStringObjectMap(entry.getValue(), "rule '" + ruleName + "'"); + + return switch (ruleName) { + case "match" -> parseMatchRule(ruleParams, defaultField); + case "prefix" -> parsePrefixRule(ruleParams, defaultField); + case "wildcard" -> parseWildcardRule(ruleParams, defaultField); + case "fuzzy" -> parseFuzzyRule(ruleParams, defaultField); + case "all_of" -> parseAllOfRule(ruleParams, defaultField); + case "any_of" -> parseAnyOfRule(ruleParams, defaultField); + case "term" -> parseTermRule(ruleParams, defaultField); + case "phrase" -> parsePhraseRule(ruleParams, defaultField); + case "regexp" -> parseRegexpRule(ruleParams, defaultField); + case "range" -> parseRangeRule(ruleParams, defaultField); + case "max_width" -> parseMaxWidthRule(ruleParams, defaultField); + case "extend" -> parseExtendRule(ruleParams, defaultField); + case "unordered_no_overlaps" -> parseUnorderedNoOverlapsRule(ruleParams, defaultField); + case "not_within" -> parseNotWithinRule(ruleParams, defaultField); + case "within" -> parseWithinRule(ruleParams, defaultField); + case "at_least" -> parseAtLeastRule(ruleParams, defaultField); + case "no_intervals" -> parseNoIntervalsRule(ruleParams); + default -> + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, "Unsupported intervals rule: " + ruleName); + }; + } + + private IntervalsSource parseMatchRule(Map params, SchemaField defaultField) { + String queryText = requireString(params, "query", "match"); + int maxGaps = getInt(params, "max_gaps", -1, "match"); + boolean ordered = getBoolean(params, "ordered", false, "match"); + String useField = getOptionalString(params, "use_field", "match"); + SchemaField analysisField = resolveField(useField, defaultField); + + Analyzer analyzer = resolveAnalyzer(params, analysisField, "match"); + IntervalsSource source; + try { + source = + Intervals.analyzedText( + queryText, analyzer, analysisField.getName(), maxGaps, ordered); + } catch (IOException e) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Failed to analyze match query text for field '" + analysisField.getName() + "'", + e); + } + if (useField != null) { + source = Intervals.fixField(analysisField.getName(), source); + } + return applyFilter(source, params.get("filter"), defaultField); + } + + private IntervalsSource parsePrefixRule( + Map params, SchemaField defaultField) { + String prefix = requireString(params, "prefix", "prefix"); + String useField = getOptionalString(params, "use_field", "prefix"); + SchemaField field = resolveField(useField, defaultField); + Analyzer analyzer = resolveMultiTermAnalyzer(params, field, "prefix"); + String normalizedPrefix = normalizeMultiTerm(field.getName(), prefix, analyzer); + IntervalsSource source = Intervals.prefix(new BytesRef(normalizedPrefix)); + if (useField != null) { + source = Intervals.fixField(field.getName(), source); + } + return source; + } + + private IntervalsSource parseWildcardRule( + Map params, SchemaField defaultField) { + String pattern = requireString(params, "pattern", "wildcard"); + String useField = getOptionalString(params, "use_field", "wildcard"); + SchemaField field = resolveField(useField, defaultField); + Analyzer analyzer = resolveMultiTermAnalyzer(params, field, "wildcard"); + String normalizedPattern = normalizeMultiTerm(field.getName(), pattern, analyzer); + IntervalsSource source = Intervals.wildcard(new BytesRef(normalizedPattern)); + if (useField != null) { + source = Intervals.fixField(field.getName(), source); + } + return source; + } + + private IntervalsSource parseFuzzyRule(Map params, SchemaField defaultField) { + String term = requireString(params, "term", "fuzzy"); + String useField = getOptionalString(params, "use_field", "fuzzy"); + SchemaField field = resolveField(useField, defaultField); + Analyzer analyzer = resolveMultiTermAnalyzer(params, field, "fuzzy"); + String normalizedTerm = normalizeMultiTerm(field.getName(), term, analyzer); + + String fuzziness = getOptionalString(params, "fuzziness", "fuzzy"); + int maxEdits = resolveFuzziness(fuzziness, normalizedTerm); + int prefixLength = getInt(params, "prefix_length", 0, "fuzzy"); + if (prefixLength < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'fuzzy' requires a non-negative integer 'prefix_length'"); + } + boolean transpositions = getBoolean(params, "transpositions", true, "fuzzy"); + + IntervalsSource source = + Intervals.fuzzyTerm( + normalizedTerm, + maxEdits, + prefixLength, + transpositions, + DEFAULT_FUZZY_MAX_EXPANSIONS); + if (useField != null) { + source = Intervals.fixField(field.getName(), source); + } + return source; + } + + private IntervalsSource parseAllOfRule(Map params, SchemaField defaultField) { + List intervals = parseIntervalsArray(params, defaultField, "all_of"); + boolean ordered = getBoolean(params, "ordered", false, "all_of"); + int maxGaps = getInt(params, "max_gaps", -1, "all_of"); + + IntervalsSource source = + ordered + ? Intervals.ordered(intervals.toArray(IntervalsSource[]::new)) + : Intervals.unordered(intervals.toArray(IntervalsSource[]::new)); + if (maxGaps >= 0) { + source = Intervals.maxgaps(maxGaps, source); + } + return applyFilter(source, params.get("filter"), defaultField); + } + + private IntervalsSource parseAnyOfRule(Map params, SchemaField defaultField) { + List intervals = parseIntervalsArray(params, defaultField, "any_of"); + IntervalsSource source = Intervals.or(intervals); + return applyFilter(source, params.get("filter"), defaultField); + } + + private IntervalsSource parseTermRule(Map params, SchemaField defaultField) { + String value = requireString(params, "value", "term"); + String useField = getOptionalString(params, "use_field", "term"); + IntervalsSource source = Intervals.term(value); + if (useField != null) { + source = Intervals.fixField(resolveField(useField, defaultField).getName(), source); + } + return source; + } + + private IntervalsSource parsePhraseRule( + Map params, SchemaField defaultField) { + 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)"); + } + if (termsObj != null) { + if (!(termsObj instanceof List)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'phrase' requires 'terms' to be an array of strings"); + } + List rawTerms = (List) termsObj; + String[] terms = new String[rawTerms.size()]; + for (int i = 0; i < rawTerms.size(); i++) { + Object t = rawTerms.get(i); + if (!(t instanceof String)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'phrase' requires all 'terms' elements to be strings, got " + + describeType(t)); + } + terms[i] = (String) t; + } + return Intervals.phrase(terms); + } else { + List intervals = parseIntervalsArray(params, defaultField, "phrase"); + return Intervals.phrase(intervals.toArray(IntervalsSource[]::new)); + } + } + + private IntervalsSource parseRegexpRule( + Map params, SchemaField defaultField) { + String pattern = requireString(params, "pattern", "regexp"); + String useField = getOptionalString(params, "use_field", "regexp"); + int maxExpansions = + getInt(params, "max_expansions", Intervals.DEFAULT_MAX_EXPANSIONS, "regexp"); + if (maxExpansions < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'regexp' requires a non-negative integer 'max_expansions', got " + + maxExpansions); + } + IntervalsSource source = Intervals.regexp(new BytesRef(pattern), maxExpansions); + if (useField != null) { + source = Intervals.fixField(resolveField(useField, defaultField).getName(), source); + } + return source; + } + + private IntervalsSource parseRangeRule(Map params, SchemaField defaultField) { + String lowerTermStr = getOptionalString(params, "lower_term", "range"); + String upperTermStr = getOptionalString(params, "upper_term", "range"); + boolean includeLower = getBoolean(params, "include_lower", true, "range"); + boolean includeUpper = getBoolean(params, "include_upper", false, "range"); + int maxExpansions = + getInt(params, "max_expansions", Intervals.DEFAULT_MAX_EXPANSIONS, "range"); + if (maxExpansions < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'range' requires a non-negative integer 'max_expansions', got " + + maxExpansions); + } + BytesRef lowerTerm = lowerTermStr == null ? null : new BytesRef(lowerTermStr); + BytesRef upperTerm = upperTermStr == null ? null : new BytesRef(upperTermStr); + return Intervals.range(lowerTerm, upperTerm, includeLower, includeUpper, maxExpansions); + } + + private IntervalsSource parseMaxWidthRule( + Map params, SchemaField defaultField) { + int width = getInt(params, "width", -1, "max_width"); + if (width < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'max_width' requires a non-negative integer 'width'"); + } + IntervalsSource source = parseNestedRule(params, "source", "max_width", defaultField); + return Intervals.maxwidth(width, source); + } + + private IntervalsSource parseExtendRule( + Map params, SchemaField defaultField) { + int before = getInt(params, "before", 0, "extend"); + int after = getInt(params, "after", 0, "extend"); + IntervalsSource source = parseNestedRule(params, "source", "extend", defaultField); + return Intervals.extend(source, before, after); + } + + private IntervalsSource parseUnorderedNoOverlapsRule( + Map params, SchemaField defaultField) { + List intervals = + parseIntervalsArray(params, defaultField, "unordered_no_overlaps"); + if (intervals.size() != 2) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'unordered_no_overlaps' requires exactly 2 intervals, got " + intervals.size()); + } + return Intervals.unorderedNoOverlaps(intervals.get(0), intervals.get(1)); + } + + private IntervalsSource parseNotWithinRule( + Map params, SchemaField defaultField) { + IntervalsSource source = parseNestedRule(params, "source", "not_within", defaultField); + int positions = getInt(params, "positions", -1, "not_within"); + if (positions < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'not_within' requires a non-negative integer 'positions'"); + } + IntervalsSource reference = + parseNestedRule(params, "reference", "not_within", defaultField); + return Intervals.notWithin(source, positions, reference); + } + + private IntervalsSource parseWithinRule( + Map params, SchemaField defaultField) { + IntervalsSource source = parseNestedRule(params, "source", "within", defaultField); + int positions = getInt(params, "positions", -1, "within"); + if (positions < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'within' requires a non-negative integer 'positions'"); + } + IntervalsSource reference = parseNestedRule(params, "reference", "within", defaultField); + return Intervals.within(source, positions, reference); + } + + private IntervalsSource parseAtLeastRule( + Map params, SchemaField defaultField) { + int minShouldMatch = getInt(params, "min_should_match", -1, "at_least"); + if (minShouldMatch < 0) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule 'at_least' requires a non-negative integer 'min_should_match'"); + } + List intervals = parseIntervalsArray(params, defaultField, "at_least"); + return Intervals.atLeast(minShouldMatch, intervals.toArray(IntervalsSource[]::new)); + } + + private IntervalsSource parseNoIntervalsRule(Map params) { + String reason = getOptionalString(params, "reason", "no_intervals"); + return Intervals.noIntervals(reason == null ? "no_intervals rule" : reason); + } + + private IntervalsSource parseNestedRule( + Map params, String key, String ruleName, SchemaField defaultField) { + Object nested = params.get(key); + if (nested == null) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + ruleName + "' requires '" + key + "' parameter"); + } + return parseRuleObject( + asStringObjectMap(nested, "'" + key + "' in rule '" + ruleName + "'"), defaultField); + } + + private List parseIntervalsArray( + Map params, SchemaField defaultField, String ruleName) { + Object intervalsObj = params.get("intervals"); + if (!(intervalsObj instanceof List)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + ruleName + "' requires an 'intervals' array"); + } + List rawIntervals = (List) intervalsObj; + if (rawIntervals.isEmpty()) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + ruleName + "' requires at least one interval rule"); + } + List parsed = new ArrayList<>(rawIntervals.size()); + for (Object intervalObj : rawIntervals) { + parsed.add( + parseRuleObject( + asStringObjectMap(intervalObj, "intervals array element"), defaultField)); + } + return parsed; + } + + private IntervalsSource applyFilter( + IntervalsSource source, Object filterObj, SchemaField defaultField) { + if (filterObj == null) { + return source; + } + Map filterMap = asStringObjectMap(filterObj, "filter"); + if (filterMap.size() != 1) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Filter must contain exactly one operator, got " + filterMap.keySet()); + } + + Map.Entry entry = filterMap.entrySet().iterator().next(); + String op = entry.getKey(); + if ("script".equals(op)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, "Filter operator 'script' is not supported"); + } + IntervalsSource other = + parseRuleObject( + asStringObjectMap(entry.getValue(), "filter '" + op + "'"), defaultField); + return switch (op) { + case "after" -> Intervals.after(source, other); + case "before" -> Intervals.before(source, other); + case "contained_by" -> Intervals.containedBy(source, other); + case "containing" -> Intervals.containing(source, other); + case "not_contained_by" -> Intervals.notContainedBy(source, other); + case "not_containing" -> Intervals.notContaining(source, other); + case "not_overlapping" -> Intervals.nonOverlapping(source, other); + case "overlapping" -> Intervals.overlapping(source, other); + default -> + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, "Unsupported filter operator: " + op); + }; + } + + /** + * Resolves the field referenced by an optional {@code use_field} rule parameter, falling back + * to the query's default field when absent. Throws BAD_REQUEST if {@code useField} names a + * field that doesn't exist in the schema. + */ + private SchemaField resolveField(String useField, SchemaField defaultField) { + return useField == null ? defaultField : req.getSchema().getField(useField); + } + + private Analyzer resolveAnalyzer( + Map params, SchemaField field, String ruleName) { + String analyzerName = getOptionalString(params, "analyzer", ruleName); + if (analyzerName == null) { + return field.getType().getQueryAnalyzer(); + } + return resolveFieldType(analyzerName, ruleName).getQueryAnalyzer(); + } + + /** + * Resolves the analyzer to use for normalizing prefix/wildcard/fuzzy term text. Unlike {@link + * #resolveAnalyzer}, this uses the field type's multi-term analyzer rather than its regular + * query analyzer, since the term text here is a single already-tokenized value, not free text + * to be tokenized. + */ + private Analyzer resolveMultiTermAnalyzer( + Map params, SchemaField field, String ruleName) { + String analyzerName = getOptionalString(params, "analyzer", ruleName); + FieldType fieldType = + analyzerName == null ? field.getType() : resolveFieldType(analyzerName, ruleName); + if (fieldType instanceof TextField textField) { + return textField.getMultiTermAnalyzer(); + } + return null; + } + + private FieldType resolveFieldType(String analyzerName, String ruleName) { + FieldType fieldType = req.getSchema().getFieldTypeByName(analyzerName); + if (fieldType == null) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Unknown analyzer '" + + analyzerName + + "' for rule '" + + ruleName + + "'. In Solr this value must match a field type name."); + } + return fieldType; + } + + private String normalizeMultiTerm(String field, String term, Analyzer analyzer) { + if (analyzer == null) { + return term; + } + BytesRef analyzed = TextField.analyzeMultiTerm(field, term, analyzer); + return analyzed == null ? term : analyzed.utf8ToString(); + } + + private int resolveFuzziness(String fuzziness, String term) { + if (fuzziness == null || "AUTO".equals(fuzziness)) { + return resolveAutoFuzziness(term, 3, 6); + } + if (fuzziness.startsWith("AUTO:")) { + String thresholds = fuzziness.substring("AUTO:".length()); + String[] parts = thresholds.split(","); + if (parts.length != 2) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Invalid fuzziness value: " + fuzziness + ". Expected AUTO:,"); + } + int low; + int high; + try { + low = Integer.parseInt(parts[0].trim()); + high = Integer.parseInt(parts[1].trim()); + } catch (NumberFormatException e) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Invalid fuzziness value: " + fuzziness + ". Expected AUTO:,", + e); + } + return resolveAutoFuzziness(term, low, high); + } + try { + int edits = Integer.parseInt(fuzziness); + if (edits < 0 || edits > 2) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "fuzziness must be between 0 and 2, got " + edits); + } + return edits; + } catch (NumberFormatException e) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, "Invalid fuzziness value: " + fuzziness, e); + } + } + + private int resolveAutoFuzziness(String term, int low, int high) { + int length = term.codePointCount(0, term.length()); + if (length < low) { + return 0; + } + if (length < high) { + return 1; + } + return 2; + } + + private Map asStringObjectMap(Object obj, String context) { + if (!(obj instanceof Map mapObj)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Expected object for " + context + ", got " + describeType(obj)); + } + List badKeys = new ArrayList<>(); + for (Object key : mapObj.keySet()) { + if (!(key instanceof String)) { + badKeys.add(String.valueOf(key)); + } + } + if (!badKeys.isEmpty()) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Expected string keys for " + context + ", got keys " + badKeys); + } + @SuppressWarnings("unchecked") + Map casted = (Map) mapObj; + return casted; + } + + private String requireString(Map map, String key, String context) { + Object val = map.get(key); + if (!(val instanceof String)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + + context + + "' requires string parameter '" + + key + + "', got " + + describeType(val)); + } + return (String) val; + } + + private String getOptionalString(Map map, String key, String context) { + Object val = map.get(key); + if (val == null) { + return null; + } + if (!(val instanceof String)) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + + context + + "' expects string parameter '" + + key + + "', got " + + describeType(val)); + } + return (String) val; + } + + private boolean getBoolean( + Map map, String key, boolean defaultValue, String context) { + Object val = map.get(key); + if (val == null) { + return defaultValue; + } + if (val instanceof Boolean b) { + return b; + } + if (val instanceof String s) { + return Boolean.parseBoolean(s); + } + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + + context + + "' expects boolean parameter '" + + key + + "', got " + + describeType(val)); + } + + private int getInt(Map map, String key, int defaultValue, String context) { + Object val = map.get(key); + if (val == null) { + return defaultValue; + } + if (val instanceof Number n) { + return n.intValue(); + } + if (val instanceof String s) { + try { + return Integer.parseInt(s); + } catch (NumberFormatException e) { + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + context + "' expects integer parameter '" + key + "', got " + s, + e); + } + } + throw new SolrException( + SolrException.ErrorCode.BAD_REQUEST, + "Rule '" + + context + + "' expects integer parameter '" + + key + + "', got " + + describeType(val)); + } + + private String describeType(Object value) { + return value == null ? "null" : value.getClass().getName(); + } + }; + } +} diff --git a/solr/core/src/java/org/apache/solr/search/QParserPlugin.java b/solr/core/src/java/org/apache/solr/search/QParserPlugin.java index 4504a8086e79..e21385592ea0 100644 --- a/solr/core/src/java/org/apache/solr/search/QParserPlugin.java +++ b/solr/core/src/java/org/apache/solr/search/QParserPlugin.java @@ -92,6 +92,7 @@ public abstract class QParserPlugin implements NamedListInitializedPlugin { map.put(VectorSimilarityQParserPlugin.NAME, new VectorSimilarityQParserPlugin()); map.put(FuzzyQParserPlugin.NAME, new FuzzyQParserPlugin()); map.put(NumericRangeQParserPlugin.NAME, new NumericRangeQParserPlugin()); + map.put(IntervalsQParserPlugin.NAME, new IntervalsQParserPlugin()); standardPlugins = Collections.unmodifiableMap(map); } diff --git a/solr/core/src/test/org/apache/solr/search/DistributedQParserTest.java b/solr/core/src/test/org/apache/solr/search/DistributedQParserTest.java new file mode 100644 index 000000000000..a70d8e9aadd9 --- /dev/null +++ b/solr/core/src/test/org/apache/solr/search/DistributedQParserTest.java @@ -0,0 +1,166 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.solr.search; + +import org.apache.solr.client.solrj.request.CollectionAdminRequest; +import org.apache.solr.client.solrj.request.QueryRequest; +import org.apache.solr.client.solrj.request.UpdateRequest; +import org.apache.solr.client.solrj.response.QueryResponse; +import org.apache.solr.cloud.SolrCloudTestCase; +import org.junit.BeforeClass; +import org.junit.Test; + +/** + * Distributed search tests for the standard query parsers: {@code lucene}, {@code dismax}, {@code + * edismax}, and {@code intervals}. + */ +public class DistributedQParserTest extends SolrCloudTestCase { + + private static final String COLLECTION = "distributed-qparser"; + + @BeforeClass + public static void setupCluster() throws Exception { + configureCluster(2).addConfig("conf", configset("cloud-dynamic")).configure(); + + CollectionAdminRequest.createCollection(COLLECTION, "conf", 2, 1) + .process(cluster.getSolrClient()); + cluster.waitForActiveCollection(COLLECTION, 2, 2); + + new UpdateRequest() + .add(sdoc("id", "1", "subject", "quick brown fox")) + .add(sdoc("id", "2", "subject", "lazy brown dog")) + .add(sdoc("id", "3", "subject", "quick red dog")) + .add(sdoc("id", "4", "subject", "slow green cat")) + .commit(cluster.getSolrClient(), COLLECTION); + } + + @Test + public void testLuceneQParser() throws Exception { + QueryResponse response = + new QueryRequest(params("q", "subject:quick", "defType", "lucene", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(2, response.getResults().getNumFound()); + + response = + new QueryRequest(params("q", "subject:brown", "defType", "lucene", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(2, response.getResults().getNumFound()); + } + + @Test + public void testDismaxQParser() throws Exception { + QueryResponse response = + new QueryRequest(params("q", "quick", "defType", "dismax", "qf", "subject", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(2, response.getResults().getNumFound()); + + response = + new QueryRequest(params("q", "brown dog", "defType", "dismax", "qf", "subject", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(3, response.getResults().getNumFound()); + } + + @Test + public void testEdismaxQParser() throws Exception { + QueryResponse response = + new QueryRequest(params("q", "quick", "defType", "edismax", "qf", "subject", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(2, response.getResults().getNumFound()); + + response = + new QueryRequest( + params("q", "brown dog", "defType", "edismax", "qf", "subject", "fl", "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(3, response.getResults().getNumFound()); + } + + @Test + public void testIntervalsQParser() throws Exception { + // match rule: "quick" appears in docs 1 ("quick brown fox") and 3 ("quick red dog") + QueryResponse response = + new QueryRequest( + params( + "q", + "{!intervals df=subject}$q1", + "json", + "{json_queries:{q1:{match:{query:quick}}" + + (random().nextBoolean() ? ",ignore:{match:{query:lazy}}}}" : "}}"), + "fl", + "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(2, response.getResults().getNumFound()); + + // a distinct match rule: "lazy" appears only in doc 2 ("lazy brown dog") — confirm the + // result differs from the "quick" query above + QueryResponse lazyResponse = + new QueryRequest( + params( + "q", + "{!intervals df=subject}$q1", + "json", + "{json_queries:{q1:{match:{query:lazy}}" + + (random().nextBoolean() ? ",ignore:{match:{query:quick}}}}" : "}}"), + "fl", + "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(1, lazyResponse.getResults().getNumFound()); + assertNotEquals(response.getResults().getNumFound(), lazyResponse.getResults().getNumFound()); + + // all_of ordered: "quick" then "fox" — only doc 1 ("quick brown fox") matches + response = + new QueryRequest( + params( + "q", + "{!intervals df=subject}$q1", + "json", + "{json_queries:{q1:{all_of:{ordered:true," + + "intervals:[{match:{query:quick}},{match:{query:fox}}]}}}}", + "fl", + "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(1, response.getResults().getNumFound()); + + // union of two top-level interval queries: "quick" (docs 1, 3) or "lazy" (doc 2) — three + // docs match. Note: the leading space before the first "{!" is required, otherwise the + // whole q string is parsed as a single set of local params rather than two clauses. + response = + new QueryRequest( + params( + "q", + " {!intervals df=subject}$q1 {!intervals df=subject}$q2", + "json", + "{json_queries:{q1:{match:{query:quick}},q2:{match:{query:lazy}}}}", + "fl", + "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(3, response.getResults().getNumFound()); + + // intersection of two top-level interval queries (using "+" to require both clauses): + // "quick" (docs 1, 3) and "brown" (docs 1, 2) — only doc 1 has both terms + response = + new QueryRequest( + params( + "q", + " +{!intervals df=subject}$q1 +{!intervals df=subject}$q2", + "json", + "{json_queries:{q1:{match:{query:quick}},q2:{match:{query:brown}}}}", + "fl", + "id")) + .process(cluster.getSolrClient(), COLLECTION); + assertEquals(1, response.getResults().getNumFound()); + } +} diff --git a/solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java b/solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java index ecad83f39de0..31a75ecd364a 100644 --- a/solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java +++ b/solr/core/src/test/org/apache/solr/search/QueryEqualityTest.java @@ -174,6 +174,17 @@ public void testQueryFuzzy() throws Exception { } } + public void testQueryIntervals() throws Exception { + try (SolrQueryRequest req = req("myField", "foo_s")) { + req.setJSON(Map.of("json_queries", Map.of("q1", Map.of("term", Map.of("value", "asdf"))))); + assertQueryEquals( + IntervalsQParserPlugin.NAME, + req, + "{!intervals df=$myField}$q1", + "{!intervals df=foo_s}$q1"); + } + } + public void testQueryBoost() throws Exception { SolrQueryRequest req = req("df", "foo_s", "myBoost", "sum(3,foo_i)"); try { diff --git a/solr/core/src/test/org/apache/solr/search/TestIntervalsQParserPlugin.java b/solr/core/src/test/org/apache/solr/search/TestIntervalsQParserPlugin.java new file mode 100644 index 000000000000..2db09515c221 --- /dev/null +++ b/solr/core/src/test/org/apache/solr/search/TestIntervalsQParserPlugin.java @@ -0,0 +1,588 @@ +/* + * Licensed to the Apache Software Foundation (ASF) under one or more + * contributor license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright ownership. + * The ASF licenses this file to You under the Apache License, Version 2.0 + * (the "License"); you may not use this file except in compliance with + * the License. You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.apache.solr.search; + +import org.apache.solr.SolrTestCaseJ4; +import org.apache.solr.common.SolrException; +import org.junit.BeforeClass; +import org.junit.Test; + +/** Tests for {@link IntervalsQParserPlugin}. */ +public class TestIntervalsQParserPlugin extends SolrTestCaseJ4 { + + @BeforeClass + public static void beforeClass() throws Exception { + initCore("solrconfig.xml", "schema11.xml"); + } + + @Test + public void testIntervalsMissingQueryReferenceThrows() throws Exception { + assertU(adoc("id", "1", "v_t", "hello world")); + assertU(commit()); + + // Without a "$name" query string the parser must explain the required syntax + assertQEx( + "intervals qparser without a $name reference should throw BAD_REQUEST", + "Expected syntax", + req("q", "{!intervals df=v_t}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMissingJsonBodyThrows() throws Exception { + assertU(adoc("id", "2", "v_t", "hello world")); + assertU(commit()); + + // With a $name reference but no JSON request body at all + assertQEx( + "intervals qparser without a JSON body should throw BAD_REQUEST", + "No JSON request body found", + req("q", "{!intervals df=v_t}$myQuery"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMissingJsonQueriesKeyThrows() throws Exception { + assertU(adoc("id", "3", "v_t", "hello world")); + assertU(commit()); + + // JSON body present, but no top-level "json_queries" map + assertQEx( + "intervals qparser without a json_queries map should throw BAD_REQUEST", + "No 'json_queries' map found", + req("q", "{!intervals df=v_t}$myQuery", "json", "{params:{}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMissingNamedQueryThrows() throws Exception { + assertU(adoc("id", "4", "v_t", "hello world")); + assertU(commit()); + + // json_queries map present, but it has no entry named "myQuery" + assertQEx( + "intervals qparser with an unresolved $name reference should throw BAD_REQUEST", + "Query 'myQuery' not found in 'json_queries'", + req( + "q", + "{!intervals df=v_t}$myQuery", + "json", + "{json_queries:{otherQuery:{match:{query:foo}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMatchRuleMatchesDocument() throws Exception { + assertU(adoc("id", "10", "v_t", "foo bar")); + assertU(adoc("id", "11", "v_t", "baz qux")); + assertU(commit()); + + // field specified via df local param; the named json_queries entry is the rule object directly + assertQ( + "intervals qparser with match rule should match documents containing the term", + req( + "q", + "{!intervals df=v_t}$myQuery", + "json", + "{json_queries:{myQuery:{match:{query:foo}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='10']"); + } + + @Test + public void testIntervalsAllOfAnyOfNamedQuery() throws Exception { + assertU(adoc("id", "30", "title_t", "alpha beta gamma delta")); + assertU(adoc("id", "31", "title_t", "alpha beta epsilon delta")); + assertU(adoc("id", "32", "title_t", "alpha zeta gamma delta")); + assertU(commit()); + + assertQ( + "intervals qparser should support all_of with nested any_of via df local param", + req( + "q", + "{!intervals df=title_t}$second_query", + "json", + "{json_queries:{" + + "second_query:{" + + "all_of:{" + + "ordered:true," + + "intervals:[" + + "{match:{query:'alpha beta', max_gaps:0, ordered:true}}," + + "{any_of:{intervals:[" + + "{match:{query:'gamma delta', max_gaps:0, ordered:true}}," + + "{match:{query:'epsilon delta', max_gaps:0, ordered:true}}" + + "]}}" + + "]" + + "}" + + "}" + + "}}"), + "//result[@numFound='2']"); + } + + @Test + public void testIntervalsNoMatchingRule() throws Exception { + assertU(adoc("id", "20", "v_t", "hello world")); + assertU(commit()); + + // Match rule text not present in any document; field via df local param + assertQ( + "intervals qparser with non-matching rule should return no docs", + req( + "q", + "{!intervals df=v_t}$myQuery", + "json", + "{json_queries:{myQuery:{match:{query:zzznomatch}}}}"), + "//result[@numFound='0']"); + } + + @Test + public void testIntervalsTermRule() throws Exception { + assertU(adoc("id", "40", "v_ws", "trm_apple trm_banana")); + assertU(adoc("id", "41", "v_ws", "trm_banana trm_cherry")); + assertU(commit()); + + assertQ( + "term rule should match documents containing the exact term", + req("q", "{!intervals df=v_ws}$q1", "json", "{json_queries:{q1:{term:{value:trm_apple}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='40']"); + } + + @Test + public void testIntervalsPhraseRuleWithTerms() throws Exception { + assertU(adoc("id", "50", "v_ws", "phrA_quick phrA_brown phrA_fox")); + assertU(adoc("id", "51", "v_ws", "phrA_quick phrA_fox phrA_brown")); + assertU(commit()); + + assertQ( + "phrase rule with terms array should match documents with exact phrase", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{phrase:{terms:[phrA_quick,phrA_brown,phrA_fox]}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='50']"); + // same query expressed via the top-level JSON "query" (rather than the "q" param) still + // resolves the intervals qparser's $q1 reference against json_queries + assertJQ( + req( + "json", + "{query:{intervals:{df:v_ws, query:$q1}}, " + + " json_queries:{q1:{phrase:{terms:[phrA_quick,phrA_brown,phrA_fox]}}}," + + " fields:id" + + "}"), + "/response=={'numFound':1,'start':0,'numFoundExact':true,'docs':[{'id':'50'}]}"); + } + + @Test + public void testIntervalsPhraseRuleWithIntervals() throws Exception { + assertU(adoc("id", "52", "v_ws", "phrB_quick phrB_brown phrB_fox")); + assertU(adoc("id", "53", "v_ws", "phrB_quick phrB_fox phrB_brown")); + assertU(commit()); + + assertQ( + "phrase rule with intervals array should match documents with the phrase in order", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{phrase:{intervals:" + + "[{term:{value:phrB_quick}},{term:{value:phrB_brown}},{term:{value:phrB_fox}}]}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='52']"); + } + + @Test + public void testIntervalsRegexpRule() throws Exception { + assertU(adoc("id", "60", "v_ws", "rx_cat")); + assertU(adoc("id", "61", "v_ws", "rx_car")); + assertU(adoc("id", "62", "v_ws", "rx_dog")); + assertU(commit()); + + assertQ( + "regexp rule should match documents with terms matching the pattern", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{regexp:{pattern:'rx_ca.*'}}}}"), + "//result[@numFound='2']"); + + assertQEx( + "regexp rule should reject a negative max_expansions with BAD_REQUEST", + "max_expansions", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{regexp:{pattern:'rx_ca.*',max_expansions:-1}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsRangeRule() throws Exception { + assertU(adoc("id", "70", "v_ws", "rng_aaaa")); + assertU(adoc("id", "71", "v_ws", "rng_bbbb")); + assertU(adoc("id", "72", "v_ws", "rng_cccc")); + assertU(adoc("id", "73", "v_ws", "rng_dddd")); + assertU(commit()); + + assertQ( + "range rule should match documents with terms in the given range", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{range:{lower_term:rng_bbbb,upper_term:rng_cccc," + + "include_lower:true,include_upper:true}}}}"), + "//result[@numFound='2']", + "//doc/str[@name='id'][.='71']", + "//doc/str[@name='id'][.='72']"); + + assertQEx( + "range rule should reject a negative max_expansions with BAD_REQUEST", + "max_expansions", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{range:{lower_term:rng_bbbb,upper_term:rng_cccc," + + "include_lower:true,include_upper:true,max_expansions:-1}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsFuzzyRule() throws Exception { + assertU(adoc("id", "80", "v_ws", "fzz_cat")); + assertU(adoc("id", "81", "v_ws", "fzz_car")); + assertU(adoc("id", "82", "v_ws", "fzz_dog")); + assertU(commit()); + + assertQ( + "fuzzy rule should match documents with terms within the edit distance", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{fuzzy:{term:fzz_cat,fuzziness:'1'}}}}"), + "//result[@numFound='2']", + "//doc/str[@name='id'][.='80']", + "//doc/str[@name='id'][.='81']"); + + assertQEx( + "fuzzy rule should reject a negative prefix_length with BAD_REQUEST", + "prefix_length", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{fuzzy:{term:fzz_cat,prefix_length:-1}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMaxWidthRule() throws Exception { + assertU(adoc("id", "80", "v_ws", "mwd_alpha mwd_beta mwd_gamma")); + assertU(adoc("id", "81", "v_ws", "mwd_alpha mwd_zeta mwd_gamma")); + assertU(commit()); + + // ordered phrase "mwd_alpha mwd_beta" has width 2 (positions 0..1); doc 81 has no mwd_beta + assertQ( + "max_width rule should filter intervals by maximum width", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{max_width:{width:2,source:" + + "{all_of:{ordered:true,intervals:[{term:{value:mwd_alpha}},{term:{value:mwd_beta}}]}}}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='80']"); + } + + @Test + public void testIntervalsExtendRule() throws Exception { + assertU(adoc("id", "90", "v_ws", "ext_one ext_two ext_three ext_four ext_five")); + assertU(adoc("id", "91", "v_ws", "ext_one ext_five")); + assertU(commit()); + + // extend ext_three by before=2 and after=2; doc 90 has ext_three, doc 91 does not + assertQ( + "extend rule should extend intervals by specified positions", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{extend:{source:{term:{value:ext_three}},before:2,after:2}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='90']"); + } + + @Test + public void testIntervalsUnorderedNoOverlapsRule() throws Exception { + assertU(adoc("id", "100", "v_ws", "uno_foo uno_bar")); + assertU(adoc("id", "101", "v_ws", "uno_bar uno_foo")); + assertU(adoc("id", "102", "v_ws", "uno_baz uno_qux")); + assertU(commit()); + + assertQ( + "unordered_no_overlaps rule should match documents containing both terms without overlap", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{unordered_no_overlaps:{intervals:" + + "[{term:{value:uno_foo}},{term:{value:uno_bar}}]}}}}"), + "//result[@numFound='2']"); + } + + @Test + public void testIntervalsWithinRule() throws Exception { + assertU(adoc("id", "110", "v_ws", "wth_alpha wth_beta wth_gamma")); + assertU(adoc("id", "111", "v_ws", "wth_alpha wth_zeta wth_eps wth_gamma")); + assertU(commit()); + + // "wth_alpha" within 1 position of "wth_beta": doc 110 matches (adjacent), doc 111 does not + assertQ( + "within rule should match documents where source appears within N positions of reference", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{within:{source:{term:{value:wth_alpha}}," + + "positions:1,reference:{term:{value:wth_beta}}}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='110']"); + } + + @Test + public void testIntervalsNotWithinRule() throws Exception { + assertU(adoc("id", "120", "v_ws", "nwt_alpha nwt_zeta nwt_eps nwt_gamma")); + assertU(adoc("id", "121", "v_ws", "nwt_alpha nwt_beta nwt_gamma")); + assertU(commit()); + + // "nwt_alpha" NOT within 1 position of "nwt_beta": doc 121 has them adjacent (excluded), + // doc 120 has no nwt_beta so nwt_alpha qualifies + assertQ( + "not_within rule should match documents where source is not within N positions of reference", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{not_within:{source:{term:{value:nwt_alpha}}," + + "positions:1,reference:{term:{value:nwt_beta}}}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='120']"); + } + + @Test + public void testIntervalsAtLeastRule() throws Exception { + assertU(adoc("id", "130", "v_ws", "atl_alpha atl_beta atl_gamma")); + assertU(adoc("id", "131", "v_ws", "atl_alpha atl_gamma")); + assertU(adoc("id", "132", "v_ws", "atl_delta atl_epsilon")); + assertU(commit()); + + // at_least 2 of [atl_alpha, atl_beta, atl_gamma]: doc 130 has all 3, doc 131 has 2, doc 132 has + // none + assertQ( + "at_least rule should match documents containing at least N of the given sources", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{at_least:{min_should_match:2,intervals:" + + "[{term:{value:atl_alpha}},{term:{value:atl_beta}},{term:{value:atl_gamma}}]}}}}"), + "//result[@numFound='2']"); + } + + @Test + public void testIntervalsNoIntervalsRule() throws Exception { + assertU(adoc("id", "140", "v_ws", "nio_anything")); + assertU(commit()); + + assertQ( + "no_intervals rule should match no documents", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{no_intervals:{reason:testing}}}}"), + "//result[@numFound='0']"); + } + + @Test + public void testIntervalsDfFallbackFromQueryParam() throws Exception { + assertU(adoc("id", "150", "v_ws", "dfp_alpha dfp_beta")); + assertU(adoc("id", "151", "v_ws", "dfp_gamma dfp_delta")); + assertU(commit()); + + // df supplied as a regular query param (not a local param) should be used as the field + assertQ( + "df query param (not local param) should be used as the field when df is absent in local params", + req( + "q", + "{!intervals}$q1", + "df", + "v_ws", + "json", + "{json_queries:{q1:{term:{value:dfp_alpha}}}}"), + "//result[@numFound='1']", + "//doc/str[@name='id'][.='150']"); + } + + @Test + public void testIntervalsLegacyFieldInJsonQueryThrows() throws Exception { + assertU(adoc("id", "160", "v_ws", "bkc_alpha bkc_beta")); + assertU(commit()); + + // Old {field: rule_object} format is no longer supported: even with a valid df, the field + // name is mistaken for an (unsupported) rule name since rule objects must be + // {rule_name: {...}}, not {field_name: {...}}. + assertQEx( + "legacy {field: rule} format should throw BAD_REQUEST for an unrecognized rule name", + "Unsupported intervals rule: v_ws", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{v_ws:{term:{value:bkc_alpha}}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMatchRuleNonexistentDfFieldThrows() throws Exception { + // df names a field that doesn't exist in the schema; the match rule resolves its analyzer + // from this field since no analyzer/use_field override is given + assertQEx( + "match rule with a nonexistent df field should throw BAD_REQUEST", + "undefined field", + req( + "q", + "{!intervals df=no_such_field}$q1", + "json", + "{json_queries:{q1:{match:{query:foo}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsMatchRuleNonexistentUseFieldThrows() throws Exception { + // df is valid, but use_field overrides the field used to resolve the analyzer + assertQEx( + "match rule with a nonexistent use_field should throw BAD_REQUEST", + "undefined field", + req( + "q", + "{!intervals df=v_t}$q1", + "json", + "{json_queries:{q1:{match:{query:foo,use_field:no_such_field}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsPrefixRuleNonexistentDfFieldThrows() throws Exception { + // prefix/wildcard/fuzzy resolve their multi-term analyzer from the field the same way + assertQEx( + "prefix rule with a nonexistent df field should throw BAD_REQUEST", + "undefined field", + req( + "q", + "{!intervals df=no_such_field}$q1", + "json", + "{json_queries:{q1:{prefix:{prefix:foo}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsPrefixRuleNonexistentUseFieldThrows() throws Exception { + assertQEx( + "prefix rule with a nonexistent use_field should throw BAD_REQUEST", + "undefined field", + req( + "q", + "{!intervals df=v_ws}$q1", + "json", + "{json_queries:{q1:{prefix:{prefix:foo,use_field:no_such_field}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsUnknownAnalyzerFieldTypeThrows() throws Exception { + // an explicit 'analyzer' value that doesn't match any field type name in the schema + assertQEx( + "match rule with an unknown analyzer field type should throw BAD_REQUEST", + "Unknown analyzer", + req( + "q", + "{!intervals df=v_t}$q1", + "json", + "{json_queries:{q1:{match:{query:foo,analyzer:no_such_field_type}}}}"), + SolrException.ErrorCode.BAD_REQUEST); + } + + @Test + public void testIntervalsNestedAlternativeOutperformsXmlSpans() throws Exception { + // v_ws (text_ws) is a plain whitespace-tokenized field with no stemming/synonym/word-delimiter + // filters, so the literal terms used in the raw SpanTerm/term rules below match the indexed + // tokens exactly. + assertU(adoc("id", "170", "v_ws", "cmplorem cmpthe cmpdomain cmpis cmpipsum")); + assertU( + adoc("id", "171", "v_ws", "cmplorem cmpthe cmpdomain cmpname cmpsystem cmpis cmpipsum")); + assertU( + adoc("id", "172", "v_ws", "cmplorem cmpthe cmpdomain cmpblame cmpsystem cmpis cmpipsum")); + assertU(commit()); + + assertQ( + "xmlparser SpanNear with nested SpanOr/SpanNear misses one nested match", + req( + "q", + "{!xmlparser df=v_ws}" + + "" + + "cmpthe" + + "" + + "cmpdomain" + + "" + + "cmpdomain" + + "cmpname" + + "cmpsystem" + + "" + + "" + + "cmpis" + + ""), + "//result[@numFound='1']"); + + assertQ( + "intervals handles the same nested alternative and finds both valid matches", + req( + "q", + "{!intervals df=v_ws}$cmpq", + "json", + // max_gaps:0 mirrors the xmlparser query's slop="0": the whole sequence must be + // contiguous, so doc 172 (where cmpblame/cmpsystem separate cmpdomain from cmpis) + // is correctly excluded even though it contains "cmpdomain" in isolation. + "{json_queries:{cmpq:{all_of:{ordered:true,max_gaps:0,intervals:[" + + "{term:{value:cmpthe}}," + + "{any_of:{intervals:[" + + "{term:{value:cmpdomain}}," + + "{phrase:{terms:[cmpdomain,cmpname,cmpsystem]}}" + + "]}}" + + ",{term:{value:cmpis}}" + + "]}}}}"), + "//result[@numFound='2']", + "//doc/str[@name='id'][.='170']", + "//doc/str[@name='id'][.='171']"); + } +} diff --git a/solr/core/src/test/org/apache/solr/search/json/TestJsonRequest.java b/solr/core/src/test/org/apache/solr/search/json/TestJsonRequest.java index 628dd73766cf..73653cfc401d 100644 --- a/solr/core/src/test/org/apache/solr/search/json/TestJsonRequest.java +++ b/solr/core/src/test/org/apache/solr/search/json/TestJsonRequest.java @@ -357,6 +357,16 @@ public static void doJsonRequest(Client client, boolean isDistrib) throws Except params("json", "{query:'cat_s:A'}", "json.filter", "'where_s:NY'", "debug", "true"), "debug/json=={query:'cat_s:A', filter:'where_s:NY'}"); + // test json_queries: accepted as a known key and preserved as a parsed object in req.getJSON() + client.testJQ( + params( + "json", + "{query:'cat_s:A', json_queries:{myQuery:{lucene:{query:'where_s:NY'}}}}", + "debug", + "true"), + "response/numFound==2", + "debug/json/json_queries=={myQuery:{lucene:{query:'where_s:NY'}}}"); + // test query dsl client.testJQ(params("json", "{'query':'{!lucene}id:1'}"), "response/numFound==1"); diff --git a/solr/solr-ref-guide/modules/query-guide/pages/intervals-query-parser.adoc b/solr/solr-ref-guide/modules/query-guide/pages/intervals-query-parser.adoc new file mode 100644 index 000000000000..2bd2439de2cc --- /dev/null +++ b/solr/solr-ref-guide/modules/query-guide/pages/intervals-query-parser.adoc @@ -0,0 +1,749 @@ += Intervals Query Parser +// Licensed to the Apache Software Foundation (ASF) under one +// or more contributor license agreements. See the NOTICE file +// distributed with this work for additional information +// regarding copyright ownership. The ASF licenses this file +// to you under the Apache License, Version 2.0 (the +// "License"); you may not use this file except in compliance +// with the License. You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, +// software distributed under the License is distributed on an +// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +// KIND, either express or implied. See the License for the +// specific language governing permissions and limitations +// under the License. + +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 {lucene-javadocs}/queries/org/apache/lucene/queries/intervals/package-summary.html[Lucene Intervals package documentation] for a detailed description of the underlying interval machinery. + +Invoked with the syntax `{!intervals df=}$`. + +== Query Format + +Specify the target field using the `df` local param (or the `df` query param as a fallback). +The query string following the local params, `$`, is *required* and names an entry in the +`json_queries` map of the JSON request body; that entry is then the rule object directly, with no +field wrapper. +If the `$` reference is missing or malformed, or if `json_queries` (or the named entry +within it) is absent from the JSON request body, the query parser throws a `BAD_REQUEST` error +explaining the expected syntax. + +[source,text] +---- +q={!intervals df=title}$myQuery +---- + +[source,text] +---- +json={ + "json_queries": { + "myQuery": { + "match": { "query": "apache solr" } + } + } +} +---- + +== Parameters + +`$`:: ++ +[%autowidth,frame=none] +|=== +|Required |Default: none +|=== ++ +The query string following the local params (e.g., `$myQuery`). +Names an entry in the `json_queries` map that defines the interval query to execute. + +`df`:: ++ +[%autowidth,frame=none] +|=== +|Required |Default: none +|=== ++ +The field to run the interval query against. +Required; may be specified as a local param inside `{! }` or as a regular query param. + +== Interval Rules + +Each rule object contains exactly one key that identifies the rule type, mapped to an object of rule parameters. + +=== `match` + +Analyzes query text and matches documents where the resulting tokens appear according to positional constraints. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`query` +|Yes +|— +|The text to analyze and match. + +|`max_gaps` +|No +|`-1` (unlimited) +|Maximum number of gaps (positions) between matched terms. + +|`ordered` +|No +|`false` +|When `true`, terms must appear in the order given. + +|`use_field` +|No +|— +|Analyze using a different field's analyzer and match against that field. + +|`analyzer` +|No +|— +|Name of a field type to use as the analyzer (overrides field default). + +|`filter` +|No +|— +|A <> to apply after matching. +|=== + +Example: + +[source,json] +---- +{ "match": { "query": "apache solr", "max_gaps": 1, "ordered": true } } +---- + +=== `term` + +Matches a single exact term without analysis. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`value` +|Yes +|— +|The exact term to match. + +|`use_field` +|No +|— +|Match against this field instead of the query field. +|=== + +Example: + +[source,json] +---- +{ "term": { "value": "solr" } } +---- + +=== `phrase` + +Matches a sequence of terms or interval rules in order with no gaps. + +Accepts either a `terms` array of strings (for a simple phrase) or an `intervals` array of rule objects (to combine other rules into a phrase). + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`terms` +|One of `terms` / `intervals` required +|— +|Array of exact string terms forming the phrase. + +|`intervals` +|One of `terms` / `intervals` required +|— +|Array of rule objects that must match in sequence. +|=== + +Example using strings: + +[source,json] +---- +{ "phrase": { "terms": ["apache", "solr"] } } +---- + +Example using nested rules: + +[source,json] +---- +{ "phrase": { "intervals": [ { "term": { "value": "apache" } }, { "term": { "value": "solr" } } ] } } +---- + +=== `prefix` + +Matches all terms starting with a given prefix. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`prefix` +|Yes +|— +|The prefix string. Normalized using the field's multi-term analyzer. + +|`use_field` +|No +|— +|Operate on this field instead. + +|`analyzer` +|No +|— +|Field type name to use for normalization. +|=== + +Example: + +[source,json] +---- +{ "prefix": { "prefix": "sol" } } +---- + +=== `wildcard` + +Matches terms using a wildcard pattern (`*` and `?`). + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`pattern` +|Yes +|— +|The wildcard pattern. Normalized using the field's multi-term analyzer. + +|`use_field` +|No +|— +|Operate on this field instead. + +|`analyzer` +|No +|— +|Field type name to use for normalization. +|=== + +Example: + +[source,json] +---- +{ "wildcard": { "pattern": "sol*" } } +---- + +=== `regexp` + +Matches terms using a regular expression. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`pattern` +|Yes +|— +|The regular expression pattern. + +|`max_expansions` +|No +|`128` +|Maximum number of terms to expand the regexp to. + +|`use_field` +|No +|— +|Operate on this field instead. +|=== + +Example: + +[source,json] +---- +{ "regexp": { "pattern": "sol.r" } } +---- + +=== `fuzzy` + +Matches terms within a given edit distance of the supplied term. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`term` +|Yes +|— +|The term to match fuzzily. Normalized using the field's multi-term analyzer. + +|`fuzziness` +|No +|`AUTO` +|Edit distance: `0`, `1`, `2`, `AUTO`, or `AUTO:,`. + +|`prefix_length` +|No +|`0` +|Number of leading characters that must match exactly. + +|`transpositions` +|No +|`true` +|Whether transpositions count as a single edit. + +|`use_field` +|No +|— +|Operate on this field instead. + +|`analyzer` +|No +|— +|Field type name to use for normalization. +|=== + +Example: + +[source,json] +---- +{ "fuzzy": { "term": "solr", "fuzziness": "AUTO" } } +---- + +=== `range` + +Matches terms within a lexicographic range. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`lower_term` +|No +|— +|Lower bound of the range (inclusive by default). + +|`upper_term` +|No +|— +|Upper bound of the range (exclusive by default). + +|`include_lower` +|No +|`true` +|Whether to include the lower bound. + +|`include_upper` +|No +|`false` +|Whether to include the upper bound. + +|`max_expansions` +|No +|`128` +|Maximum number of terms to expand to. +|=== + +Example: + +[source,json] +---- +{ "range": { "lower_term": "aaa", "upper_term": "zzz" } } +---- + +== Combining Rules + +=== `all_of` + +Matches documents where all supplied intervals match in the same field, optionally ordered and within a maximum gap. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`intervals` +|Yes +|— +|Array of rule objects that must all match. + +|`ordered` +|No +|`false` +|When `true`, intervals must match in the order listed. + +|`max_gaps` +|No +|`-1` (unlimited) +|Maximum gap between matched intervals. + +|`filter` +|No +|— +|A <> to apply after matching. +|=== + +Example — ordered phrase with a gap: + +[source,json] +---- +{ + "all_of": { + "ordered": true, + "max_gaps": 2, + "intervals": [ + { "match": { "query": "apache solr" } }, + { "term": { "value": "search" } } + ] + } +} +---- + +=== `any_of` + +Matches documents where at least one of the supplied intervals matches. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`intervals` +|Yes +|— +|Array of rule objects, any of which may match. + +|`filter` +|No +|— +|A <> to apply after matching. +|=== + +Example: + +[source,json] +---- +{ + "any_of": { + "intervals": [ + { "term": { "value": "apache" } }, + { "term": { "value": "lucene" } } + ] + } +} +---- + +=== `at_least` + +Matches documents where at least `min_should_match` of the supplied intervals match. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`min_should_match` +|Yes +|— +|Minimum number of interval rules that must match. + +|`intervals` +|Yes +|— +|Array of rule objects. +|=== + +Example: + +[source,json] +---- +{ + "at_least": { + "min_should_match": 2, + "intervals": [ + { "term": { "value": "apache" } }, + { "term": { "value": "solr" } }, + { "term": { "value": "search" } } + ] + } +} +---- + +== Positional Constraints + +=== `max_width` + +Restricts a source interval to span at most `width` positions. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`width` +|Yes +|— +|Maximum allowed span width in positions. + +|`source` +|Yes +|— +|A rule object to constrain. +|=== + +Example: + +[source,json] +---- +{ + "max_width": { + "width": 5, + "source": { "match": { "query": "apache solr" } } + } +} +---- + +=== `extend` + +Extends an interval by adding extra positions before and/or after it. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`before` +|No +|`0` +|Number of positions to extend before the interval. + +|`after` +|No +|`0` +|Number of positions to extend after the interval. + +|`source` +|Yes +|— +|A rule object to extend. +|=== + +Example: + +[source,json] +---- +{ + "extend": { + "before": 1, + "after": 1, + "source": { "term": { "value": "solr" } } + } +} +---- + +=== `within` + +Matches documents where a `source` interval occurs within `positions` of a `reference` interval. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`positions` +|Yes +|— +|Maximum number of positions separating the two intervals. + +|`source` +|Yes +|— +|The interval that must be near the reference. + +|`reference` +|Yes +|— +|The reference interval. +|=== + +Example: + +[source,json] +---- +{ + "within": { + "positions": 3, + "source": { "term": { "value": "solr" } }, + "reference": { "term": { "value": "apache" } } + } +} +---- + +=== `not_within` + +Matches documents where a `source` interval does *not* occur within `positions` of a `reference` interval. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`positions` +|Yes +|— +|Exclusion distance in positions. + +|`source` +|Yes +|— +|The interval that must not be near the reference. + +|`reference` +|Yes +|— +|The reference interval. +|=== + +Example: + +[source,json] +---- +{ + "not_within": { + "positions": 5, + "source": { "term": { "value": "slow" } }, + "reference": { "term": { "value": "solr" } } + } +} +---- + +=== `unordered_no_overlaps` + +Matches documents where two intervals appear in either order without overlapping. +Exactly two intervals must be supplied. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`intervals` +|Yes +|— +|Array of exactly two rule objects. +|=== + +Example: + +[source,json] +---- +{ + "unordered_no_overlaps": { + "intervals": [ + { "term": { "value": "apache" } }, + { "term": { "value": "solr" } } + ] + } +} +---- + +=== `no_intervals` + +Always produces no intervals (matches no documents for the given rule). +Useful as a placeholder or for testing. + +[%autowidth,frame=none] +|=== +|Parameter |Required |Default |Description + +|`reason` +|No +|`"no_intervals rule"` +|An optional message explaining why this rule produces no intervals. +|=== + +Example: + +[source,json] +---- +{ "no_intervals": { "reason": "disabled for testing" } } +---- + +== Filter Operators + +The `match`, `all_of`, and `any_of` rules accept an optional `filter` parameter. +A filter restricts matches based on the positional relationship between the source interval and a second (filter) interval. + +The `filter` object contains exactly one of the following operators as its key, mapped to a nested rule object: + +[%autowidth,frame=none] +|=== +|Operator |Description + +|`after` +|Source must appear after the filter interval. + +|`before` +|Source must appear before the filter interval. + +|`contained_by` +|Source must be contained within the filter interval. + +|`containing` +|Source must contain the filter interval. + +|`not_contained_by` +|Source must not be contained within the filter interval. + +|`not_containing` +|Source must not contain the filter interval. + +|`not_overlapping` +|Source must not overlap the filter interval. + +|`overlapping` +|Source must overlap the filter interval. +|=== + +Example — match "solr" only when it appears after "apache": + +[source,json] +---- +{ + "match": { + "query": "solr", + "filter": { + "after": { "term": { "value": "apache" } } + } + } +} +---- + +== Full Example + +Find documents where the `title` field contains the phrase "apache solr" followed within 5 positions by the word "search": + +[source,text] +---- +q={!intervals df=title}$titleQuery +---- + +[source,text] +---- +json={ + "json_queries": { + "titleQuery": { + "all_of": { + "ordered": true, + "max_gaps": 5, + "intervals": [ + { "match": { "query": "apache solr", "max_gaps": 0, "ordered": true } }, + { "term": { "value": "search" } } + ] + } + } + } +} +---- diff --git a/solr/solr-ref-guide/modules/query-guide/pages/json-request-api.adoc b/solr/solr-ref-guide/modules/query-guide/pages/json-request-api.adoc index 7b56b48f3158..30ac4429cb11 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/json-request-api.adoc +++ b/solr/solr-ref-guide/modules/query-guide/pages/json-request-api.adoc @@ -254,6 +254,8 @@ curl "http://localhost:8983/solr/techproducts/query?fl=name,price&q=memory&rows= Usage of `queries` key is described in xref:json-query-dsl.adoc#additional-queries[Additional Queries]. +`json_queries` key is used by xref:intervals-query-parser.adoc[Intervals Query Parser]. + === Parameter Substitution / Macro Expansion Of course request templating via parameter substitution works fully with JSON request bodies or parameters as well. diff --git a/solr/solr-ref-guide/modules/query-guide/pages/other-parsers.adoc b/solr/solr-ref-guide/modules/query-guide/pages/other-parsers.adoc index 7a8b0bd09183..569639570a62 100644 --- a/solr/solr-ref-guide/modules/query-guide/pages/other-parsers.adoc +++ b/solr/solr-ref-guide/modules/query-guide/pages/other-parsers.adoc @@ -717,6 +717,15 @@ Note the name of the cache should be the field name prefixed by "`hash_`". ---- +== Intervals Query Parser + +The `IntervalsQParserPlugin` builds Lucene interval queries from a JSON DSL description. +Interval queries express positional constraints between terms, such as requiring that terms appear within a specified number of positions of each other or in a particular order. + +Invoked with the syntax `{!intervals df=}$`, where `$` is a required reference to an entry in the `json_queries` map supplied in the JSON request body. + +Details of this query parser are in the section xref:intervals-query-parser.adoc[]. + == Join Query Parser The Join Query Parser allows users to run queries that normalize relationships between documents, similar to SQL-style joins. diff --git a/solr/solr-ref-guide/modules/query-guide/querying-nav.adoc b/solr/solr-ref-guide/modules/query-guide/querying-nav.adoc index d83ab083a839..8604457592e3 100644 --- a/solr/solr-ref-guide/modules/query-guide/querying-nav.adoc +++ b/solr/solr-ref-guide/modules/query-guide/querying-nav.adoc @@ -35,6 +35,7 @@ ** xref:dense-vector-search.adoc[] *** xref:text-to-vector.adoc[] ** xref:other-parsers.adoc[] +*** xref:intervals-query-parser.adoc[] ** xref:sql-query.adoc[] *** xref:jdbc-dbvisualizer.adoc[] *** xref:jdbc-squirrel.adoc[]