MarkLogic Server
XQUERY/XSLT API DOCUMENTATION
5.0
All XQuery & XSLT Functions
MarkLogic Built-In Functions
XQuery Library Modules
CPF Functions
W3C-Standard Functions
  W3C XQuery/XSLT Reference
W3C XQuery Functions
W3C XQuery Language
W3C XSLT Language
This page was generated
March  13,  2012
4:48  AM
XQuery & XSLT Built-In & Modules Function Reference

Module: Thesaurus

The thesaurus functions are designed to help you manage thesaurus documents and then use those thesaurus documents to lookup synonyms for words used in queries. The thesaurus function module is installed as the following file:

  • install_dir/Modules/MarkLogic/thesaurus.xqy

where install_dir is the directory in which MarkLogic Server is installed.

To use the thesaurus.xqy module in your own XQuery modules, include the following line in your XQuery prolog:

import module namespace thsr="http://marklogic.com/xdmp/thesaurus" at "/MarkLogic/thesaurus.xqy";
Function Summary
thsr:add-synonym Adds a synonym to the specified thesaurus entry.
thsr:expand Returns a query that searches for all the query strings specified in $query and their synonyms as found in $entries.
thsr:insert Load the entries in $thsr into the thesaurus at $uri.
thsr:load Load the file specified in $path to the thesaurus at $uri.
thsr:lookup Returns all entries for term $term in the thesaurus document(s) at $uri.
thsr:query-lookup Returns a sequence of all entries that are found by looking up terms in the query and/or subqueries of $query in the thesaurus document(s) at $uri.
thsr:remove-entry Removes all entries that exactly match $entry from the thesaurus documents(s) at $uri.
thsr:remove-synonym Removes synonym $synonym from thesaurus entry $entry.
thsr:remove-term Removes all entries with term $term from the thesaurus document(s) at $uri.
thsr:set-entry Adds the entry $entry to the thesaurus at $uri.
Function Detail
thsr:add-synonym(
$entry as element(thsr:entry),
$synonym as element(thsr:synonym)
)  as   empty-sequence()
Summary:

Adds a synonym to the specified thesaurus entry.

Parameters:
$entry : A thesaurus entry.
$synonym : A synonym to add to a thesaurus entry.

Usage Notes:

The synonym and the entry specified must conform to the thesaurus schema and must be namespace-qualified with the "http://marklogic.com/xdmp/thesaurus" namespace.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";
  thsr:add-synonym(thsr:lookup("/myThsrDocs/roget.xml", 
                               "car")[1],
                 <thsr:synonym>
                    <thsr:term>Alfa Romeo</thsr:term>
                 </thsr:synonym>)
thsr:expand(
$query as cts:query,
$entries as element(thsr:entry)*,
$new-weight as xs:double?,
$min-weight as xs:double?,
$filter as node()*
)  as   cts:query
Summary:

Returns a query that searches for all the query strings specified in $query and their synonyms as found in $entries.

Parameters:
$query : A cts:query item from any of the cts:*-query functions (cts:word-query, cts:and-query, and so on). Thesaurus expansion only occurs on an "unwildcarded" cts:query; it cannot expand "wildcarded" queries.
$entries : A sequence of thesaurus entries.
$new-weight : A new weight for the relevance ranking. If $new-weight is the empty sequence, then the relevance ranking is inherited from the parent query.
$min-weight : A minimum weight for the relevance ranking. If $min-weight is not the empty sequence then only queries with weight less than or equal to $min-weight will be expanded. Otherwise, all queiries are expanded.
$filter : A sequence of node restrictions. These restrictions must be nodes that can be found in a thesaurus entry (for example, <thsr:qualifier>birds</thsr:qualifier>).

Example: 
  xquery version "1.0-ml";
  import module namespace 
	   thsr="http://marklogic.com/xdmp/thesaurus" 
                           at "/MarkLogic/thesaurus.xqy";

  cts:search(
   doc("/Docs/hamlet.xml")//LINE,
   thsr:expand(
     cts:word-query("weary"), 
     thsr:lookup("/myThsrDocs/thesaurus.xml", 
     "weary"),
     (), 
     (), 
     () )
   )

   (: This query returns all of the lines in Shakespeare's 
      Hamlet that have the word "weary" or any of the 
      synonyms of the word "weary"  :)
thsr:insert(
$uri as xs:string,
$thsr as element(thsr:thesaurus)
)  as   empty-sequence()
Summary:

Load the entries in $thsr into the thesaurus at $uri. If there is no document at $uri a new one will be created. If there is a document at $uri it will be overwritten.

Parameters:
$uri : The URI of a thesaurus document.
$thsr : A thesaurus document.

Usage Notes:

If $uri contains XML that does not conform to the thesaurus schema (located in install_dir/Config/thesaurus.xsd), an error is raised.

If $thsr contains XML that does not conform to the thesaurus schema, an error is raised.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

  thsr:insert("/myThsrDocs/roget.xml", 
               xdmp:get("c:\thesaurus\roget.xml") )
thsr:load(
$path as xs:string,
$uri as xs:string
)  as   empty-sequence()
Summary:

Load the file specified in $path to the thesaurus at $uri. Exisiting documents at $uri are overwritten.

Parameters:
$path : The path to a file containing thesaurus entries.
$uri : The URI of a thesaurus document.

Usage Notes:

If $path contains XML that does not conform to the thesaurus schema, an error is raised. If $uri contains XML that does not conform to the thesaurus schema (located in install_dir/Config/thesaurus.xsd), an error is raised.
Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

  thsr:load("c:\thesaurus\roget.xml", "/myThsrDocs/roget.xml")
thsr:lookup(
$uri as xs:string*,
$term as xs:string
)  as   element(thsr:entry)*
Summary:

Returns all entries for term $term in the thesaurus document(s) at $uri.

Parameters:
$uri : The URI of the thesaurus document(s).
$term : A term to lookup in the thesaurus.

Example: 
   thsr:lookup("/myThsrDocs/thesaurus.xml", "weary")
   => returns the thesaurus entry for the term "weary"
thsr:query-lookup(
$uri as xs:string*,
$query as cts:query
)  as   element(thsr:entry)*
Summary:

Returns a sequence of all entries that are found by looking up terms in the query and/or subqueries of $query in the thesaurus document(s) at $uri.

Parameters:
$uri : The URI of the thesaurus document(s).
$query : A cts:query item from any of the cts:*-query functions (cts:word-query, cts:and-query, etc.).

Example: 
  xquery version "1.0-ml";
  import module namespace 
	   thsr="http://marklogic.com/xdmp/thesaurus" 
                           at "/MarkLogic/thesaurus.xqy";

  let $query := cts:word-query("weary")
  return 
      thsr:query-lookup("/myThsrDocs/thesaurus.xml", 
                        $query)

   => All entries for the term "weary" in the specified 
      thsesaurus document
thsr:remove-entry(
$uri as xs:string*,
$entry as element(thsr:entry)
)  as   empty-sequence()
Summary:

Removes all entries that exactly match $entry from the thesaurus documents(s) at $uri.

Parameters:
$uri : The URI of the thesaurus document(s).
$entry : A thesaurus entry.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

   (: removes the second "Car" entry from the 
      thesaurus document :)
  thsr:remove-entry("/myThsrDocs/roget.xml", 
            thsr:lookup("/myThsrDocs/roget.xml","Car")[2])
thsr:remove-synonym(
$entry as element(thsr:entry),
$synonym as element(thsr:synonym)
)  as   empty-sequence()
Summary:

Removes synonym $synonym from thesaurus entry $entry.

Parameters:
$entry : A thesaurus entry.
$synonym : A synonym to add to a thesaurus entry.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	   thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

  thsr:remove-synonym(thsr:lookup("/myThsrDocs/roget.xml",  
                                   "car")[1],
                           <thsr:synonym>
                                <thsr:term>Fiat</thsr:term>
                           </thsr:synonym>)
thsr:remove-term(
$uri as xs:string*,
$term as xs:string
)  as   empty-sequence()
Summary:

Removes all entries with term $term from the thesaurus document(s) at $uri.

Parameters:
$uri : The URI of the thesaurus document(s).
$term : A term to remove from the thesaurus.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

  thsr:remove-term("/myThsrDocs/roget.xml", "Car")

   => removes all entries for "Car" from the thesaurus with the 
      specified URI
thsr:set-entry(
$uri as xs:string,
$entry as element(thsr:entry)
)  as   empty-sequence()
Summary:

Adds the entry $entry to the thesaurus at $uri.

Parameters:
$uri : The URI of a thesaurus document.
$entry : An entry to add to the thesaurus.

Usage Notes:

set the entry $entry in the thesaurus at $uri. If $entry does not contain a valid entry node, an error will be raised. If an entry matching $entry does not exist in the thesaurus, $entry is added to the thesaurus. If $entry contains XML that does not conform to the thesaurus schema (located in install_dir/Config/thesaurus.xsd), an error is raised.

Example: 
  xquery version "1.0-ml";
  import module namespace 
	thsr="http://marklogic.com/xdmp/thesaurus" 
                             at "/MarkLogic/thesaurus.xqy";

  thsr:set-entry("/myThsrDocs/roget.xml", 
   <entry xmlns="http://marklogic.com/xdmp/thesaurus">
      <term>Car</term>
      <synonym>
        <term>Ford</term>
        <part-of-speech>noun</part-of-speech>
      </synonym>
      <synonym>
        <term>automobile</term>
        <part-of-speech>noun</part-of-speech>
      </synonym>
      <synonym>
        <term>Fiat</term>
        <part-of-speech>noun</part-of-speech>
      </synonym>
   </entry>)
Copyright  © 2012 MarkLogic Corporation.    All rights reserved.