Difference between revisions of "Index Module"

From BaseX Documentation
Jump to navigation Jump to search
 
(66 intermediate revisions by 2 users not shown)
Line 1: Line 1:
−
This module is introduced with BaseX {{Mark|Version 7.1}}. It provides [[Querying#Functions|XQuery functions]] for displaying information stored in the database index structures. All functions are introduced with the {{Mono|index:}} prefix, which is linked to the statically declared {{Mono|http://www.basex.org/modules/index}} namespace.
+
This [[Module Library|XQuery Module]] provides functions for displaying information stored in the database index structures.
 +
 
 +
For functions that use the indexes to return nodes see [[Database_Module#Value_Indexes|Value Indexes]] in the [[Database Module]] and {{Function|Full-Text|ft:search}} in the [[Full-Text Module]].
 +
 
 +
=Conventions=
 +
 
 +
All functions and errors in this module are assigned to the <code><nowiki>http://basex.org/modules/index</nowiki></code> namespace, which is statically bound to the {{Code|index}} prefix.<br/>
 +
 
 +
=Functions=
  
 
==index:facets==
 
==index:facets==
−
{|
+
 
−
|-
+
{| width='100%'
−
| valign='top' width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Mono|<b>index:facets</b>($db as item()) as xs:string}}<br/>{{Mono|<b>index:facets</b>($db as item(), $type as xs:string) as xs:string}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>index:facets(
−
| valign='top' | '''Summary'''
+
  $db   as xs:string,
−
|Returns information about possible facets and facet values on a database in document structure format. {{Mono|$db}} may either be an <code>xs:string</code>, denoting the database name, or a node stored in the database.<br/>If {{Mono|$type}} is specified as {{Mono|flat}}, the function returns this information in a flat summarized version.
+
  $type as xs:string := ()
−
|-
+
) as xs:string</pre>
−
| valign='top' | '''Errors'''
+
|- valign="top"
−
|<b>[[XQuery Errors#BaseX Errors|BASX0001]]</b> is raised if the path index is not available.<br/><b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the addressed database {{Mono|$db}} cannot be opened.<br/>
+
|'''Summary'''
−
|-
+
|Returns information about all facets and facet values of the database {{Code|$db}} in document structure format.<br/>If {{Code|$type}} is specified as {{Code|flat}}, the function returns this information in a flat summarized version. The returned data is derived from the [[Indexes#Path Index|Path Index]].
−
| valign='top' | '''Examples'''
+
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.
 +
|- valign="top"
 +
|'''Examples'''
 
|
 
|
−
* {{Mono|index:facets("DB")}} returns information about facets and facet values on the database {{Mono|DB}} in document structure.
+
* {{Code|index:facets("DB")}} returns information about facets and facet values on the database {{Code|DB}} in document structure.
−
* {{Mono|index:facets("DB", "flat")}} returns information about facets and facet values on the database {{Mono|DB}} in a summarized flat structure.
+
* {{Code|index:facets("DB", "flat")}} returns information about facets and facet values on the database {{Code|DB}} in a summarized flat structure.
 
|}
 
|}
  
 
==index:texts==
 
==index:texts==
−
{|
+
 
−
|-
+
{| width='100%'
−
| valign='top' width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Mono|<b>index:texts</b>($db as item()) as element(value)*}}<br/>{{Mono|<b>index:texts</b>($db as item(), $prefix as xs:string) as element(value)*}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>index:texts(
−
| valign='top' | '''Summary'''
+
  $db         as xs:string,
−
|Returns all strings stored in the text index, along with their number of occurrence. {{Mono|$db}} may either be an <code>xs:string</code>, denoting the database name, or a node stored in the database.<br/>If {{Mono|$prefix}} is specified, the returned nodes will be refined to the strings starting with that prefix.
+
  $prefix    as xs:string    := (),
−
|-
+
  $ascending  as xs:boolean?  := false()
−
| valign='top' | '''Errors'''
+
) as element(value)*</pre>
−
|<b>[[XQuery Errors#BaseX Errors|BASX0001]]</b> is raised if the text index is not available.<br/><b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the addressed database {{Mono|$db}} cannot be opened.<br/>
+
|- valign="top"
 +
|'''Summary'''
 +
|Returns all strings stored in the [[Indexes#Text Index|Text Index]] of the database {{Code|$db}}, along with their number of occurrences.<br/>If {{Code|$prefix}} is specified, the returned entries will be refined to the ones starting with that prefix.<br/>If {{Code|$prefix}} and {{Code|$ascending}} are specified, all nodes will be returned after or before the specified entry.
 +
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.<br/>{{Error|db:no-index|Database Module#Errors}} the index is not available.
 
|}
 
|}
  
 
==index:attributes==
 
==index:attributes==
−
{|
+
 
−
|-
+
{| width='100%'
−
| valign='top' width='90' | '''Signatures'''
+
|- valign="top"
−
|{{Mono|<b>index:attributes</b>($db as item()) as element(value)*}}<br/>{{Mono|<b>index:attributes</b>($db as item(), $prefix as xs:string) as element(value)*}}
+
| width='120' | '''Signature'''
−
|-
+
|<pre>index:attributes(
−
| valign='top' | '''Summary'''
+
  $db         as xs:string,
−
|Returns all strings stored in the attribute index, along with their number of occurrence. {{Mono|$db}} may either be an <code>xs:string</code>, denoting the database name, or a node stored in the database.<br/>If {{Mono|$prefix}} is specified, the returned nodes will be refined to the strings starting with that prefix.
+
  $prefix    as xs:string    := (),
−
|-
+
  $ascending  as xs:boolean?  := false()
−
| valign='top' | '''Errors'''
+
) as element(value)*</pre>
−
|<b>[[XQuery Errors#BaseX Errors|BASX0001]]</b> is raised if the attribute index is not available.<br/><b>[[XQuery Errors#BaseX Errors|BASX0002]]</b> is raised if {{Mono|$db}} is a node that is not stored in a database.<br/><b>[[XQuery Errors#BaseX Errors|BASX0003]]</b> is raised if the addressed database {{Mono|$db}} cannot be opened.<br/>
+
|- valign="top"
 +
|'''Summary'''
 +
|Returns all strings stored in the [[Indexes#Attribute Index|Attribute Index]] of the database {{Code|$db}}, along with their number of occurrences.<br/>If {{Code|$prefix}} is specified, the returned entries will be refined to the ones starting with that prefix.<br/>If {{Code|$prefix}} and {{Code|$ascending}} are specified, all nodes will be returned after or before the specified start entry.
 +
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.<br/>{{Error|db:no-index|Database Module#Errors}} the index is not available.
 +
|}
 +
 
 +
==index:tokens==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>index:tokens(
 +
  $db  as xs:string
 +
) as element(value)*</pre>
 +
|- valign="top"
 +
|'''Summary'''
 +
|Returns all strings stored in the [[Indexes#Token Index|Token Index]] of the database {{Code|$db}}, along with their number of occurrences.
 +
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.<br/>{{Error|db:no-index|Database Module#Errors}} the index is not available.
 +
|}
 +
 
 +
==index:element-names==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>index:element-names(
 +
  $db  as xs:string
 +
) as element(value)*</pre>
 +
|- valign="top"
 +
|'''Summary'''
 +
|Returns all element names stored in the [[Indexes#Name Index|Name Index]] of the database {{Code|$db}}, along with their number of occurrences.
 +
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.
 +
|}
 +
 
 +
==index:attribute-names==
 +
 
 +
{| width='100%'
 +
|- valign="top"
 +
| width='120' | '''Signature'''
 +
|<pre>index:attribute-names(
 +
  $db  as xs:string
 +
) as element(value)*</pre>
 +
|- valign="top"
 +
|'''Summary'''
 +
|Returns all attribute names stored in the [[Indexes#Name Index|Name Index]] of the database {{Code|$db}}, along with their number of occurrences.
 +
|- valign="top"
 +
|'''Errors'''
 +
|{{Error|db:get|Database Module#Errors}} The addressed database does not exist or could not be opened.
 
|}
 
|}
 +
 +
=Changelog=
 +
 +
;Version 8.4
 +
 +
* Added: {{Function||index:tokens}}
 +
 +
;Version 7.7
 +
 +
* Updated: the functions no longer accept [[Database Module#Database Nodes|Database Nodes]] as reference. Instead, the name of a database must now be specified.
 +
 +
;Version 7.3
 +
 +
* Updated: {{Function||index:texts}}, {{Function||index:attributes}}: signature with three arguments added.
 +
 +
The module was introduced with Version 7.1.

Latest revision as of 17:13, 9 March 2023

This XQuery Module provides functions for displaying information stored in the database index structures.

For functions that use the indexes to return nodes see Value Indexes in the Database Module and ft:search in the Full-Text Module.

Conventions[edit]

All functions and errors in this module are assigned to the http://basex.org/modules/index namespace, which is statically bound to the index prefix.

Functions[edit]

index:facets[edit]

Signature 
index:facets(
  $db    as xs:string,
  $type  as xs:string  := ()
) as xs:string
Summary Returns information about all facets and facet values of the database $db in document structure format.
If $type is specified as flat, the function returns this information in a flat summarized version. The returned data is derived from the Path Index.
Errors db:get: The addressed database does not exist or could not be opened.
Examples
  • index:facets("DB") returns information about facets and facet values on the database DB in document structure.
  • index:facets("DB", "flat") returns information about facets and facet values on the database DB in a summarized flat structure.

index:texts[edit]

Signature 
index:texts(
  $db         as xs:string,
  $prefix     as xs:string    := (),
  $ascending  as xs:boolean?  := false()
) as element(value)*
Summary Returns all strings stored in the Text Index of the database $db, along with their number of occurrences.
If $prefix is specified, the returned entries will be refined to the ones starting with that prefix.
If $prefix and $ascending are specified, all nodes will be returned after or before the specified entry.
Errors db:get: The addressed database does not exist or could not be opened.
db:no-index: the index is not available.

index:attributes[edit]

Signature 
index:attributes(
  $db         as xs:string,
  $prefix     as xs:string    := (),
  $ascending  as xs:boolean?  := false()
) as element(value)*
Summary Returns all strings stored in the Attribute Index of the database $db, along with their number of occurrences.
If $prefix is specified, the returned entries will be refined to the ones starting with that prefix.
If $prefix and $ascending are specified, all nodes will be returned after or before the specified start entry.
Errors db:get: The addressed database does not exist or could not be opened.
db:no-index: the index is not available.

index:tokens[edit]

Signature 
index:tokens(
  $db  as xs:string
) as element(value)*
Summary Returns all strings stored in the Token Index of the database $db, along with their number of occurrences.
Errors db:get: The addressed database does not exist or could not be opened.
db:no-index: the index is not available.

index:element-names[edit]

Signature 
index:element-names(
  $db  as xs:string
) as element(value)*
Summary Returns all element names stored in the Name Index of the database $db, along with their number of occurrences.
Errors db:get: The addressed database does not exist or could not be opened.

index:attribute-names[edit]

Signature 
index:attribute-names(
  $db  as xs:string
) as element(value)*
Summary Returns all attribute names stored in the Name Index of the database $db, along with their number of occurrences.
Errors db:get: The addressed database does not exist or could not be opened.

Changelog[edit]

Version 8.4
Version 7.7
  • Updated: the functions no longer accept Database Nodes as reference. Instead, the name of a database must now be specified.
Version 7.3

The module was introduced with Version 7.1.

Retrieved from "http://docs.basex.org/index.php?title=Index_Module&oldid=16500"