XMLQUERY is a SQL/XML operator that you can use to query XML
values in SQL.
The XMLQUERY operator has two arguments, an XML query expression and a
GemFire XD XML value.
Syntax
XMLQUERY ( xquery-string-literal
PASSING BY REF xml-value-expression
[ RETURNING SEQUENCE [ BY REF ] ]
EMPTY ON EMPTY
)
- xquery-string-literal
- Must be specified as a string literal. If this argument is
specified as a parameter, an expression that is not a literal, or a literal
that is not a string (for example an integer),GemFire XD throws an error. The
xquery-string-literal argument must also be an
XPath expression that is supported by Apache Xalan. GemFire XD uses Apache Xalan
to evaluate all XML query expressions. Because Xalan does not support full
XQuery, neither does GemFire XD. If Xalan is unable to compile or execute the
query argument, GemFire XD catches the error that is thrown by Xalan and throws
the error as a SQLException. For more on XPath and XQuery expressions, see
these Web sites:
http://www.w3.org/TR/xpath and
http://www.w3.org/TR/xquery/.
- xml-value-expression
- Must be an XML data value and must constitute a well-formed
SQL/XML document. The
xml-value-expression argument cannot be a
parameter. GemFire XD does not perform implicit parsing nor casting of XML values,
so use of strings or any other data type results in an error. If the argument
is a sequence that is returned by a GemFire XD XMLQUERY operation, the argument is
accepted if it is a sequence of exactly one node that is a document node.
Otherwise GemFire XD throws an error.
- BY REF
- Optional keywords that describe the only value passing mechanism
supported by GemFire XD. Since BY REF is also the default passing mechanism, the
XMLQUERY operator behaves the same whether the keywords are present or not. For
more information on passing mechanisms, see the SQL/XML specification.
- RETURNING SEQUENCE
- Optional keywords that describe the only XML type returned by the
GemFire XD XMLQUERY operator. Since SEQUENCE is also the default return type, the
XMLQUERY operator behaves the same whether the keywords are present or not. For
more information on the different XML return types, see the SQL/XML
specification.
- EMPTY ON EMPTY
- Required keywords that describe the way in which XMLQUERY handles
an empty result sequence. The XMLQUERY operator returns an empty sequence
exactly as the sequence is. The XMLQUERY operator does not convert the empty
sequence to a null value. When an empty result sequence is serialized, the
result is an empty string. GemFire XD does not consider an empty result sequence
to be a well-formed XML document.
The result of the XMLQUERY operator is a value of type XML. The result
represents a sequence of XML nodes or values. Atomic values, such as strings,
can be part of the result sequence. The result of an XMLQUERY operator is not
guaranteed to represent a well-formed XML document and it might not be possible
to insert the result of an XMLQUERY operator into an XML column. To store the
result in an XML column, the result must be a sequence with exactly one item in
the sequence and the item must be a well-formed document node. The result can
be viewed only in serialized form by explicitly using the
XMLSERIALIZE.
Examples
In the
x_table table, to search the XML column
xcol and return the students that have an age
attribute that is greater than 20, use the following statement:
SELECT ID,
XMLSERIALIZE(
XMLQUERY('//student[@age>20]' PASSING BY REF xcol EMPTY ON EMPTY)
AS VARCHAR(50))
FROM x_table
The result set for this query contains a row for every row in
x_table, regardless of whether or not the XMLQUERY
operator actually returns results.
In the
x_table table, to search the XML column
xcol and return the ages for any students named BC,
use the following statement:
SELECT ID,
XMLSERIALIZE(
XMLQUERY('string(//student[text() = "BC"]/@age)' PASSING BY REF xcol EMPTY ON EMPTY)
AS VARCHAR(50))
FROM x_table
WHERE
XMLEXISTS('//student[text() = "BC"]' PASSING BY REF xcol)
The result set for this query contains a row for only the rows in
x_table that have a student whose name is BC.
Usage note
GemFire XD requires that a JAXP parser (such as Apache Xerces) and Apache
Xalan are listed in the Java classpath for the XML functions to work. If either
the JAXP parser or Xalan is missing from the classpath, attempts to use the
XMLQUERY operator will result in an error. In some situations, you may need to
take steps to place the parser and Xalan in your classpath. See
XML for details.