XmlIndexSpecification::addIndex

XmlIndexSpecification::addIndex
Prev	Chapter 16. XmlIndexSpecification	Next

#include <DbXml.hpp>

void XmlIndexSpecification::addIndex(
    const std::string &uri, const std::string &name, 
    const std::string &index)

void XmlIndexSpecification::addIndex(
    const std::string &uri, const std::string &name, Type type,
    XmlValue::Type syntax)

Adds an index to the index specification. You then set the index specification using XmlContainer::setIndexSpecification.

You identify the indexing strategy that you want to add to the index specification in one of two ways. The first way is to provide a string that identifies the desired indexing strategy. The second is to use XmlIndexSpecification::Type and XmlValue::Type constants to identify the same information.

Either way, an index strategy is set by providing the name of a node and one or more indexing strategies for that node. The node name can be either that of an element, attribute, or metadata node. Metadata nodes are used only for indexing metadata. Element and attribute nodes are used for indexing XML document content. For example, in the XML fragment:

<art title='...'/>

there are two node names that index strategies could be specified for, the element node name is 'art', and the attribute node name is 'title'.

When specifying indexing strategies, you must provide the following information:

Whether the index value must be unique. Of all the information you provide for an index strategy, this is the only one you are not required to specify. If it is not specified, then the indexed value is not required to be unique.
Whether the index is for a specific node, or whether it is for an edge. An edge occurs in an XML document when two nodes meet in the document. For example, in the document:
```
"<a><b><c>foo</c>o</b></a>"
```
there is an edge at <a><b> and another one at <b><c>.
Whether the node to be indexed is an element, attribute, or metadata node. If you are indexing a metadata node, then the index must be a node index (not an edge index).
Whether the index is a presence index (the index indicates whether the node or node edge exists in the document), an equality index (the index tracks the exact value set for the node), or an substring index (the index tracks all the substrings, 3 characters long and greater, that can be constructed for the node).
The indexed value's syntax. There is a large list of available syntaxes, and they range everywhere from a boolean to a date to time information.

In addition to setting index strategies for specified nodes, applications can also specify a default indexing strategy for all nodes in a container by using XmlIndexSpecification::addDefaultIndex. When a container is first created the default indexing strategy is unique-node-metadata-equality-string.

For more information on designing an indexing strategy for your application, see the Berkeley DB XML Getting Started Guide.

You can specify an index by using a string, or by using enumerated values.

Specifying indexes as strings

#include <DbXml.hpp>

void XmlIndexSpecification::addIndex(
    const std::string &uri, const std::string &name, 
    const std::string &index)

Identifies one or more indexing strategies to set for the identified node. The strategies are identified as a space-separated listing of strings.

Parameters are:

uri

The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.

name

The name of the element or attribute node to be indexed.

index

A comma-separated list of strings that represent the indexing strategy. The strings must contain the following information in the following order:

unique-{path type}-{node type}-{key type}-{syntax}

where:

unique indicates that the indexed value is unique in the container. If this keyword does not appear on the index string, then the indexed value is not required to be unique in the container.
{path type} is either node or edge.
{node type} is one of element, attribute, or metadata. If metadata is specified, then {path type} must be node.
{key type} is one of presence, equality, or substring.
{syntax} identifies the type of information being indexed. It must be one of the following values:
none double gYear
base64Binary duration gYearMonth
boolean float hexBinary
date gDay string
dateTime gMonth time
decimal gMonthDay

Note that if {key type} is presence, then {syntax} must be none or simply not specified.

Some example index strings are:

    unique-node-element-presence

    node-element-equality-string

    edge-element-presence-none

    node-element-equality-float

Specifying indexes as enumerated values

#include <DbXml.hpp>

void XmlIndexSpecification::addIndex(
    const std::string &uri, const std::string &name, Type type,
    XmlValue::Type syntax)

Identifies an indexing strategy to set for the identified node. The strategy is set using enumeration values for the index and the syntax.

Parameters are:

uri

The namespace of the node to be indexed. The default namespace is selected by passing an empty string for the namespace.

name

The name of the element or attribute node to be indexed.

type

A series of XmlIndexSpecification::Type values bitwise OR'd together to form the index strategy.

To indicate whether the indexed value must be unique container-wide, use one of the following, or leave the value out entirely:

XmlIndexSpecification::UNIQUE_OFF
XmlIndexSpecification::UNIQUE_ON

To identify the path type, use one of the following:

XmlIndexSpecification::PATH_NODE
XmlIndexSpecification::PATH_EDGE

To identify the node type, use one of the following:

XmlIndexSpecification::NODE_ELEMENT
XmlIndexSpecification::NODE_ATTRIBUTE
XmlIndexSpecification::NODE_METADATA

Note that if XmlIndexSpecification::NODE_METADATA is used, then XmlIndexSpecification::PATH_NODE must also be used as well.

To identify the key type, use one of the following:

XmlIndexSpecification::KEY_PRESENCE
XmlIndexSpecification::KEY_EQUALITY
XmlIndexSpecification::KEY_SUBSTRING

For example:

XmlIndexSpecification::PATH_NODE | 
XmlIndexSpecification::NODE_ELEMENT |
XmlIndexSpecification::KEY_SUBSTRING

syntax

Identifies the type of information being indexed. The value must be one of the XmlValue enumerated types:

XmlValue::NONE
XmlValue::BASE_64_BINARY
XmlValue::BOOLEAN
XmlValue::DATE
XmlValue::DATE_TIME
XmlValue::DECIMAL
XmlValue::DOUBLE
XmlValue::DURATION
XmlValue::FLOAT
XmlValue::G_DAY
XmlValue::G_MONTH
XmlValue::G_MONTH_DAY
XmlValue::G_YEAR
XmlValue::G_YEAR_MONTH
XmlValue::HEX_BINARY
XmlValue::STRING
XmlValue::TIME

Note that if XmlIndexSpecification::KEY_PRESENCE is specified for the type parameter, then this parameter must be XmlValue::NONE.

Errors

The XmlIndexSpecification::addIndex method may fail and throw XmlException , encapsulating one of the following non-zero errors:

UNKNOWN_INDEX

Unknown index specification.

Class

XmlIndexSpecification

none	double	gYear
base64Binary	duration	gYearMonth
boolean	float	hexBinary
date	gDay	string
dateTime	gMonth	time
decimal	gMonthDay

Prev	Up	Next
XmlIndexSpecification::addDefaultIndex	Home	XmlIndexSpecification::deleteDefaultIndex