The XMLQUERY operator has two arguments, an XML query expression
and a XML value.
SyntaxXMLQUERY ( 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), throws
an error. The xquery-string-literal argument must also be
an XPath expression that is supported by Apache Xalan. uses
Apache Xalan to evaluate all XML query expressions. Because Xalan does not
support full XQuery, neither does .
If Xalan is unable to compile or execute the query argument, 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.
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 XMLQUERY operation,
the argument is accepted if it is a sequence of exactly one node that is a
document node. Otherwise throws
an error.
- BY REF
- Optional keywords that describe the only value passing mechanism supported
by . 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 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. 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 .
ExamplesIn 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 requires
that a JAXP parser, such as Apache Xerces, and that 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.