You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by dw...@apache.org on 2021/03/10 09:59:26 UTC
[lucene] 13/50: SOLR-11506: Upgrade ref guide for Json Query DSL
This is an automated email from the ASF dual-hosted git repository.
dweiss pushed a commit to branch branch_7_1
in repository https://gitbox.apache.org/repos/asf/lucene.git
commit 08f75bec05fa32668db3be6fd6ea06e1d4c9e38b
Author: Cao Manh Dat <da...@apache.org>
AuthorDate: Thu Oct 19 09:12:53 2017 +0700
SOLR-11506: Upgrade ref guide for Json Query DSL
---
solr/solr-ref-guide/src/json-query-dsl.adoc | 172 ++++++++++++++++++++++++++
solr/solr-ref-guide/src/json-request-api.adoc | 166 +++++++++++++++++++++++++
solr/solr-ref-guide/src/other-parsers.adoc | 30 +++++
solr/solr-ref-guide/src/searching.adoc | 4 +-
4 files changed, 371 insertions(+), 1 deletion(-)
diff --git a/solr/solr-ref-guide/src/json-query-dsl.adoc b/solr/solr-ref-guide/src/json-query-dsl.adoc
new file mode 100644
index 0000000..615ff2c
--- /dev/null
+++ b/solr/solr-ref-guide/src/json-query-dsl.adoc
@@ -0,0 +1,172 @@
+= JSON Query DSL
+:page-shortname: json-query-dsl
+:page-permalink: json-query-dsl.html
+// 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 JSON Query DSL provides a simple yet powerful query language for the JSON Request API.
+
+== Structure of JSON Query DSL
+A JSON query can be:
+
+* A valid <<the-standard-query-parser.adoc#the-standard-query-parser,query string>> for default `deftype` (the standard query parser in most cases), as in, `title:solr`.
+
+* A valid <<local-parameters-in-queries.adoc#local-parameters-in-queries,local parameters>> query string, as in, `{!dismax qf=myfield}solr rocks`.
+
+* A JSON object with query parser name and arguments.
+The special key `v` in local parameters is replaced by key `query` in JSON object query, as in this example:
+
+[source,json]
+{
+ "query-parser-name" : {
+ "param1": "value1",
+ "param2": "value2",
+ "query": "a-json-query",
+ "another-param": "another-json-query"
+ }
+}
+
+== Basic Examples
+The four requests below are equivalent for searching for `solr lucene` in a field named `content`:
+
+. Passing all parameters on URI, with "lucene" as the default query parser.
++
+[source,bash]
+curl -XGET "http://localhost:8983/solr/books/query?q=content:(solr lucene)"
+
+. Using the JSON Query DSL with valid query string for default `deftype`, with "lucene" as default query parser.
++
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{"query": "content:(solr lucene)"}'
+
+. Using JSON Query DSL with valid local parameters query defining the "lucene" query parser.
++
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{"query": "{!lucene df=content v='solr lucene'}"}'
+
+
+. Using JSON Query DSL in verbose way, as a valid JSON object with parser name and arguments.
++
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{"query": {"lucene": {
+ "df": "content",
+ "query": "solr lucene"
+ }
+ }}'
+
+Note that the JSON query in the examples above is provided under the key `query` of <<json-request-api.adoc#json-request-api,JSON Request API>>.
+
+== Nested Queries
+Some query parsers accept a query as an argument. JSON Query DSL makes it easier to write and read such complex query.
+
+The three requests below are equivalent for wrapping the above example query (searching for `solr lucene` in field `content`) with a boost query:
+
+. Passing all parameters on URI.
++
+[source,bash]
+http://localhost:8983/solr/books/query?q={!boost b=log(popularity) v='{!lucene df=content}(lucene solr)'}
+
+. Converted into JSON Query DSL with use of local parameters.
+As you can see, the special key `v` is replaced by key `query`.
++
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{
+ "query" : {
+ "boost": {
+ "query": {!lucene df=content}(lucene solr),
+ "b": "log(popularity)"
+ }
+ }
+}'
+
+. Using a verbose JSON Query DSL without local parameters.
++
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{
+ "query": {
+ "boost": {
+ "query": {
+ "lucene": {
+ "df": "content",
+ "query": "solr lucene"
+ }
+ },
+ "b": "log(popularity)"
+ }
+ }
+}'
+
+== Compound Queries
+With the support of the <<other-parsers.adoc#boolean-query-parser,BoolQParser>>, the JSON Query DSL can create a very powerful nested query.
+
+This query searches for books where `content` contains `lucene` or `solr`, `title` contains `solr` and their `ranking` must larger than 3.0:
+
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{
+ "query": {
+ "bool": {
+ "must": [
+ "title:solr" ,
+ {"lucene": {"df: "content", query: "lucene solr"}}
+ ],
+ "must_not": [
+ {"frange": {"u": "3.0", query: "ranking"}}
+ ]
+ }
+ }
+}'
+
+If lucene is the default query parser query, the above can be rewritten in much less verbose way as in:
+
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{
+ "query": {
+ "bool": {
+ "must": [
+ "title:solr",
+ "content:(lucene solr)"
+ ],
+ "must_not": "{!frange u:3.0}ranking"
+ }
+ }
+}'
+
+== Use JSON Query DSL in JSON Request API
+JSON Query DSL is not only supported with the key `query` but also with the key `filter` of the <<json-request-api.adoc#json-request-api,JSON Request API>>.
+
+For example, the above query can be rewritten using filter clause like this:
+
+[source,bash]
+curl -XGET http://localhost:8983/solr/books/query -d '
+{
+ "query": {
+ "bool": {
+ "must_not": "{!frange u:3.0}ranking"
+ }
+ },
+ "filter: [
+ "title:solr",
+ { "lucene" : {"df: "content", query : "lucene solr" }}
+ ]
+}'
diff --git a/solr/solr-ref-guide/src/json-request-api.adoc b/solr/solr-ref-guide/src/json-request-api.adoc
new file mode 100644
index 0000000..dcddb24
--- /dev/null
+++ b/solr/solr-ref-guide/src/json-request-api.adoc
@@ -0,0 +1,166 @@
+= JSON Request API
+:page-shortname: json-request-api
+:page-permalink: json-request-api.html
+:page-children: json-query-dsl
+// 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 JSON Request API allows a JSON body to be passed for the entire search request.
+
+Here's an example of a search request using query parameters only:
+[source,bash]
+curl "http://localhost:8983/solr/techproducts/query?q=memory&fq=inStock:true"
+
+The same request when passed as JSON in the body:
+[source,bash]
+curl http://localhost:8983/solr/techproducts/query -d '
+{
+ "query" : "memory",
+ "filter" : "inStock:true"
+}'
+
+== Passing JSON via Request Parameter
+It may sometimes be more convenient to pass the JSON body as a request parameter rather than in the actual body of the HTTP request. Solr treats a `json` parameter the same as a JSON body.
+
+[source,bash]
+curl http://localhost:8983/solr/techproducts/query -d 'json={"query":"memory"}'
+
+== Smart Merging of Multiple JSON Parameters
+Multiple `json` parameters in a single request are merged before being interpreted.
+
+* Single-valued elements are overwritten by the last value.
+
+* Multi-valued elements like fields and `filter` are appended.
+
+* Parameters of the form `json.<path>=<json_value>` are merged in the appropriate place in the hierarchy. For example a `json.facet` parameter is the same as `facet` within the JSON body.
+
+* A JSON body, or straight `json` parameters are always parsed first, meaning that other request parameters come after, and overwrite single valued elements.
+
+Smart merging gives the best of both worlds…the structure of JSON with the ability to selectively separate out / decompose parts of the request!
+
+=== Simple Example
+[source,bash]
+curl 'http://localhost:8983/solr/techproducts/query?json.limit=5&json.filter="cat:electronics"' -d '
+{
+ query: "memory",
+ limit: 10,
+ filter: "inStock:true"
+}'
+
+Is equivalent to:
+
+[source,bash]
+curl http://localhost:8983/solr/techproducts/query -d '
+{
+ query: "memory",
+ limit: 5, // this single-valued parameter was overwritten.
+ filter: ["inStock:true","cat:electronics"] // this multi-valued parameter was appended to.
+}'
+
+=== Facet Example
+In fact, you don’t even need to start with a JSON body for smart merging to be very useful. Consider the following request composed entirely of request params:
+
+[source,bash]
+curl http://localhost:8983/solr/techproducts/query -d 'q=*:*&rows=1&
+ json.facet.avg_price="avg(price)"&
+ json.facet.top_cats.terms={field:"cat",limit:5}'
+
+That is equivalent to having the following JSON body or `json` parameter:
+
+[source,json]
+{
+ "facet": {
+ "avg_price": "avg(price)",
+ "top_cats": {
+ "terms": {
+ "field": "cat",
+ "limit": 5
+ }}}}
+
+=== Debugging
+
+If you want to see what your merged/parsed JSON looks like, you can turn on debugging (`debug=true`), and it will come back under the "json" key along with the other debugging information.
+
+== Passing Parameters via JSON
+We can also pass normal query request parameters in the JSON body within the params block:
+
+[source,bash]
+curl "http://localhost:8983/solr/techproducts/query?fl=name,price"-d '
+{
+ params: {
+ q: "memory",
+ rows: 1
+ }
+}'
+
+Which is equivalent to
+
+[source,bash]
+curl "http://localhost:8983/solr/techproducts/query?fl=name,price&q=memory&rows=1"
+
+== Parameters Mapping
+Right now only some standard query parameters have JSON equivalents. Unmapped parameters can be passed through request parameters or `params` block as shown above.
+
+.Standard query parameters to JSON field
+|===
+|Query parameters |JSON field equivalent
+
+|`q`
+|`query`
+
+|`fq`
+|`filter`
+
+|`offset`
+|`start`
+
+|`limit`
+|`rows`
+
+|`sort`
+|`sort`
+
+|`json.facet`
+|`facet`
+|===
+
+== Error Detection
+
+Because we didn’t pollute the root body of the JSON request with the normal Solr request parameters (they are all contained in the params block), we now have the ability to validate requests and return an error for unknown JSON keys.
+
+[source,bash]
+curl http://localhost:8983/solr/techproducts/query -d '
+{
+ query : "memory",
+ fulter : "inStock:true" // oops, we misspelled "filter"
+}'
+
+And we get an error back containing the error string:
+
+[source,text]
+"Unknown top-level key in JSON request : fulter"
+
+== Parameter Substitution / Macro Expansion
+Of course request templating via parameter substitution works fully with JSON request bodies or parameters as well.
+For example:
+
+[source,bash]
+curl "http://localhost:8983/solr/techproducts/query?FIELD=text&TERM=memory&HOWMANY=10" -d '
+{
+ query:"${FIELD}:${TERM}",
+ limit:${HOWMANY}
+}'
diff --git a/solr/solr-ref-guide/src/other-parsers.adoc b/solr/solr-ref-guide/src/other-parsers.adoc
index c339135..eda5214 100644
--- a/solr/solr-ref-guide/src/other-parsers.adoc
+++ b/solr/solr-ref-guide/src/other-parsers.adoc
@@ -139,6 +139,36 @@ Instead, you should use a sibling mandatory clause as a filter:
You can optionally use the `score` local parameter to return scores of the subordinate query. The values to use for this parameter define the type of aggregation, which are `avg` (average), `max` (maximum), `min` (minimum), `total (sum)`. Implicit default is `none` which returns `0.0`.
+== Boolean Query Parser
+
+The `BoolQParser` creates a Lucene `BooleanQuery` which is a boolean combination of other queries. Sub-queries along with their typed occurrences indicate how documents will be matched and scored.
+
+*Parameters*
+
+`must`::
+A list of queries that *must* appear in matching documents and contribute to the score.
+
+`must_not`::
+A list of queries that *must not* appear in matching documents.
+
+`should`::
+A list of queries *should* appear in matching documents. For a BooleanQuery with no `must` queries, one or more `should` queries must match a document for the BooleanQuery to match.
+
+`filter`::
+A list of queries that *must* appear in matching documents. However, unlike `must`, the score of filter queries is ignored.
+
+*Examples*
+
+[source,text]
+----
+{!bool must=foo must=bar}
+----
+
+[source,text]
+----
+{!bool filter=foo should=bar}
+----
+
== Boost Query Parser
`BoostQParser` extends the `QParserPlugin` and creates a boosted query from the input value. The main value is the query to be boosted. Parameter `b` is the function query to use as the boost. The query to be boosted may be of any type.
diff --git a/solr/solr-ref-guide/src/searching.adoc b/solr/solr-ref-guide/src/searching.adoc
index 426976c..62d3216 100644
--- a/solr/solr-ref-guide/src/searching.adoc
+++ b/solr/solr-ref-guide/src/searching.adoc
@@ -1,7 +1,7 @@
= Searching
:page-shortname: searching
:page-permalink: searching.html
-:page-children: overview-of-searching-in-solr, velocity-search-ui, relevance, query-syntax-and-parsing, faceting, highlighting, spell-checking, query-re-ranking, transforming-result-documents, suggester, morelikethis, pagination-of-results, collapse-and-expand-results, result-grouping, result-clustering, spatial-search, the-terms-component, the-term-vector-component, the-stats-component, the-query-elevation-component, response-writers, near-real-time-searching, realtime-get, exporting-re [...]
+:page-children: overview-of-searching-in-solr, velocity-search-ui, relevance, query-syntax-and-parsing, json-request-api, faceting, highlighting, spell-checking, query-re-ranking, transforming-result-documents, suggester, morelikethis, pagination-of-results, collapse-and-expand-results, result-grouping, result-clustering, spatial-search, the-terms-component, the-term-vector-component, the-stats-component, the-query-elevation-component, response-writers, near-real-time-searching, realtime [...]
// 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
@@ -32,6 +32,8 @@ This section describes how Solr works with search requests. It covers the follow
** <<function-queries.adoc#function-queries,Function Queries>>: Detailed information about parameters for generating relevancy scores using values from one or more numeric fields.
** <<local-parameters-in-queries.adoc#local-parameters-in-queries,Local Parameters in Queries>>: How to add local arguments to queries.
** <<other-parsers.adoc#other-parsers,Other Parsers>>: More parsers designed for use in specific situations.
+* <<json-request-api.adoc#json-request-api,JSON Request API>>: Overview of Solr's JSON Request API.
+** <<json-query-dsl.adoc#json-query-dsl,JSON Query DSL>>: Detailed information about a simple yet powerful query language for JSON Request API.
* <<faceting.adoc#faceting,Faceting>>: Detailed information about categorizing search results based on indexed terms.
* <<highlighting.adoc#highlighting,Highlighting>>: Detailed information about Solr's highlighting capabilities, including multiple underlying highlighter implementations.
* <<spell-checking.adoc#spell-checking,Spell Checking>>: Detailed information about Solr's spelling checker.