Loading TOC...

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 (for example, cts:element-values). When using the fragment-frequency lexicon option, cts:frequency returns the number of fragments in which the lexicon value occurs. When using the item-frequency lexicon option, cts:frequency returns the total number of times in which the lexicon value occurs in each item.

Parameters
$value A value from a value lexicon lookup. The value should be one returned from the cts:element-values, cts:element-attribute-values, or the corresponding value-match lexicon APIs.

Usage Notes

You must have a Range index configured to use the value lexicon APIs (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, cts:frequency returns a frequency of 0.

The frequency returned from cts:frequency 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. Therefore, if the value returned is 13, it means that the value occurs in 13 fragments.

If you want the total frequency instead of the fragment-based frequency (that is, the total number of occurences of the value in the items specified in the cts:query option of the lexicon API), you must specify the item-frequency option to the lexicon API value input to cts:frequency. For example, the second example below specifies an item-frequency and a cts:document-query in the lexicon API, so the item frequency is how many times each speaker speaks in the play (because the constraining query is a document query of hamlet.xml, which contains the whole play).

Example

<results>{
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. 

Example

<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. 

Comments

  • A link to chapter 10 of the Search Developers Guide, in particular the section on lexicon queries, would be very helpful: http://docs.marklogic.com/8.0/guide/search-dev/lexicon#id_68391
  • can the cts;frequency used with the cts:element-value-co-occurences?
    • Yes. See http://docs.marklogic.com/cts:element-value-co-occurrences.
  • You can also use cts:frequency() on cts:range results from cts:element-value-ranges() and cts:element-attribute-value-ranges(), to pull back the number of fragments in each bucket.
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy