Author: thomasm
Date: Thu Jan 18 11:05:25 2018
New Revision: 1821481
URL: http://svn.apache.org/viewvc?rev=1821481&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.md
jackrabbit/oak/trunk/oak-doc/src/site/site.xml
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=1821481&r1=1821480&r2=1821481&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
Jan 18 11:05:25 2018
@@ -18,11 +18,22 @@
## Oak SQL-2 Query Grammar
* [Query](#query)
+* [Column](#column)
+* [Selector](#selector)
+* [Join](#join)
+* [Constraint](#constraint)
+* [And Condition](#andCondition)
+* [Condition](#condition)
+* [Comparison](#comparison)
+* [In Comparison](#inComparison)
+* [Static Operand](#staticOperand)
+* [Ordering](#ordering)
+* [Dynamic Operand](#dynamicOperand)
* [Options](#options)
* [Explain](#explain)
* [Measure](#measure)
-
+<hr />
<h3 id="query">Query</h3>
<h4>
@@ -43,6 +54,7 @@ ORDER BY may use an index.
If there is no index for the given sort order,
then the result is fully read in memory and sorted before returning the first
row.
+<hr />
<h3 id="column">Column</h3>
<h4>
@@ -53,7 +65,7 @@ then the result is fully read in memory
<br/> } [ AS aliasName ]
</h4>
-
+<hr />
<h3 id="selector">Selector</h3>
<h4>
@@ -62,12 +74,11 @@ nodeTypeName [ AS selectorName ]
The nodetype name can be either a primary nodetype or a mixin nodetype.
-
-
+<hr />
<h3 id="join">Join</h3>
<h4>
-{ INNER | { LEFT | RIGHT } OUTER } JOIN rightSelector ON
+{ INNER | { LEFT | RIGHT } OUTER } JOIN <a href="#selector">rightSelector</a>
ON
<br/> { selectorName . propertyName = joinSelectorName . joinPropertyName }
<br/> | { ISSAMENODE( selectorName , joinSelectorName [ , selectorPathName ] )
}
<br/> | { ISCHILDNODE( childSelectorName , parentSelectorName ) }
@@ -79,14 +90,15 @@ A left outer join will return entries th
A right outer join will return entries that don't have matching nodes on the
left selector.
For outer joins, all the properties of the selector that doesn't have a
matching node are null.
-
+<hr />
<h3 id="constraint">Constraint</h3>
<h4>
-andCondition [ { OR andCondition } [...] ]
+<a href="#andCondition">andCondition</a> [ { OR <a
href="#andCondition">andCondition</a> } [...] ]
</h4>
-OR conditions of the form "X = 1 OR X = 2" are automatically converted to "X
IN(1, 2)".
+OR conditions of the form "X = 1 OR X = 2" are automatically converted to "X
IN(1, 2)",
+and can use the same an index.
OR conditions of the form "X = 1 OR Y = 2" are more complicated.
Oak will try two options: first, what is the expected cost to use a UNION query
@@ -95,11 +107,11 @@ If using UNION results in a lower estima
This can be the case, for example, if there are two distinct indexes,
one on X and another on Y.
-
+<hr />
<h3 id="andCondition">And Condition</h3>
<h4>
-condition [ { AND condition } [...] ]
+<a href="#condition">condition</a> [ { AND <a href="#condition">condition</a>
} [...] ]
</h4>
A special case (not found in relational databases) is
@@ -107,15 +119,16 @@ AND conditions of the form "X = 1 AND X
They will match nodes with multi-valued properties,
where the property value contains both 1 and 2.
+<hr />
<h3 id="condition">Condition</h3>
<h4>
-comparison
-<br/> inComparison
-<br/> | NOT constraint
-<br/> | ( constraint )
+<a href="#comparison">comparison</a>
+<br/> <a href="#inComparison">inComparison</a>
+<br/> | NOT <a href="#constraint">constraint</a>
+<br/> | ( <a href="#constraint">constraint</a> )
<br/> | [ selectorName . ] propertyName IS [ NOT ] NULL
-<br/> | CONTAINS( { { [ selectorName . ] propertyName } | { selectorName . * }
} , fulltextSearchExpression )
+<br/> | CONTAINS( { { [ selectorName . ] propertyName } | { selectorName . * }
} , staticOperand )
<br/> | { ISSAMENODE | ISCHILDNODE | ISDESCENDANTNODE } ( [ selectorName , ]
pathString )
<br/> | SIMILAR ( [ selectorName . ] { propertyName | * } , staticOperand )
<br/> | NATIVE ( [ selectorName , ] language , staticOperand )
@@ -123,21 +136,42 @@ comparison
<br/> | SUGGEST ( [ selectorName , ] staticOperand )
</h4>
+NOT conditions can not typically use an index.
+
+CONTAINS: see <a href="query-engine.html#Full-Text_Queries">Full-Text
Queries</a>.
+
+SIMILAR: see <a href="query-engine.html#Similarity_Queries">Similarity
Queries</a>.
+NATIVE: see <a href="query-engine.html#Native_Queries">Native Queries</a>.
+
+SPELLCHECK: see <a href="query-engine.html#Spellchecking">Spellchecking</a>.
+
+SUGGEST: see <a href="query-engine.html#Suggestions">Suggestions</a>.
+
+<hr />
<h3 id="comparison">Comparison</h3>
<h4>
-dynamicOperand { = | <> | < | <= | > | >= | LIKE }
staticOperand
+<a href="#dynamicOperand">dynamicOperand</a>
+{ = | <> | < | <= | > | >= | LIKE }
+<a href="#staticOperand">staticOperand</a>
</h4>
+LIKE: when comparing with LIKE, the wildcards characters are _ (any one
character)
+and % (any characters). An index is used,
+except if the operand starts with a wildcard.
+To search for the characters % and _, the characters need to be escaped using
\ (backslash).
+
+Comparison using <, >, >=, and <= can use an index if the property
in the index is ordered.
+<hr />
<h3 id="inComparison">In Comparison</h3>
<h4>
-dynamicOperand IN ( staticOperand [, ...] )
+<a href="#dynamicOperand">dynamicOperand</a> IN ( <a
href="#staticOperand">staticOperand</a> [, ...] )
</h4>
-
+<hr />
<h3 id="staticOperand">Static Operand</h3>
<h4>
@@ -158,11 +192,18 @@ literal
<br/> | URI } )
</h4>
+A string (text) literal starts and ends with a single quote.
+Two single quotes can be used to create a single quote inside a string.
+
+Example:
+'John''s car'
+
+<hr />
<h3 id="ordering">Ordering</h3>
<h4>
-dynamicOperand [ ASC | DESC ]
+<a href="#dynamicOperand">dynamicOperand</a> [ ASC | DESC ]
</h4>
Ordering by an indexed property will use that index if possible.
@@ -175,6 +216,7 @@ As a special case, sorting by "jcr:score
If for some reason you want to enforce sorting by "jcr:score", then
you can use the workaround to order by "LOWER([jcr:score]) DESC".
+<hr />
<h3 id="dynamicOperand">Dynamic Operand</h3>
<h4>
@@ -197,6 +239,7 @@ It allows to filter for all properties w
Example: the condition `PROPERTY(*, Reference) = $uuid` will search for any
property of type
`Reference`.
+<hr />
<h3 id="options">Options</h3>
<h4>
@@ -218,6 +261,7 @@ INDEX TAG: by default, queries will use
To only consider some of the indexes, add tags (a multi-valued String
property) to the index(es) of choice,
and specify this tag in the query.
+<hr />
<h3 id="explain">Explain Query</h3>
<h4>
@@ -242,7 +286,7 @@ Result:
This means the property index named "uuid" is used for this query.
The expected cost (roughly the number of uncached I/O operations) is 2.
-
+<hr />
<h3 id="measure">Measure</h3>
<h4>
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=1821481&r1=1821480&r2=1821481&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
Jan 18 11:05:25 2018
@@ -17,72 +17,207 @@
## Oak XPath Query Grammar
-### XPath
-
-*
-
-### SQL-2
-
* [Query](#query)
+* [Filter](#filter)
+* [Constraint](#constraint)
+* [And Condition](#andCondition)
+* [Condition](#condition)
+* [Comparison](#comparison)
+* [Static Operand](#staticOperand)
+* [Ordering](#ordering)
+* [Dynamic Operand](#dynamicOperand)
+* [Options](#options)
* [Explain](#explain)
* [Measure](#measure)
-
+<hr />
<h3 id="query">Query</h3>
<h4>
-SELECT [ DISTINCTÂ ] { * | { <a href="#column">column</a> [ , ... ] } }
-<br/> FROM { <a href="#selector">selector</a> [ <a href="#join">join</a> ... ]
}
-<br/> [ WHERE <a href="#constraint">constraint</a> ]
-<br/> [ UNION [ ALLÂ ]Â <a href="#query">query</a> ]
-<br/> [ ORDER BY { <a href="#ordering">ordering</a> [ , ... ] } ]
+/jcr:root { <a href="#filter">filter</a> [ ... ] } }
+<br/> [ ( <a href="#column">column</a> [ | ... ] } ) ]
+<br/> [ order by { <a href="#ordering">ordering</a> [ , ... ] } ]
<br/> [ <a href="#options">queryOptions</a> ]
</h4>
-DISTINCT ensures each row is only returned once.
-
-UNION combines the result of this query with the results of another query,
-where UNION ALL does not remove duplicate.
-
-ORDER BY may use an index.
+"order by" may use an index.
If there is no index for the given sort order,
then the result is fully read in memory and sorted before returning the first
row.
+The column list only needs to contain non-standard columns,
+such as "rep:excerpt" or "rep:spellcheck".
+All properties of the node are returned in any case.
+
+The "/jcr:root" means the root node.
+It is recommended that all XPath queries start with this term.
+
+<hr />
+<h3 id="filter">Filter</h3>
+
+<h4>
+/ <a href="#filter">directChildNodeFilter</a>
+<br/> | // <a href="#filter">descendantNodeFilter</a>
+<br/> | element( [ * | nodeName ] [, nodeType] )
+<br/> | *
+<br/> | '[' <a href="#constraint">constraint</a> ']'
+</h4>
+
+<hr />
+<h3 id="constraint">Constraint</h3>
+
+<h4>
+<a href="#andCondition">andCondition</a> [ { or <a
href="#andCondition">andCondition</a> } [...] ]
+</h4>
+
+"or" conditions of the form "@x = 1 or @x = 2" can use the same index.
+
+"or" conditions of the form "@x = 1 or @y = 2" are more complicated.
+Oak will convert them to a "union" query
+(one query with @x = 1, and a second query with @y = 2).
+
+<hr />
+<h3 id="andCondition">And Condition</h3>
+
+<h4>
+<a href="#condition">condition</a> [ { and <a href="#condition">condition</a>
} [...] ]
+</h4>
+
+A special case (not found in relational databases) is
+"and" conditions of the form "@x = 1 and @x = 2".
+They will match nodes with multi-valued properties,
+where the property value contains both 1 and 2.
+
+<hr />
+<h3 id="condition">Condition</h3>
+
+<h4>
+<a href="#comparison">comparison</a>
+<br/> <a href="#inComparison">inComparison</a>
+<br/> | [ fn:not (<a href="#constraint">constraint</a>)
+<br/> | ( <a href="#constraint">constraint</a> )
+<br/> | jcr:contains( [ { property | . } , ] fulltextSearchExpression )
+<br/> | jcr:like( dynamicOperand , staticOperand )
+<br/> | rep:similar ( propertyName , staticOperand )
+<br/> | rep:native ( language , staticOperand )
+<br/> | rep:spellcheck ( staticOperand )
+<br/> | rep:suggest ( staticOperand )
+</h4>
+
+"fn:not" conditions can not typically use an index.
+
+"jcr:contains": see <a href="query-engine.html#Full-Text_Queries">Full-Text
Queries</a>.
+
+"jcr:like": the wildcards characters are _ (any one character)
+and % (any characters). An index is used,
+except if the operand starts with a wildcard.
+To search for the characters % and _, the characters need to be escaped using
\ (backslash).
+
+"rep:similar": see <a href="query-engine.html#Similarity_Queries">Similarity
Queries</a>.
+
+"rep:native": see <a href="query-engine.html#Native_Queries">Native
Queries</a>.
+
+"rep:spellcheck": see <a
href="query-engine.html#Spellchecking">Spellchecking</a>.
+
+"rep:suggest": see <a href="query-engine.html#Suggestions">Suggestions</a>.
+
+<hr />
+<h3 id="comparison">Comparison</h3>
+
+<h4>
+<a href="#dynamicOperand">dynamicOperand</a>
+{ = | <> | < | <= | > | >= }
+<a href="#staticOperand">staticOperand</a>
+</h4>
+
+Comparison using <, >, >=, and <= can use an index if the property
in the index is ordered.
+
+<hr />
+<h3 id="staticOperand">Static Operand</h3>
+
+<h4>
+literal
+<br/> | $ bindVariableName
+<br/> | xs:dateTime ( literal )
+</h4>
+
+A string (text) literal starts and ends with a single quote.
+Two single quotes can be used to create a single quote inside a string.
+
+Example:
+
+'John''s car'
+
+<hr />
+<h3 id="ordering">Ordering</h3>
+
+<h4>
+<a href="#dynamicOperand">dynamicOperand</a> [ ascending | descending ]
+</h4>
+
+Ordering by an indexed property will use that index if possible.
+If there is no index that can be used for the given sort order,
+then the result is fully read in memory and sorted there.
+
+As a special case, sorting by "jcr:score" in descending order is ignored
+(removed from the list), as this is what the fulltext index does anyway
+(and if no fulltext index is used, then the score doesn't apply).
+If for some reason you want to enforce sorting by "jcr:score", then
+you can use the workaround to order by "fn:lowercase(@jcr:score) descending".
+
+<hr />
+<h3 id="dynamicOperand">Dynamic Operand</h3>
+
+<h4>
+[ relativePath / ] { @propertyName | * }
+<br/> | fn:string-length ( dynamicOperand )
+<br/> | { fn:name | fn:local-name } ( [ . ] )
+<br/> | jcr:score ( )
+<br/> | { fn:lower-case | fn:upper-case } ( dynamicOperand )
+<br/> | fn:coalesce ( dynamicOperand1, dynamicOperand2 )
+</h4>
+
+The selector name is only needed if the query contains multiple selectors.
+
+"fn:coalesce": this returns the first operand if it is not null,
+and the second operand otherwise.
+`@since Oak 1.8`
+
+<hr />
<h3 id="options">Options</h3>
<h4>
-OPTION( {
-<br/> TRAVERSAL { OK | WARN | FAIL | DEFAULT } |
-<br/> INDEX TAG tagName
+option( {
+<br/> traversal { ok | warn | fail | default } |
+<br/> index tag tagName
<br/> } [ , ... ] )
</h4>
-TRAVERSAL: by default, queries without index will log a warning,
+"traversal": by default, queries without index will log a warning,
except if the configuration option `QueryEngineSettings.failTraversal` is
changed
The traversal option can be used to change the behavior of the given query:
-OK to not log a warning,
-WARN to log a warning,
-FAIL to fail the query, and
-DEFAULT to use the default setting.
+"ok" to not log a warning,
+"warn" to log a warning,
+"fail" to fail the query, and
+"default" to use the default setting.
-INDEX TAG: by default, queries will use the index with the lowest expected
cost (as in relational databases).
+"index tag": by default, queries will use the index with the lowest expected
cost (as in relational databases).
To only consider some of the indexes, add tags (a multi-valued String
property) to the index(es) of choice,
and specify this tag in the query.
+<hr />
<h3 id="explain">Explain Query</h3>
<h4>
-EXPLAIN [MEASURE] { <a href="#query">query</a> }
+explain [measure] { <a href="#query">query</a> }
</h4>
Does not run the query, but only computes and returns the query plan.
-With EXPLAIN MEASURE, the expected cost is calculated as well.
+With "explain measure", the expected cost is calculated as well.
In both cases, the query result will only have one column called 'plan', and
one row that contains the plan.
Examples:
- EXPLAIN MEASURE
- SELECT * FROM [nt:base] WHERE [jcr:uuid] = 1
+ exlplain measure /jcr:root//*[@jcr:uuid = 'x']
Result:
@@ -93,11 +228,11 @@ Result:
This means the property index named "uuid" is used for this query.
The expected cost (roughly the number of uncached I/O operations) is 2.
-
+<hr />
<h3 id="measure">Measure</h3>
<h4>
-MEASURE { <a href="#query">query</a> }
+measure { <a href="#query">query</a> }
</h4>
Runs the query, but instead of returning the result, returns the number of
rows traversed.
@@ -107,8 +242,7 @@ and one per selector used in the query.
Examples:
- MEASURE
- SELECT * FROM [nt:base] WHERE [jcr:uuid] = 1
+ measure /jcr:root//*[@jcr:uuid = 'x']
Result:
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md?rev=1821481&r1=1821480&r2=1821481&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query.md Thu Jan 18
11:05:25 2018
@@ -24,6 +24,8 @@ the repository will be traversed. That i
but probably be very slow.
* [The Query Engine](./query-engine.html)
+* [XPath Grammar](./grammar-xpath.html)
+* [SQL-2 Grammar](./query-sql2.html)
* [Troubleshooting](./query-troubleshooting.html)
* [Flags](./flags.html)
Modified: jackrabbit/oak/trunk/oak-doc/src/site/site.xml
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/site.xml?rev=1821481&r1=1821480&r2=1821481&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/site.xml (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/site.xml Thu Jan 18 11:05:25 2018
@@ -52,6 +52,8 @@ under the License.
<item href="plugins/blobstore.html" name="Blob Storage" />
<item href="query/query.html" name="Query" collapse="false">
<item href="query/query-engine.html" name="Query Engine" />
+ <item href="query/grammar-xpath.html" name="XPath Grammar" />
+ <item href="query/grammar-sql2.html" name="SQL-2 Grammar" />
<item href="query/query-troubleshooting.html" name="Troubleshooting" />
<item href="query/indexing.html" name="Indexing" />
<item href="query/lucene.html" name="Lucene Index" />
