Author: thomasm
Date: Thu Feb 8 15:29:46 2018
New Revision: 1823566
URL: http://svn.apache.org/viewvc?rev=1823566&view=rev
Log:
OAK-6898 Query: grammar documentation / annotated railroad diagrams
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md?rev=1823566&r1=1823565&r2=1823566&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-sql2.md Thu
Feb 8 15:29:46 2018
@@ -76,6 +76,9 @@ Examples:
It is recommended to enclose property names in square brackets.
+For the "excerpt" property,
+see <a href="query-engine.html#Excerpts_and_Highlighting">Excerpts and
Highlighting</a>.
+
Not listed above are "special" properties such as "[jcr:path]" (the path),
"[jcr:score]" (the score),
"[rep:suggest()]".
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md?rev=1823566&r1=1823565&r2=1823566&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/grammar-xpath.md Thu
Feb 8 15:29:46 2018
@@ -140,9 +140,9 @@ rep:excerpt( [. | [ relativePath / ] @pr
<br/> | rep:facet ( [ relativePath / ] @propertyName )
</h4>
-"rep:excerpt": include the spellcheck column in the result.
+"rep:excerpt": include the excerpt in the result.
Since Oak version 1.8.1, optionally a property name can be specified.
-See also <a href="lucene.html#Property_Definitions">useInExcerpt</a>.
+See <a href="query-engine.html#Excerpts_and_Highlighting">Excerpts and
Highlighting</a>.
"rep:spellcheck": Include the spellcheck in the result.
See <a href="query-engine.html#Spellchecking">Spellchecking</a>.
@@ -155,6 +155,10 @@ See <a href="query-engine.html#Facets">F
Examples:
+ /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt())
+
+ /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt(@jcr:title) |
rep:excerpt())
+
/jcr:root/content//*[rep:suggest('in ')]/(rep:suggest())
/jcr:root/content//*[jcr:contains(@jcr:title, 'oak')]/(rep:facet(@tags))
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md?rev=1823566&r1=1823565&r2=1823566&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
(original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md Thu
Feb 8 15:29:46 2018
@@ -34,6 +34,7 @@ grep "^#.*$" src/site/markdown/query/que
* [Equality for Path Constraints](#Equality_for_Path_Constraints)
* [Slow Queries and Read Limits](#Slow_Queries_and_Read_Limits)
* [Full-Text Queries](#Full-Text_Queries)
+ * [Excerpts and Highlighting](#Excerpts_and_Highlighting)
* [Native Queries](#Native_Queries)
* [Similarity Queries](#Similarity_Queries)
* [Spellchecking](#Spellchecking)
@@ -335,6 +336,24 @@ For compatibility with Jackrabbit 2.x, s
That means the query `contains(., "word ''hello world'' word")` is supported.
New applications should not rely on this feature.
+### Excerpts and Highlighting
+
+If excerpts and highlighting is needed, then queries should contains the
"excerpt" property, as follows:
+
+ /jcr:root/content//*[jcr:contains(., 'test')]/(rep:excerpt())
+
+That way, the excerpt and highlighting features of Lucene are used.
+That is, if a Lucene index is configured for the query, and excerpts are
generated
+(see <a href="lucene.html#Property_Definitions">useInExcerpt</a>).
+On the other hand, If the query doesn't contain the excerpt property, for
example as follows:
+
+ /jcr:root/content//*[jcr:contains(., 'test')]
+
+and the excerpt is requested after running the query,
+then the SimpleExcerptProvider utility is used, which generates excerpt from
the content, and does highlighting.
+This is not not recommended; specially highlighting is limited
+(eg. stopwords are ignored, highlighting is case sensitive).
+The same problem occurs if excerpts for properties are requested that are not
specified in the query.
### Native Queries
