<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="xml_queries">
	<title>XML SELECT Command</title>
	<section>
		<title>Overview</title>
		<para>Complex XML documents can be dynamically constructed by Teiid using XML Document Models. A document model is
			generally created from a schema. The document model is bound to
			relevant SQL statements through mapping classes. See the Designer
			guide for more on creating document models.</para>
		<para>XML documents may also created via XQuery with the <link linkend="xmlquery">XMLQuery</link> function 
		or with various other <link linkend="xml_functions">SQL/XML</link> functions.</para>
		<para>Querying XML documents is similar to querying relational
			tables. An idiomatic SQL variant with special scalar functions gives
			control over which parts of a given document to return.</para>
	</section>
	<section>
		<title>Query Structure</title>
		<para>
			A valid XML SELECT Command against a document model is of the form
			<link linkend="xml_select_clause">SELECT ...</link>
			<link linkend="xml_from_clause">FROM ...</link>
			<link linkend="xml_where_clause">[WHERE ...]</link>
			<link linkend="xml_order_by_clause">[ORDER BY ...]</link>
			. The use of any other SELECT command clause is not allowed.
		</para>
		<para>
			The fully qualified name for an XML element is:
			<code>"model"."document name".[path to
				element]."element name"</code>
			.
		</para>
		<para>
			The fully qualified name for an attribute is:
			<code>"model"."document name".[path to
				element]."element name".[@]"attribute name"</code>
		</para>
		<para> Partially qualified names for elements and attributes can be
			used as long as the partial name is unique.</para>
		<section id="xml_from_clause">
			<title>FROM Clause</title>
			<para>Specifies the document to generate. Document names
				resemble other virtual groups - "model"."document name".</para>
			<itemizedlist>
				<para>Syntax Rules:</para>
				<listitem>
					<para>The from may only contain one unary clause specifying the
						desired document.</para>
				</listitem>
			</itemizedlist>
		</section>
		<section id="xml_select_clause">
			<title>SELECT Clause</title>
			<para>The select clause determines which parts of the XML document
				are generated for output.</para>
			<itemizedlist>
				<para>Example Syntax:</para>
				<listitem>
					<para>select * from model.doc</para>
				</listitem>
				<listitem>
					<para>select model.doc.root.parent.element.* from model.doc
					</para>
				</listitem>
				<listitem>
					<para>select element, element1.@attribute from model.doc
					</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<para>Syntax Rules:</para>
				<listitem>
					<para>SELECT * and SELECT "xml" are equivalent and specify
						that every element and attribute of the document should be output.
					</para>
				</listitem>
				<listitem>
					<para>The SELECT clause of an XML Query may only contain *,
						"xml", or element and attribute references from the specified
						document. Any other expressions are not allowed.</para>
				</listitem>
				<listitem>
					<para>If the SELECT clause contains an element or attribute
						reference (other than * or "xml") then only the specified
						elements, attributes, and their ancestor elements will be in the
						generated document.</para>
				</listitem>
				<listitem>
					<para>element.* specifies that the element, it's
						attribute, and all child content should be output.</para>
				</listitem>
			</itemizedlist>
		</section>
		<section id="xml_where_clause">
			<title>WHERE Clause</title>
			<para>The where clause specifies how to filter content from the
				generated document based upon values contained in the underlying
				mapping classes. Most predicates are valid in an XML SELECT Command,
				however combining value references from different parts of the
				document may not always be allowed.</para>
			<para>Criteria is logically applied to a context which is
				directly related to a mapping class. Starting with the root mapping
				class, there is a root context that describes all of the top level
				repeated elements that will be in the output document. Criteria
				applied to the root or any other context will change the related
				mapping class query to apply the affects of the criteria, which can
				include checking values from any of the descendant mapping classes.
			</para>
			<itemizedlist>
				<para>Example Syntax:</para>
				<listitem>
					<para>select element, element1.@attribute from model.doc
						where element1.@attribute = 1</para>
				</listitem>
				<listitem>
					<para>select element, element1.@attribute from model.doc
						where context(element1, element1.@attribute) = 1</para>
				</listitem>
			</itemizedlist>
			<itemizedlist>
				<para>Syntax Rules:</para>
				<listitem>
					<para>
						Each criteria conjunct must refer to a single context and can be
						criteria that applies to a mapping class, contain a
						<link linkend="rowlimit_function">rowlimit</link>
						function, or contain
						<link linkend="rowlimitexception_function">rowlimitexception</link>
						function.
					</para>
				</listitem>
				<listitem>
					<para>
						Criteria that applies to a mapping class is associated to that
						mapping class via the
						<link linkend="context_function">context</link>
						function. The absence of a context function implies the criteria
						applies to the root context.
					</para>
				</listitem>
				<listitem>
					<para>At a given context the criteria can span multiple mapping
						classes provided that all mapping classes involved are either
						parents of the context, the context itself, or a descendant of the
						context.</para>
				</listitem>
			</itemizedlist>
			<note>
				<title>Sibling Root Mapping Classes</title>
				<para> Implied root context user criteria against a document model
					with sibling root mapping classes is not generally semantically
					correct. It is applied as if each of the conjuncts is applied to
					only a single root mapping class. This behavior is the same as
					prior releases but may be fixed in a future release.</para>
			</note>
			<section>
				<title>XML SELECT Command Specific Functions</title>
				<para>XML SELECT Command functions are resemble scalar functions,
					but act as hints in the WHERE clause. These functions are only
					valid in an XML SELECT Command.</para>
				<section id="context_function">
					<title>Context Function</title>
					<para>
						<code>CONTEXT(arg1, arg2)</code>
					</para>
					<para>Select the context for the containing conjunct.</para>
					<itemizedlist>
						<para>Syntax Rules:</para>
						<listitem>
							<para>Context functions apply to the whole conjunct.
							</para>
						</listitem>
						<listitem>
							<para>The first argument must be an element or attribute
								reference from the mapping class whose context the criteria
								conjunct will apply to.</para>
						</listitem>
						<listitem>
							<para>The second parameter is the return value for the function.
							</para>
						</listitem>
					</itemizedlist>
				</section>
				<section id="rowlimit_function">
					<title>Rowlimit Function</title>
					<para>
						<code>ROWLIMIT(arg)</code>
					</para>
					<para>Limits the rows processed for the given context.</para>
					<itemizedlist>
						<para>Syntax Rules:</para>
						<listitem>
							<para>The first argument must be an element or attribute
								reference from the mapping class whose context the row limit
								applies.</para>
						</listitem>
						<listitem>
							<para>The rowlimit function must be used in equality
								comparison criteria with the right hand expression equal to an
								positive integer number or rows to limit.</para>
						</listitem>
						<listitem>
							<para>Only one row limit or row limit exception may apply to
								a given context.</para>
						</listitem>
					</itemizedlist>
				</section>
				<section id="rowlimitexception_function">
					<title>Rowlimitexception Function</title>
					<para>Limits the rows processed for the given context and
						throws an exception if the given number of rows is exceeded.
					</para>
					<para>
						<code>ROWLIMITEXCEPTION(arg)</code>
					</para>
					<itemizedlist>
						<para>Syntax Rules:</para>
						<listitem>
							<para>The first argument must be an element or attribute
								reference from the mapping class whose context the row limit
								exception applies.</para>
						</listitem>
						<listitem>
							<para>The rowlimitexception function must be used in equality
								comparison criteria with the right hand expression equal to an
								positive integer number or rows to limit.</para>
						</listitem>
						<listitem>
							<para>Only one row limit or row limit exception may apply to
								a given context.</para>
						</listitem>
					</itemizedlist>
				</section>
			</section>
		</section>
		<section id="xml_order_by_clause">
			<title>ORDER BY Clause</title>
			<para>The XML SELECT Command ORDER BY Clause specifies ordering
				for the referenced mapping class queries.</para>
			<itemizedlist>
				<para>Syntax Rules:</para>
				<listitem>
					<para>Each order by item must be an element or attribute
						reference tied a output value from a mapping class.</para>
				</listitem>
				<listitem>
					<para>The order or the order by items is the relative order they
						will be applied to their respective mapping classes.</para>
				</listitem>
			</itemizedlist>
		</section>
	</section>
	<section>
		<title>Document Generation</title>
		<para>Document generation starts with the root mapping class
			and proceeds iteratively and hierarchically over all of the child
			mapping classes. This can result in a large number of query
			executions. For example if a document has a root mapping class with 3
			child mapping classes. Then for each row selected by the root mapping
			class after the application of the root context criteria, each of the
			child mapping classes queries will also be executed.</para>
		<note>
			<title>Document Correctness</title>
			<para>
				By default XML generated by XML documents are not checked for
				correctness vs. the relevant schema. It is possible that the mapping
				class queries, the usage of specific SELECT or WHERE clause values
				will generated a document that is not valid with respect to the
				schema. See
				<link linkend="document_validation">document validation</link>
				on how to ensure correctness.
			</para>
		</note>
		<para>Sibling or cousin elements defined by the same mapping
			class that do not have a common parent in that mapping class will be
			treated as independent mapping classes during planning and execution.
			This allows for a more document centric approach to applying criteria
			and order bys to mapping classes.</para>
		<section id="document_validation">
			<title>Document Validation</title>
			<para>The execution property XMLValidation should be set to 'true'
				to indicate that generated documents should be checked for
				correctness. Correctness checking will not prevent invalid documents
				from being generated, since correctness is checked after generation
				and not during.</para>
		</section>
	</section>
</chapter>