XMLQUERY is a SQL/XML operator that you can use to query XML values
The XMLQUERY operator has two arguments, an XML query expression
and a Derby XML value.
XMLQUERY ( xquery-string-literal
PASSING BY REF xml-value-expression
[ RETURNING SEQUENCE [ BY REF ] ]
EMPTY ON EMPTY
- 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),Derby throws
an error. The xquery-string-literal argument must also be
an XPath expression that is supported by Apache Xalan. Derby uses
Apache Xalan to evaluate all XML query expressions. Because Xalan does not
support full XQuery, neither does Derby.
If Xalan is unable to compile or execute the query argument, Derby 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/.
- Must be an XML data value and must constitute a well-formed SQL/XML document.
The xml-value-expression argument cannot be a parameter.
Derby 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 Derby XMLQUERY operation,
the argument is accepted if it is a sequence of exactly one node that is a
document node. Otherwise Derby throws
- BY REF
- Optional keywords that describe the only value passing mechanism supported
by Derby. 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 Derby 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. Derby 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 operator.
In the x_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:
XMLQUERY('//student[@age>20]' PASSING BY REF xcol EMPTY ON EMPTY)
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.
table, to search the XML column xcol
return the ages for any students named BC, use the following statement:
XMLQUERY('string(//student[text() = "BC"]/@age)' PASSING BY REF xcol EMPTY ON EMPTY)
XMLEXISTS('//student[text() = "BC"]' PASSING BY REF xcol)
The result set for this query contains a row for only the rows
that have a student whose name is BC.
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 data types and operators" in
the Java DB Developer's Guide for details.