Difference between revisions of "Full-Text Module"

From BaseX Documentation
Jump to navigation Jump to search
m (Text replace - "=Recent Changes=" to "=Changelog=")
Line 124: Line 124:
 
|}
 
|}
  
=Recent Changes=
+
=Changelog=
  
 
===Version 7.1===
 
===Version 7.1===

Revision as of 13:05, 5 March 2012

This module extends the W3C Full Text Recommendation with some useful XQuery functions: The index can be directly accessed, full-text results can be marked with additional elements, or the relevant parts can be extracted. Moreover, the score value, which is generated by the contains text expression, can be explicitly requested from items. All functions are introduced with the ft: prefix, which is linked to the statically declared http://basex.org/modules/ft namespace.

Functions

ft:search

Signatures ft:search($node as node(), $text as xs:string) as text()
Summary Performs a full-text index request on the specified XML node and returns all text nodes that contain the string $text. The index full-text options are used for searching, i.e., if the index terms were stemmed, the search string will be stemmed as well.
Errors BASX0001 is raised if the full-text index is not available.
BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment).
Examples
  • ft:search(., "QUERY") returns all text nodes of the currently opened database that contain the string "QUERY".

ft:mark

Signatures ft:mark($nodes as node()*) as node()*
ft:mark($nodes as node()*, $tag as xs:string) as node()*
Summary Puts a marker element around the resulting $nodes of a full-text index request.
The default tag name of the marker element is mark. An alternative tag name can be chosen via the optional $tag argument.
Note that the XML node to be transformed must be an internal "database" node. The transform expression can be used to apply the method to a main-memory fragment (see example).
Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment).
FOCA0002 is raised if $name is no valid QName.
Examples
  • The following query returns <XML><mark>hello</mark> world</XML>, if one text node of the database DB has the value "hello world":
ft:mark(db:open('DB')//*[text() contains text 'hello'])
  • The following expression returns <p><b>word</b></p>:
copy $p := <p>word</p>
modify ()
return ft:mark($p[text() contains text 'word'], 'b')

ft:extract

Signatures ft:extract($nodes as node()*) as node()*
ft:extract($nodes as node()*, $tag as xs:string) as node()*
ft:extract($nodes as node()*, $tag as xs:string, $length as xs:integer) as node()*
Summary Extracts and returns relevant parts of full-text results. It puts a marker element around the resulting $nodes of a full-text index request and chops irrelevant sections of the result.
The default tag name of the marker element is mark. An alternative tag name can be chosen via the optional $tag argument.
The default length of the returned text is 150 characters. An alternative length can be specified via the optional $length argument. Note that the effective text length may differ from the specified text due to formatting and readibility issues.
Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment).
FOCA0002 is raised if $name is no valid QName.
Examples
  • The following query may return <XML>...<b>hello</b>...<XML> if a text node of the database DB contains the string "hello world":
ft:extract(db:open('DB')//*[text() contains text 'hello'], 'b', 1)

ft:count

Signatures ft:count($nodes as node()*) as xs:integer
Summary Returns the number of occurrences of the search terms specified in a full-text expression.
Errors BASX0002 is raised if a referenced node is not stored in a database (i.e., references a main-memory XML fragment).
Examples
  • ft:count(//*[text() contains text 'QUERY']) returns the xs:integer value 2 if a document contains two occurrences of the string "QUERY".

ft:score

Signatures ft:score($item as item()*) as xs:double*
Summary Returns the score values (0.0 - 1.0) that have been attached to the specified items. 0 is returned a value if no score was attached.
Examples
  • ft:score('a' contains text 'a') returns the xs:double value 1.

ft:tokens

Signatures ft:tokens($db as item()) as element(value)*
ft:tokens($db as item(), $prefix as xs:string) as element(value)*
Summary Returns all full-text tokens stored in the index, along with their numbers of occurrences. $db may either be an xs:string, denoting the database name, or a node stored in the database.
If $prefix is specified, the returned nodes will be refined to the strings starting with that prefix. The prefix will be tokenized according to the full-text used for creating the index.
Errors BASX0001 is raised if the full-text index is not available.
BASX0002 is raised if $db references a node that is not stored in a database (i.e., references a main-memory XML fragment).
BASX0003 is raised if the addressed database cannot be opened.

ft:tokenize

Signatures ft:tokenize($input as xs:string) as xs:string*
Summary Tokenizes the given $input string, using the current default full-text options.
Examples
  • ft:tokenize("No Doubt") returns the two strings no and doubt.
  • declare ft-option using stemming; ft:tokenize("GIFTS") returns a single string gift.

Changelog

Version 7.1

  • Added: ft:tokens(), ft:tokenize()