Loading TOC...
JavaScript cts.frequency

cts: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 occurrences of the value in any given fragment, the frequency is still one per fragment when using fragment-frequency. For example, if this function 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>
 :)

Stack Overflow iconStack Overflow: Get the most useful answers to questions from the MarkLogic community, or ask your own question.