Author: tommaso
Date: Fri Jan 29 15:03:46 2016
New Revision: 1727597
URL: http://svn.apache.org/viewvc?rev=1727597&view=rev
Log:
OAK-1736 - added missing doc for facets
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/lucene.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/query-engine.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/solr.md
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/lucene.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/lucene.md?rev=1727597&r1=1727596&r2=1727597&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/lucene.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/lucene.md Fri Jan 29
15:03:46 2016
@@ -1036,6 +1036,45 @@ Since Oak 1.3.11, the each suggestion wo
```
+#### Facets
+
+`@since Oak 1.3.14`
+
+Lucene property indexes can also be used for retrieving facets, in order to do
so the property _facets_ must be set to
+ _true_ on the property definition.
+
+```
+/oak:index/lucene-with-facets
+ - jcr:primaryType = "oak:QueryIndexDefinition"
+ - compatVersion = 2
+ - type = "lucene"
+ - async = "async"
+ + indexRules
+ - jcr:primaryType = "nt:unstructured"
+ + nt:base
+ + properties
+ - jcr:primaryType = "nt:unstructured"
+ + jcr:title
+ - facets = true
+ - propertyIndex = true
+```
+
+Specific facet related features for Lucene property index can be configured in
a separate _facets_ node below the
+ index definition.
+ By default ACL checks are always performed on facets by the Lucene property
index however this can be avoided by setting
+ the property _secure_ to _false_ in the _facets_ configuration node.
+```
+ + nt:base
+ + properties
+ - jcr:primaryType = "nt:unstructured"
+ + jcr:title
+ - facets = true
+ - propertyIndex = true
+ + facets
+ - secure = false
+```
+
+
#### Score Explanation
`@since Oak 1.3.12`
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=1727597&r1=1727596&r2=1727597&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 Fri
Jan 29 15:03:46 2016
@@ -216,6 +216,11 @@ Clients wanting to obtain suggestions co
if (it.hasNext()) {
suggestions = row.getValue("rep:suggest()").getString()
}
+
+The `suggestions` String would be have the following pattern
`\[\{(term\=)[\w|\W]+(\,weight\=)\d+\}(\,\{(term\=)[\w|\W]+(\,weight\=)\d+\})*\]`,
e.g.:
+
+ [{term=in 2015 a red fox is still a fox,weight=1.5}, {term=in 2015 my fox
is red, like mike's fox and john's fox,weight=0.7}]
+
`@since Oak 1.3.11` each suggestion would be returned per row.
@@ -229,13 +234,31 @@ Clients wanting to obtain suggestions co
}
If either Lucene or Solr were configured to provide the suggestions feature,
see [Enable suggestions in Lucene](lucene.html#Suggestions) and [Enable
-suggestions in Solr](solr.html#Suggestions), the `suggestions` String would be
have the following pattern
`\[\{(term\=)[\w|\W]+(\,weight\=)\d+\}(\,\{(term\=)[\w|\W]+(\,weight\=)\d+\})*\]`,
e.g.:
-
- [{term=in 2015 a red fox is still a fox,weight=1.5}, {term=in 2015 my fox
is red, like mike's fox and john's fox,weight=0.7}]
-
+suggestions in Solr](solr.html#Suggestions).
Note that suggested terms come already filtered according to calling user
privileges, so that users could see suggested
terms only coming from indexed content they are allowed to read.
+### Facets
+
+`@since Oak 1.3.14` Oak has support for
[facets](https://en.wikipedia.org/wiki/Faceted_search).
+Once enabled (see details for [Lucene](lucene.html#Facets) and/or
[Solr](solr.html#Suggestions) indexes) facets can be retrieved on properties
(backed by a proper
+field in Lucene / Solr) using the following snippet:
+
+ String sql2 = "select [jcr:path], [rep:facet(tags)] from [nt:base] " +
+ "where contains([jcr:title], 'oak');
+ Query q = qm.createQuery(sql2, Query.JCR_SQL2);
+ QueryResult result = q.execute();
+ FacetResult facetResult = new FacetResult(result);
+ Set<String> dimensions = facetResult.getDimensions(); // { "tags" }
+ List<FacetResult.Facet> facets = facetResult.getFacets("tags");
+ for (FacetResult.Facet facet : facets) {
+ String label = facet.getLabel();
+ int count = facet.getCount();
+ ...
+ }
+
+Nodes/Rows can still be retrieved from within the QueryResult object the usual
way.
+
### XPath to SQL2 Transformation
To support the XPath query language, such queries are internally converted to
SQL2.
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/solr.md
URL:
http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/solr.md?rev=1727597&r1=1727596&r2=1727597&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/solr.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/query/solr.md Fri Jan 29
15:03:46 2016
@@ -289,6 +289,20 @@ under the hood as it doesn't require any
More / different spellcheckers can be configured in Solr, as per [reference
documentation](https://cwiki.apache.org/confluence/display/solr/Spell+Checking).
+#### Facets
+
+`@since Oak 1.3.14`
+
+In order to enable proper usage of facets in Solr index the following fields
need to be added to the _schema.xml_
+
+ <dynamicField name="*_facet" type="string" indexed="false"
stored="false" docValues="true" multiValued="true"/>
+
+with either a match all _copyField_ or specific ones.
+
+ <copyField source="tags" dest="tags_facet"/> <!-- facet on tags
field/property -->
+
+ <copyField source="*" dest="*_facet"/> <!-- facet on all
fields/properties -->
+
#### Notes
As of Oak version 1.0.0:
