MarkLogic 9 Product Documentationcts:frequency
cts:frequency( $value as item() ) as xs:integer
Summary
Returns an integer representing the number of times in which a particular value occurs in a value lexicon lookup.
| Parameters | |
|---|---|
| value |
A value from a lexicon lookup function. For example, a value returned by
a function such as
cts:values,
cts:words,
cts:field-values,
cts:field-word-match,
or cts:geospatial-boxes.
|
Usage Notes
You must have a suitable index configured to use the lexicon APIs.
For example you must configure a range index to use value
lexicon lookup functions such as
cts:element-values, cts:element-value-match,
cts:element-attribute-values, or
cts:element-attribute-value-match.
If the value specified is not from a value lexicon lookup, this function returns a frequency of 0.
When using the fragment-frequency lexicon option, this function
returns the number of fragments in which the lexicon value occurs. When
using the item-frequency lexicon option, this function returns
the total number of times in which the lexicon value occurs in each item.
The frequency returned this function is fragment-based
by default (using the default fragment-frequency option in the
lexicon API). If there are multiple occurences of the value in any given
fragment, the frequency is still one per fragment when using
fragment-frequency. For example, if this funciton returns
a value of 13, then the input value occurs in 13 fragments.
To get the total frequency rather than the fragment-based frequency,
pass the item-frequency option to the lexicon lookup
function that generates the input values for this function. See the
second example, below.
Example
<results>{
(: Example using fragment frequency (default). An element range index
: on SPEAKER must exist.
:)
let $x := cts:element-values(xs:QName("SPEAKER"),"",(),
cts:document-query("/shakespeare/plays/hamlet.xml"))
for $speaker in $x
return
(
<result>
<SPEAKER>{$speaker}</SPEAKER>
<NUMBER-OF-SPEECHES>{cts:frequency($speaker)}</NUMBER-OF-SPEECHES>
</result>
)
}</results>
(: Returns the names of the speakers in Hamlet with the number of times
: they speak. If the play is fragmented at the SCENE level, then
: it returns the number of scenes in which each speaker speaks.
: For example:
:
: <results>
: <result>
: <SPEAKER>All</SPEAKER>
: <NUMBER-OF-SPEECHES>4</NUMBER-OF-SPEECHES>
: </result>
: <result>
: <SPEAKER>BERNARDO</SPEAKER>
: <NUMBER-OF-SPEECHES>2</NUMBER-OF-SPEECHES>
: </result>
: ...
: </results>
:)
Example
(: Example using item frequency. An element range index
: on SPEAKER must exist.
:)
<results>{
let $x := cts:element-values(xs:QName("SPEAKER"),
"", "item-frequency",
cts:document-query("/shakespeare/plays/hamlet.xml"))
for $speaker in $x
return
(
<result>
<SPEAKER>{$speaker}</SPEAKER>
<NUMBER-OF-SPEECHES>
{cts:frequency($speaker)}
</NUMBER-OF-SPEECHES>
</result>
)
}</results>
(: Returns the names of the speakers in Hamlet with the number of times
: they speak. Returns the total times they speak, regardless of
: fragmentation. For example:
:
: <results>
: <result>
: <SPEAKER>All</SPEAKER>
: <NUMBER-OF-SPEECHES>4</NUMBER-OF-SPEECHES>
: </result>
: <result>
: <SPEAKER>BERNARDO</SPEAKER>
: <NUMBER-OF-SPEECHES>23</NUMBER-OF-SPEECHES>
: </result>
: ...
: </results>
:)