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