An ExcerptProvider retrieves text excerpts for a node in the query result and marks up the words in the text that match the query terms.

By default, highlighting words matched the query is disabled because this feature requires that additional information is written to the search index. To enable this feature, you need to add a configuration parameter to the query-handler element in your JCR configuration file.

<param name="support-highlighting" value="true"/>

Additionally, there is a parameter that controls the format of the excerpt created. In JCR, the default is set to org.exoplatform.services.jcr.impl.core.query.lucene.DefaultHTMLExcerpt. The configuration parameter for this setting is:

<param name="excerptprovider-class" value="org.exoplatform.services.jcr.impl.core.query.lucene.DefaultXMLExcerpt"/>

DefaultXMLExcerpt

This excerpt provider creates an XML fragment of the following form:

<excerpt>

    <fragment>

        <highlight>exoplatform</highlight> implements both the mandatory

        XPath and optional SQL <highlight>query</highlight> syntax.

    </fragment>

    <fragment>

        Before parsing the XPath <highlight>query</highlight> in

        <highlight>exoplatform</highlight>, the statement is surrounded

    </fragment>

</excerpt>

DefaultHTMLExcerpt

This excerpt provider creates an HTML fragment of the following form:

<div>

  <span>

     <strong>exoplatform</strong> implements both the mandatory XPath

     and optional SQL <strong>query</strong> syntax.

  </span>

  <span>

     Before parsing the XPath <strong>query</strong> in

     <strong>exoplatform</strong>, the statement is surrounded

  </span>

</div>

How to use

If you are using XPath, you must use the rep:excerpt() function in the last location step:

QueryManager qm = session.getWorkspace().getQueryManager();

Query q = qm.createQuery("//*[jcr:contains(., 'exoplatform')]/(@Title|rep:excerpt(.))", Query.XPATH);

QueryResult result = q.execute();

for (RowIterator it = result.getRows(); it.hasNext(); ) {

   Row r = it.nextRow();

   Value title = r.getValue("Title");

   Value excerpt = r.getValue("rep:excerpt(.)");

}

The above code searches for nodes that contain the exoplatform word and then gets the value of the Title property and an excerpt for each result node.

It is also possible to use a relative path in the Row.getValue() call while the query statement still remains the same. Also, you may use a relative path to a string property. The returned value will then be an excerpt based on string value of the property.

Both available excerpt providers will create fragments of about 150 characters and up to 3 fragments.

In SQL, the function is called excerpt() without the rep prefix, but the column in the RowIterator will nonetheless be labelled rep:excerpt(.).

QueryManager qm = session.getWorkspace().getQueryManager();

Query q = qm.createQuery("select excerpt(.) from nt:resource where contains(., 'exoplatform')", Query.SQL);

QueryResult result = q.execute();

for (RowIterator it = result.getRows(); it.hasNext(); ) {

   Row r = it.nextRow();

   Value excerpt = r.getValue("rep:excerpt(.)");

}

It is also possible to get an excerpt of all the properties at the same time. See the example below:

QueryManager qm = session.getWorkspace().getQueryManager();

    queryManager.createQuery("select  excerpt(.) from exo:article where contains(exo:title, 'excerpt') or contains(exo:text, 'excerpt') or contains(exo:summary, 'excerpt') ORDER BY exo:title", Query.SQL);

    QueryResult result = q.execute();

    for (RowIterator it = result.getRows(); it.hasNext(); )

    {

      Row r = it.nextRow();

      Value excerpt = r.getValue("rep:excerpt(exo:text|exo:summary|exo:title)");

    }