MarkLogic 12 Product Documentation

cts:highlight

cts:highlight(
   $node as node(),
   $query as cts:query,
   $expr as item()*
) as node()

Summary

Returns a copy of the node, replacing any text matching the query with the specified expression. You can use this function to easily highlight any text found in a query. Unlike fn:replace and other XQuery string functions that match literal text, cts:highlight matches every term that matches the search, including stemmed matches or matches with different capitalization.

Usage Notes

There are five built-in variables to represent a query match. These variables can be used inline in the expression parameter.

$cts:text as xs:string

The matched text.

$cts:node as text()

The node containing the matched text.

$cts:queries as cts:query*

The matching queries.

$cts:start as xs:integer

The string-length position of the first character of $cts:text in $cts:node. Therefore, the following always returns true:

fn:substring($cts:node, $cts:start,
             fn:string-length($cts:text)) eq $cts:text 

$cts:action as xs:string

Use xdmp:set on this to specify what should happen next

"continue"

(default) Walk the next match. If there are no more matches, return all evaluation results.

"skip"

Skip walking any more matches and return all evaluation results.

"break"

Stop walking matches and return all evaluation results.

You cannot use cts:highlight to highlight results matching cts:similar-query and cts:element-attribute-*-query items. Using cts:highlight with these queries will return the nodes without any highlighting.

You can also use cts:highlight as a general search and replace function. The specified expression will replace any matching text. For example, you could replace the word "hello" with "goodbye" in a query similar to the following:

 cts:highlight($node, "hello", "goodbye")

Because the expressions can be any XQuery expression, they can be very simple like the above example or they can be extremely complex.

Unfiltered queries, including registered queries, do not match in cts:walk or cts:highlight.

Example

To highlight "MarkLogic" with bold in the following paragraph:

let $x :=  <p>MarkLogic Server is an enterprise-class
  database specifically built for content.</p>
return
cts:highlight($x, "MarkLogic", <b>{$cts:text}</b>)

Returns:

  <p><b>MarkLogic</b> Server is an enterprise-class
  database specifically built for content.</p>

Example

Similar to the above use case but on JSON nodes. Note that
an array is used to represent the original text with the
specified object node as a member.

let $x :=  object-node { "p1" :
  "MarkLogic Server is an enterprise-class database specifically built for content."}
return
cts:highlight($x, "MarkLogic", object-node {"highlighted" : $cts:text})

Returns:

  {
    "p1": [
      {
        "highlighted": "MarkLogic"
      },
     " Server is an enterprise-class database specifically built for content."
    ]
  }

Example

Also on JSON nodes but the query matches the whole node. In this case,
no array node is created.

let $x :=  object-node { "p1" : "MarkLogic Server"}
return
cts:highlight($x, "MarkLogic Server", object-node {"highlighted" : $cts:text})

Returns:

  {
    "p1": {
      "highlighted": "MarkLogic Server"
    }
  }

Example

Given the following document with the URI "hellogoodbye.xml":

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

The following query will highlight the word "hello" in
blue, and everything else 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>

Example

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

returns all of the nodes that contain "MarkLogic",
placing bold markup around the matched words.