MarkLogic 12 Product Documentation

cts:walk

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

Summary

Walks a node, evaluating an expression with any text matching a query. It returns a sequence of all the values returned by the expression evaluations. This is similar to cts:highlight in how it evaluates its expression, but it is different in what it returns.

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:walk to walk results matching cts:similar-query and cts:element-attribute-*-query items.

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

(:
   Return all text nodes containing matches to the query "the".
:)
let $x := <p>the quick brown fox <b>jumped</b> over the lazy dog's back</p>
return cts:walk($x, "the", $cts:node)
=>
  (text{"the quick brown fox "}, text{" over the lazy dog's back"})

Example

xquery version "1.0-ml";
(:
   Do not show any more matches that occur after
   $threshold characters.
:)
let $x := <p>This is 1, this is 2, this is 3, this is 4, this is 5.</p>
let $pos := 1
let $threshold := 20
return
cts:walk($x, "this is",
 (if ( $pos gt $threshold )
  then xdmp:set($cts:action, "break")
  else ($cts:text, xdmp:set($pos, $cts:start)) ) )
=>
("This is", "this is", "this is")

Example

xquery version "1.0-ml";
(:
   Show the first two matches.
:)
let $x := <p>This is 1, this is 2, this is 3, this is 4, this is 5.</p>
let $match := 0
let $threshold := 2
return
cts:walk($x, "this is",
 (if ( $match ge $threshold )
  then xdmp:set($cts:action, "break")
  else ($cts:text, xdmp:set($match, $match + 1)) ) )
=>
("This is", "this is")

Example

xquery version "1.0-ml";
(:
   Similar to the example above but on JSON nodes.
:)
let $x := array-node { "This is 1, this is 2, this is 3, this is 4, this is 5." }
let $match := 0
let $threshold := 2
return
cts:walk($x, "this is",
 (if ( $match ge $threshold )
  then xdmp:set($cts:action, "break")
  else ($cts:text, xdmp:set($match, $match + 1)) ) )
=>
("This is", "this is")

Example

xquery version "1.0-ml";
(:
   It works on JSON number, boolean and null nodes as well.
:)
let $x := object-node { "p1" : "There are ", "p2" : 10,  "p3" : " books here."}
return cts:walk($x, cts:json-property-value-query("p2",10), $cts:node)
=>
number-node{10}