lucene-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From dsmi...@apache.org
Subject lucene-solr:branch_7_3: SOLR-12081: improve docs on query parsing RE embedded queries, uf
Date Tue, 13 Mar 2018 20:04:25 GMT
Repository: lucene-solr
Updated Branches:
  refs/heads/branch_7_3 f2b067cef -> 06f89a367


SOLR-12081: improve docs on query parsing RE embedded queries, uf

(cherry picked from commit e7dd3fc)


Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/06f89a36
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/06f89a36
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/06f89a36

Branch: refs/heads/branch_7_3
Commit: 06f89a3671e79e11d4b98565c28bb586203f4fef
Parents: f2b067c
Author: David Smiley <dsmiley@apache.org>
Authored: Tue Mar 13 16:01:57 2018 -0400
Committer: David Smiley <dsmiley@apache.org>
Committed: Tue Mar 13 16:04:16 2018 -0400

----------------------------------------------------------------------
 solr/CHANGES.txt                                |  2 +-
 .../src/common-query-parameters.adoc            |  2 +-
 solr/solr-ref-guide/src/solr-upgrade-notes.adoc |  2 +-
 .../src/the-extended-dismax-query-parser.adoc   | 42 +++++++-------------
 .../src/the-standard-query-parser.adoc          | 16 +++++---
 5 files changed, 28 insertions(+), 36 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/06f89a36/solr/CHANGES.txt
----------------------------------------------------------------------
diff --git a/solr/CHANGES.txt b/solr/CHANGES.txt
index cf2e963..553e89f 100644
--- a/solr/CHANGES.txt
+++ b/solr/CHANGES.txt
@@ -432,7 +432,7 @@ Upgrade Notes
 * SOLR-11501: The edismax parser by default no longer allows subqueries that specify a Solr
parser using either
   local-params, or the older _query_ magic field trick.  For example
   {!prefix f=myfield v=enterp}  or  _query_:"{!prefix f=myfield v=enterp}"   are not supported
by default anymore.
-  If you want to allow power-users to do this, set uf=*,_query_ or some other value that
includes _query_.
+  If you want to allow power-users to do this, set uf=* _query_ or some other value that
includes _query_.
   If you must have full backwards compatibility, use luceneMatchVersion=7.1.0 or something
earlier. (David Smiley)
 
 New Features

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/06f89a36/solr/solr-ref-guide/src/common-query-parameters.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/common-query-parameters.adoc b/solr/solr-ref-guide/src/common-query-parameters.adoc
index 83ea667..85c0a0a 100644
--- a/solr/solr-ref-guide/src/common-query-parameters.adoc
+++ b/solr/solr-ref-guide/src/common-query-parameters.adoc
@@ -102,7 +102,7 @@ fq=+popularity:[10 TO *] +section:0
 ----
 
 * The document sets from each filter query are cached independently. Thus, concerning the
previous examples: use a single `fq` containing two mandatory clauses if those clauses appear
together often, and use two separate `fq` parameters if they are relatively independent. (To
learn about tuning cache sizes and making sure a filter cache actually exists, see <<the-well-configured-solr-instance.adoc#the-well-configured-solr-instance,The
Well-Configured Solr Instance>>.)
-* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucene-query-parser-and-the-solr-standard-query-parser,filter(condition)
syntax>> inside the `fq` to cache clauses individually and - among other things - to
achieve union of cached filter queries.
+* It is also possible to use <<the-standard-query-parser.adoc#differences-between-lucene-s-classic-query-parser-and-solr-s-standard-query-parser,filter(condition)
syntax>> inside the `fq` to cache clauses individually and - among other things - to
achieve union of cached filter queries.
 
 * As with all parameters: special characters in an URL need to be properly escaped and encoded
as hex values. Online tools are available to help you with URL-encoding. For example: http://meyerweb.com/eric/tools/dencoder/.
 

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/06f89a36/solr/solr-ref-guide/src/solr-upgrade-notes.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solr-upgrade-notes.adoc b/solr/solr-ref-guide/src/solr-upgrade-notes.adoc
index 29cef2d..ffbcd0a 100644
--- a/solr/solr-ref-guide/src/solr-upgrade-notes.adoc
+++ b/solr/solr-ref-guide/src/solr-upgrade-notes.adoc
@@ -71,7 +71,7 @@ If you must have full backwards compatibility, use `luceneMatchVersion=7.1.0`
or
 
 * The eDisMax parser by default no longer allows subqueries that specify a Solr parser using
either local parameters, or the older `\_query_` magic field trick.
 +
-For example, `{!prefix f=myfield v=enterp}` or `\_query_:"{!prefix f=myfield v=enterp}"`
are not supported by default any longer. If you want to allow power-users to do this, set
`uf=*,\_query_` or some other value that includes `\_query_`.
+For example, `{!prefix f=myfield v=enterp}` or `\_query_:"{!prefix f=myfield v=enterp}"`
are not supported by default any longer. If you want to allow power-users to do this, set
`uf=* _query_` or some other value that includes `\_query_`.
 +
 If you need full backwards compatibility for the time being, use `luceneMatchVersion=7.1.0`
or something earlier.
 

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/06f89a36/solr/solr-ref-guide/src/the-extended-dismax-query-parser.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/the-extended-dismax-query-parser.adoc b/solr/solr-ref-guide/src/the-extended-dismax-query-parser.adoc
index ae4db27..35673f1 100644
--- a/solr/solr-ref-guide/src/the-extended-dismax-query-parser.adoc
+++ b/solr/solr-ref-guide/src/the-extended-dismax-query-parser.adoc
@@ -20,10 +20,10 @@ The Extended DisMax (eDisMax) query parser is an improved version of the
<<the-d
 
 In addition to supporting all the DisMax query parser parameters, Extended Dismax:
 
-* supports the full Lucene query parser syntax with the same enhancements as <<the-standard-query-parser.adoc#the-standard-query-parser,Solr's
standard query parser>>.
-** supports queries such as AND, OR, NOT, -, and +.
-** optionally treats "and" and "or" as "AND" and "OR" in Lucene syntax mode.
-** respects the 'magic field' names `\_val_` and `\_query_`. These are not a real fields
in the Schema, but if used it helps do special things (like a function query in the case of
`\_val_` or a nested query in the case of `\_query_`). If `\_val_` is used in a term or phrase
query, the value is parsed as a function.
+* supports <<the-standard-query-parser.adoc#the-standard-query-parser,Solr's standard
query parser>> syntax such as (non-exhaustive list):
+** boolean operators such as AND (+, &&), OR (||), NOT (-).
+** optionally treats lowercase "and" and "or" as "AND" and "OR" in Lucene syntax mode
+** optionally allows embedded queries using other query parsers or functions
 * includes improved smart partial escaping in the case of syntax errors; fielded queries,
+/-, and phrase queries are still supported in this mode.
 * improves proximity boosting by using word shingles; you do not need the query to match
all words in the document before proximity boosting is applied.
 * includes advanced stopword handling: stopwords are not required in the mandatory part of
the query but are still used in the proximity boosting part. If a query consists of all stopwords,
such as "to be or not to be", then all words are required.
@@ -70,7 +70,17 @@ This is similar to `ps` but overrides the slop factor used for `pf3`. If
not spe
 A Boolean parameter indicating if the `StopFilterFactory` configured in the query analyzer
should be respected when parsing the query. If this is set to `false`, then the `StopFilterFactory`
in the query analyzer is ignored.
 
 `uf`::
-Specifies which schema fields the end user is allowed to explicitly query. This parameter
supports wildcards. The default is to allow all fields, equivalent to `uf=\*`. To allow only
title field, use `uf=title`. To allow title and all fields ending with '_s', use `uf=title,*_s`.
To allow all fields except title, use `uf=*,-title`. To disallow all fielded searches, use
`uf=-*`.
+Specifies which schema fields the end user is allowed to explicitly query and to toggle whether
embedded Solr queries are supported.
+This parameter supports wildcards. Multiple fields must be separated by a space.
++
+The default is to allow all fields and no embedded Solr queries, equivalent to `uf=* -\_query_`.
+
+* To allow only title field, use `uf=title`.
+* To allow title and all fields ending with '_s', use `uf=title *_s`.
+* To allow all fields except title, use `uf=* -title`.
+* To disallow all fielded searches, use `uf=-*`.
+* To allow embedded Solr queries (e.g. `\_query_:"..."` or `\_val_:"..."` or `{!lucene ...}`),
+ you _must_ expressly enable this by referring to the magic field `\_query_` in `uf`.
 
 === Field Aliasing using Per-Field qf Overrides
 
@@ -193,25 +203,3 @@ q="Hans Anderson"
 A document that contains "Hans Anderson" will match, but a document that contains the middle
name "Christian" or where the name is written with the last name first ("Anderson, Hans")
won't. For those cases one could configure the query field `qs`, so that even if the user
searches for an explicit phrase query, a slop is applied.
 
 Finally, in addition to the phrase fields (`pf`) parameter, `edismax` also supports the `pf2`
and `pf3` parameters, for fields over which to create bigram and trigram phrase queries. The
phrase slop for these parameters' queries can be specified using the `ps2` and `ps3` parameters,
respectively. If you use `pf2`/`pf3` but `ps2`/`ps3`, then the phrase slop for these parameters'
queries will be taken from the `ps` parameter, if any.
-
-
-== Using the "Magic Fields" \_val_ and \_query_
-
-The Solr Query Parser's use of `\_val_` and `\_query_` differs from the Lucene Query Parser
in the following ways:
-
-* If the magic field name `\_val_` is used in a term or phrase query, the value is parsed
as a function.
-
-* It provides a hook into <<function-queries.adoc#function-queries,`FunctionQuery`>>
syntax. Quotes are necessary to encapsulate the function when it includes parentheses. For
example:
-+
-[source,text]
-----
-_val_:myfield
-_val_:"recip(rord(myfield),1,2,3)"
-----
-
-* The Solr Query Parser offers nested query support for any type of query parser (via QParserPlugin).
Quotes are often necessary to encapsulate the nested query if it contains reserved characters.
For example:
-+
-[source,text]
-----
-_query_:"{!dismax qf=myfield}how now brown cow"
-----

http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/06f89a36/solr/solr-ref-guide/src/the-standard-query-parser.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/the-standard-query-parser.adoc b/solr/solr-ref-guide/src/the-standard-query-parser.adoc
index 9d04729..fced285 100644
--- a/solr/solr-ref-guide/src/the-standard-query-parser.adoc
+++ b/solr/solr-ref-guide/src/the-standard-query-parser.adoc
@@ -318,9 +318,9 @@ Example:
 
 Comments may be nested.
 
-== Differences between Lucene Query Parser and the Solr Standard Query Parser
+== Differences between Lucene's Classic Query Parser and Solr's Standard Query Parser
 
-Solr's standard query parser differs from the Lucene Query Parser in the following ways:
+Solr's standard query parser originated as a variation of Lucene's "classic" QueryParser.
 It diverges in the following ways:
 
 * A `*` may be used for either or both endpoints to specify an open-ended range query
 ** `field:[* TO 100]` finds all field values less than or equal to 100
@@ -329,11 +329,15 @@ Solr's standard query parser differs from the Lucene Query Parser in
the followi
 * Pure negative queries (all clauses prohibited) are allowed (only as a top-level clause)
 ** `-inStock:false` finds all field values where inStock is not false
 ** `-field:[* TO *]` finds all documents without a value for field
-* A hook into FunctionQuery syntax. You'll need to use quotes to encapsulate the function
if it includes parentheses, as shown in the second example below:
-** `_val_:myfield`
-** `_val_:"recip(rord(myfield),1,2,3)"`
-* Support for using any type of query parser as a nested clause.
+* Support for embedded Solr queries (sub-queries) using any type of query parser as a nested
clause using the local-params syntax.
 ** `inStock:true OR {!dismax qf='name manu' v='ipod'}`
++
+Gotcha: Be careful not to start your query with `{!` at the very beginning, which changes
the parsing of the entire
+query string, which may not be what you want if there are additional clauses.  So flipping
the example above so the
+sub-query comes first would fail to work as expected without a leading space.
++
+Sub-queries can also be done with the magic field `\_query_` and for function queries with
the magic field `\_val_` but it
+should be considered deprecated since it is less clear.  Example: `\_val_:"recip(rord(myfield),1,2,3)"`
 * Support for a special `filter(...)` syntax to indicate that some query clauses should be
cached in the filter cache (as a constant score boolean query). This allows sub-queries to
be cached and re-used in other queries. For example `inStock:true` will be cached and re-used
in all three of the queries below:
 ** `q=features:songs OR filter(inStock:true)`
 ** `q=+manu:Apple +filter(inStock:true)`


Mime
View raw message