Search syntax for XML documents

Using an XML search expression, you can use the Db2® Text Search engine to search specific portions of an XML document in a Db2 XML column.

Syntax

XML search query

@xmlxp:: The keyword that starts a text search query on an XML document.
Note: The keyword @xpath has been deprecated.
XML search query: A text search query used by Db2 Text Search to search XML documents. The query is enclosed in single quotation marks. The XML search query is an XML search expression that consists of a location path specifying the portion of the XML document to search and an optional predicate that specifies the search criteria.
location-path: An XML search expression that uses a subset of the XPath abbreviated syntax to specify an XML document node or attribute. More information is provided in the "Location path" section.
search-predicate: The optional search criteria used by Db2 Text Search when searching an XML document. More information is provided in the "Search predicate" section.

The Db2 Text Search engine returns the XML document if it finds the text specified in the search-predicate in the specified nodes or attributes of the XML document.

Location path

When performing a text search on an XML document, Db2 Text Search uses local node and attribute names and a subset of the XPath syntax to specify nodes and attributes in an XML document. Db2 Text Search supports the following XML search elements:

Local node or attribute names
. (period) as the current context node
/ or // as the separator character
@ as the abbreviated symbol for attribute

Name normalization
XML node and attribute names are not normalized when they are indexed for use by the Db2 Text Search engine: they are not converted to lowercase, tokenized, or modified in any way. Case is significant in XML node and attribute names, so the strings that you use for them in queries must match exactly the names appearing in documents to get a match.
Namespace handling
When creating a text search index, you can use XML documents that contain XML namespace specifiers, but namespace specifiers are not retained in the index. For example, the tag <nsdoc:heading> is indexed under heading only, and the query term @xmlxp:'/nsdoc:heading' is parsed as @xmlxp:'/heading'. XML namespace prefixes are discarded during query parsing.

Examples

The following example is a valid text search query using XML search that searches for the term snow shovel in the description node of product information:

	@xmlxp:'/info/product/description[. contains("snow shovel")]'

The following example is a not a valid text search query using XML search because it uses "..", the XML search abbreviation for parent::node():

	@xmlxp:'/info/product/description/../@ID[. contains("A2")]'

Search predicate

Syntax

search-expression: A Db2 Text Search XML search query. Db2 Text Search uses a search expression to search node or attribute values in an XML document.

You can use the following operators to create search expressions:

Logical operators: AND, OR, and NOT
Containment operators: contains and excludes
Comparison operators: =, >, <, >=, <=, and !=
Note:
Comparison operators can be applied to attribute values only, not node values.

Thus, for the <root><aaa id="10">100</aaa><aaa id="11">101</aaa></root>, the following query is invalid:
```
select id from testtable where contains(item,'@xmlxp:''/root/aaa[. > 20]''')>0
```
An example of a valid query would be:
```
select id from testtable where contains(item,'@xmlxp:''/root/aaa/@id[. > 20]''')>0
```

You can combine the comparison and containment operators with the logical operators AND, OR and NOT to create complex search expressions. You can also use parentheses to group expressions.

Use single or double quotation marks to enclose a string. A string that contains quotation marks cannot be enclosed by the same type of quotation marks. For example, a string enclosed in single quotation marks cannot contain a single quotation mark.

In XML search predicates, comparison operators take precedence over logical operators, and all logical operators have the same precedence. You can use parentheses to ensure intended evaluation precedence.

Free text in XML documents (text between tags, not inside a tag itself) and attribute values are normalized before indexing. Free text in XML queries (in containment operators) is normalized in the same way that it is in non-XML queries.

Example

The following example uses an XML search query to search for products that contain the term snow shovel in the product description and that have a price lower than $29.99.

	@xmlxp:'/info/product [(description contains("snow shovel")) and (@price < 29.99)]]'

Comparison expressions

Comparison expressions compare the value of an attribute with a specified value.

Syntax

path-expression

The path expression using a subset of the XML search abbreviated syntax to specify a node or attribute.

operator

The type of comparison to perform. The operator can be one of the following types:

=: path-expression value is equal to literal.
>: path-expression value is greater than literal.
<: path-expression value is less than literal.
>=: path-expression value is greater than or equal to literal.
<=: path-expression value is less than or equal to literal.
!=: path-expression value is not equal to literal.

literal

A string or number used to compare against the path-expression node or attribute value.

Enclose the string in single or double quotation marks. A string that contains quotation marks cannot be enclosed by the same type of quotation marks. For example, a string enclosed in single quotation marks cannot contain a single quotation mark. Use the backslash character (\) to escape double quotation marks (") .

If the string contains double quotation marks, you can enclose the string in single quotation marks. The following example shows a string containing double quotation marks enclosed in single quotation marks:

	'he said "Hello, World"'

If the a string contains single quotation marks, you can enclose the string in escaped double quotation marks. The following example shows a string containing a single quotation mark enclosed in double quotation marks:

	\"the cat's toy\"

Db2 Text Search features such as phrases, wildcards, and synonyms are not supported in XML search queries.

Example

The following example uses the = operator to find product IDs equal to the string 100-200-101:

@xmlxp:'/info/product/@pid[. = "100-200-101" ]'

Note:

The only comparison operators that are supported with string arguments are = and !+, so <, <=, >, >= cannot be used. All six operators are supported with numeric arguments. Numeric arguments are supported for comparison to attribute values, but not to tag (node) content

Containment expressions

Containment expressions determine whether the value of a node or an attribute contains a specified value.

Syntax

path-expression

The XML search expression that specifies an XML node or attribute.

contains

An expression that specifies that path-expression value contains literal.

excludes

An expression that specifies that path-expression value excludes literal.

literal

A string used to compare against the path-expression node or attribute value.

Use single or double quotation marks to enclose a string. A string cannot contain enclosing quote type: for example, a string enclosed in single quotation marks cannot contain a single quotation mark. Use the backslash character (\) to escape double quotation marks (").

If the string contains double quotation marks, you can enclose the string in single quotation marks.

The following example shows a string containing double quotation marks enclosed in single quotation marks:

	'he said "Hello, World"'

If the string contains single quotation marks, you can enclose the string in escaped double quotation marks. The following example shows a string containing a single quotation mark enclosed in double quotation marks:

	\"the cat's toy\"

Example

The following example uses the XQuery abbreviated syntax for path expressions to specify that the description node excludes the term ice scraper:

	@xmlxp:'/info/product/description[. excludes('ice scraper')]'