MarkLogic 9 Product Documentationcts:element-value-co-occurrences
cts:element-value-co-occurrences( $element-name-1 as xs:QName, $element-name-2 as xs:QName, [$options as xs:string*], [$query as cts:query?], [$quality-weight as xs:double?], [$forest-ids as xs:unsignedLong*] ) as element(cts:co-occurrence)*
Summary
Returns value co-occurrences (that is, pairs of values, both of which appear
in the same fragment) from the specified element value lexicon(s). The
values are returned as an XML element
with two children, each child
containing one of the co-occurring values. You can use
cts:frequency
on each item returned to find how many times the pair occurs.
Value lexicons are implemented using range indexes; consequently
this function requires an element range index for each element specified
in the function. If there is not a range index configured for each
of the specified elements, an exception is thrown.
| Parameters | |
|---|---|
| element-name-1 | An element QName. |
| element-name-2 | An element QName. |
| options |
Options. The default is ().
Options include:
|
| query |
Only include co-occurrences in fragments selected by the
cts:query,
and compute frequencies from this set of included co-occurrences.
The co-occurrences do not need to match the query, but they must occur in
fragments selected by the query.
The fragments are not filtered to ensure they match the query,
but instead selected in the same manner as
"unfiltered" cts:search
operations. If a string
is entered, the string is treated as a cts:word-query of the
specified string.
|
| quality-weight | A document quality weight to use when computing scores. The default is 1.0. |
| forest-ids | A sequence of IDs of forests to which the search will be constrained. An empty sequence means to search all forests in the database. The default is (). |
Usage Notes
Only one of "frequency-order" or "item-order" may be specified in the options parameter. If neither "frequency-order" nor "item-order" is specified, then the default is "item-order".
Only one of "fragment-frequency" or "item-frequency" may be specified in the options parameter. If neither "fragment-frequency" nor "item-frequency" is specified, then the default is "fragment-frequency".
Only one of "ascending" or "descending" may be specified in the options parameter. If neither "ascending" nor "descending" is specified, then the default is "ascending" if "item-order" is specified, and "descending" if "frequency-order" is specified.
Only one of "eager" or "lazy" may be specified in the options parameter. If neither "eager" nor "lazy" is specified, then the default is "eager" if "frequency-order" or "map" is specified, otherwise "lazy".
Only one of "any", "document", "properties", or "locks" may be specified in the options parameter. If none of "any", "document", "properties", or "locks" are specified and there is a $query parameter, then the default is "document". If there is no $query parameter then the default is "any".
Only one of the "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" options may be specified in the options parameter. If none of "score-logtfidf", "score-logtf", "score-simple", "score-random", or "score-zero" are specified, then the default is "score-logtfidf".
Only one of the "checked" or "unchecked" options may be specified in the options parameter. If neither "checked" nor "unchecked" are specified, then the default is "checked".
If "collation=URI" is not specified in the options parameter, then the default collation is used. If a lexicon with that collation does not exist, an error is thrown.
If "sample=N" is not specified in the options parameter,
then all included co-occurrences may be returned.
If a $query parameter
is not present, then "sample=N" has no effect.
If "truncate=N" is not specified in the options parameter,
then co-occurrences from all fragments selected by the
$query parameter are included.
If a $query parameter is not present, then
"truncate=N" has no effect.
To incrementally fetch a subset of the co-occurrences returned by this
function, use fn:subsequence
on the output, rather than
the "skip" option. The "skip" option is based on fragments matching the
query parameter (if present), not on occurrences. A fragment
matched by query might contain multiple occurrences or no occurrences.
The number of fragments skipped does not correspond to the number of
values. Also, the skip is applied to the relevance ordered query matches,
not to the ordered co-occurrences list.
When using the "skip" option, use the "truncate" option rather than the "limit" option to control the number of matching fragments from which to draw values.
Example
(:
This query has the database fragmented on SPEECH and
finds the first 3 SPEAKERs that co-occur in a SPEECH
in the play Hamlet.
Requires an element range index on SPEAKER with range
value positions enabled on the range index.
:)
cts:element-value-co-occurrences(
xs:QName("SPEAKER"),xs:QName("SPEAKER"),
("frequency-order","ordered"),
cts:document-query("/shakespeare/plays/hamlet.xml"))[1 to 3]
=>
<cts:co-occurrence xmlns:cts="http://marklogic.com/cts"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<cts:value xsi:type="xs:string">MARCELLUS</cts:value>
<cts:value xsi:type="xs:string">BERNARDO</cts:value>
</cts:co-occurrence>
<cts:co-occurrence xmlns:cts="http://marklogic.com/cts"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<cts:value xsi:type="xs:string">ROSENCRANTZ</cts:value>
<cts:value xsi:type="xs:string">GUILDENSTERN</cts:value>
</cts:co-occurrence>
<cts:co-occurrence xmlns:cts="http://marklogic.com/cts"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xs="http://www.w3.org/2001/XMLSchema">
<cts:value xsi:type="xs:string">HORATIO</cts:value>
<cts:value xsi:type="xs:string">MARCELLUS</cts:value>
</cts:co-occurrence>
Example
(:
this query has the database fragmented on SPEECH and
finds SPEAKERs that co-occur in a SPEECH in the play Hamlet,
returned as a map
:)
cts:element-value-co-occurrences(
xs:QName("SPEAKER"),xs:QName("SPEAKER"),
("frequency-order","ordered", "map"),
cts:document-query("/shakespeare/plays/hamlet.xml"))
=>
map:map(
<map:map xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:map="http://marklogic.com/xdmp/map">
<map:entry key="HORATIO">
<map:value xsi:type="xs:string">MARCELLUS</map:value>
</map:entry>
<map:entry key="CORNELIUS">
<map:value xsi:type="xs:string">VOLTIMAND</map:value>
</map:entry>
<map:entry key="MARCELLUS">
<map:value xsi:type="xs:string">BERNARDO</map:value>
<map:value xsi:type="xs:string">HORATIO</map:value>
</map:entry>
<map:entry key="ROSENCRANTZ">
<map:value xsi:type="xs:string">GUILDENSTERN</map:value>
</map:entry>
</map:map>)
Example
xquery version "1.0-ml";
(:
This example uses the co-occurrences between the URI lexicon
and an element range index to effectively join documents together.
:)
(: Load sample data :)
xdmp:document-insert("/test1.xml",
<test1><hello>this is a value</hello></test1>),
xdmp:document-insert("/test2.xml",
<test2><hello>this is a value</hello></test2>),
xdmp:document-insert("/test3.xml",
<test3><hello>this is a different value</hello></test3>);
(:
Requires an element range index on 'hello' and the URI lexicon.
This query finds 'hello' elements that occur in more than one document.
It is an effecient way to join documents using range indexes.
:)
let $x :=
cts:element-value-co-occurrences(
(: note the special xdmp:document QName for the URI lexicon :)
xs:QName("hello"),xs:QName("xdmp:document"),
("frequency-order", "map",
"collation-1=http://marklogic.com/collation/",
"collation-2=http://marklogic.com/collation/codepoint"))
for $key in map:keys($x)
where fn:count(map:get($x, $key)) gt 1
return
<result>
<key>{$key}</key>
<value>{for $uri in map:get($x, $key)
return <uri>{$uri}</uri>}</value>
</result>
(: returns the values that occur in more than one document (URI) :)
=>
<result>
<key>this is a value</key>
<value>
<uri>/test1.xml</uri>
<uri>/test2.xml</uri>
</value>
</result>