MarkLogic Server 11.0 Product Documentation

Search Developer's Guide — Chapter 13

All Matching Terms, Including Stemmed, and Capitalized

When you use the standard XQuery string functions such as fn:replace and fn:contains to find matches, you must specify the exact string you want to match. If you are trying to highlight matches from a cts:search query, exact string matches will not find all of the hits that match the query. A cts:highlight query match, however, is anything that matches the cts:query specified as the second argument of cts:highlight.

If you have stemmed searches enabled, matches can be more than exact text matches. For example, run, running, and ran all match a query for run. For details on stemming, see Understanding and Using Stemmed Searches.

Similarly, query matches can have different capitalization than the exact word for which you actually searched. Additionally, wildcard matches (if wildcard indexes are enabled) will match a whole range of queries. Queries that use cts:highlight will find all of these matches and replace them with whatever the specified expression evaluates to.

Using the $cts:text Variable to Access the Matched Text

The $cts:text variable holds the strings representing of the query match. For example, assume you have the following document with the URI test.xml in a database in which stemming is enabled:

<root>
  <p>I like to run to the market.</p>
  <p>She is running to catch the train.</p>
  <p>He runs all the time.</p>
</root>

You can highlight text from a query matching the word run as follows:

for $x in cts:search(doc("test.xml")/root/p, "run")
return 
cts:highlight($x, "run", <b>{$cts:text}</b>)

The expression <b>{$cts:text}</b> is evaluated once for each query match, and it replaces the query match with whatever it evaluates to. Because run, running, and ran all match the cts:query for run, the results highlight each of those words and are as follows:

<p>I like to <b>run</b> to the market.</p>
<p>She is <b>running</b> to catch the train.</p>
<p>He <b>runs</b> all the time.</p>

Using the $cts:node Variable to Access the Context of the Match

The $cts:node variable provides access to the text node in which the match occurs. By having access to the node, you can create expressions that do things in the context of that node. For example, if you know your XML has a structure with a hierarchy of book, chapter, section, and paragraph elements, you can write code in the highlight expression to display the section in which each hit occurs. The following code snippet shows an XPath statement that returns the first element named chapter above the text node in which the highlighted term occurs:

$cts:node/ancestor::chapter[1]

You can then use this information to do things like add a link to display that chapter, search for some other terms within that chapter, or whatever you might need to do with the information. Once again, because cts:highlight evaluates an arbitrary XQuery expression for each search query hit, the variations of what you can do with it are virtually unlimited.

The following example shows how to use the $cts:node variable in a test to print the highlighted term in blue if its immediate parent is a p element, otherwise to print the highlightled term in red:

let $doc := <root>
                <p>This is blue.</p>
                <p><i>This is red italic.</i></p>
             </root>
return 
cts:highlight($doc, cts:or-query(("blue", "red")),
 (if ( $cts:node/parent::p )
  then ( <font color="blue">{$cts:text}</font> )
  else ( <font color="red">{$cts:text}</font> ) ) 
             )

This query returns the following results:

<root>
 <p>This is <font color="blue">blue</font>.</p>
 <p><i>This is <font color="red">red</font>italic.</i></p>
</root>

Using the $cts:queries Variable to Feed Logic Based on the Query

The $cts:queries variable provides access to the cts:query that satisfies the query match. You can use that information to drive some logic about how you might highlight different queries in different ways.

For example, assume you have the following document with the URI hellogoodbye.xml in your database:

<root>
  <a>It starts with hello and ends with goodbye.</a>
</root>

You can then run the following query to use some simple logic which displays queries for hello in blue and queries for goodbye in red:

cts:highlight(doc("hellogoodbye.xml"), 
              cts:and-query((cts:word-query("hello"),
                             cts:word-query("goodbye"))),
if ( cts:word-query-text($cts:queries) eq "hello" )
then ( <font color="blue">{$cts:text}</font> )
else ( <font color="red">{$cts:text}</font> ) )
returns:
<root>
  <a>It starts with <font color="blue">hello</font> 
  and ends with <font color="red">goodbye</font>.</a>
</root>

Using $cts:start to Capture the String-Length Position

The $cts:start variable returns the starting position of the matching text ($cts:text), based on the string-length of the text node being processed ($cts:node).

Using $cts:action to Stop Highlighting

Use xdmp:set to change the value of $cts:action and specify what action should occur after processing a match. You can use this variable to control highlighting, typically based on some condition (such as how many matches have already occurred) that you have coded into your application). ou can specify for highlighting to continue (the default), to skip highlighting the remainder of the matches in the current text node, or to break, stopping highlighting for the rest of the input.

Input Must Be a Single Node

The input to cts:highlight must be a single node. If you want to highlight query hits from a cts:search operation that returns multiple nodes, you must iteratively apply cts:highlight to each result.

The input node to cts:highlight must be a document node or an element node; it cannot be a text node.

For example, the following query matches all documents that contain MarkLogic, and then highlights each query match by enclosing it in a b element. Each result is bound to a variable ($x) so cts:highlight can be applied to it.

for $x in cts:search(fn:doc(), "MarkLogic")
return
cts:highlight($x, "MarkLogic", <b>{$cts:text}</b>)

Using xdmp:set Side Effects With cts:highlight

If you want to keep the state of the highlighted terms so you can handle some instances differently than others, you can define a variable and then use the xdmp:set function to change the value of the variable as the highlighted terms are processed. Some common uses for this functionality are:

• Highlight only the first instance of a term.
• Highlight the first term in a different color then the rest of the terms.
• Keep a count on the number of terms matching the query.

The ability to change the state (also known as side effects) opens the door for infinite possibilities of what to do with matching terms.

The following example shows a query that highlights the first query match with a bold tag and returns only the matching text for the rest of the matches.

Assume you have following document with the URI /docs/test.xml in your database:

<html>
  <p>hello hello hello hello</p>
</html>

You can then run the following query to highlight just the first match:

let $count := 0
return
  cts:highlight(doc("/docs/test.xml"), "hello", 
   (: Increment the count for each query match :)
    (xdmp:set($count, $count + 1 ),
     if ( $count = 1 )
     then ( <b>{$cts:text}</b> )
     else ( $cts:text ) )
        ) 

Returns:

<html>
  <p><b>hello</b> hello hello hello</p>
</html>

Because the expression is evaluated once for each query match, the xdmp:set call changes the state for each query match, having the side effect of the conditions being evaluated differently for each query match.

No Highlighting with cts:similar-query or cts:element-attribute-*-query

You cannot use cts:highlight to highlight results from queries containing cts:similar-query or any of the cts:element-attribute-*-query functions. Using cts:highlight with these queries will return the nodes without any highlighting.