<!--
 -  
 -  This file is part of the OpenLink Software Virtuoso Open-Source (VOS)
 -  project.
 -  
 -  Copyright (C) 1998-2018 OpenLink Software
 -  
 -  This project is free software; you can redistribute it and/or modify it
 -  under the terms of the GNU General Public License as published by the
 -  Free Software Foundation; only version 2 of the License, dated June 1991.
 -  
 -  This program is distributed in the hope that it will be useful, but
 -  WITHOUT ANY WARRANTY; without even the implied warranty of
 -  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 -  General Public License for more details.
 -  
 -  You should have received a copy of the GNU General Public License along
 -  with this program; if not, write to the Free Software Foundation, Inc.,
 -  51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
 -  
 -  
-->
<?xml version="1.0" encoding="ISO-8859-1"?>
<refentry id="MS-A-3">
  <refmeta>
    <refentrytitle>Using Annotated XSD Schemas for Creating XML Views</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname></refname>
    <refpurpose>Using sql:relationship to Specify Relationships</refpurpose>
  </refnamediv>

<refsect1 id="MS-A-3a">
<title>Preliminaries</title>
<para>
In the annotated XSD schema, the sql:relationship annotation is used to nest the schema elements hierarchically, 
on the basis of primary key and foreign key relationships among the underlying tables to which the elements map. 
In specifying the sql:relationship annotation, you must identify: 
 The parent table (Customers) and the child table (Orders).
 The necessary join condition. (CustomerID in Orders is a child key that refers to the CustomerID parent key in the Customers table.) 

This information is used in generating the proper hierarchy. (For each parent element, the related child 
elements appear as subelements.)
To provide the table names and the necessary join information, the following attributes are specified on the 
sql:relationship annotation: </para>
<itemizedlist mark="bullet">
  <listitem> 
&apos;name&apos; specifies the unique name of the relationship;
  </listitem>
  <listitem>&apos;parent&apos; specifies the parent relation (table). This is an optional attribute; if the attribute is not specified, the parent 
table name is obtained from information in the child hierarchy in the document. If the schema specifies two 
parent-child hierarchies that use the same &lt;sql:relationship&gt; but different parent elements, you do not specify 
the parent attribute in &lt;sql:relationship&gt;. This information is obtained from the hierarchy in the schema.
  </listitem>
  <listitem> &apos;parent-key&apos; specifies the parent key of the parent. If the parent key is composed of multiple columns, values are specified 
with a space between them. There is a positional mapping between the values that are specified for the multicolumn 
key and for the corresponding child key.
  </listitem>
  <listitem>&apos;child&apos; specifies the child relation (table).
  </listitem>
  <listitem>&apos;child-key&apos; specifies the child key in the child referring to parent-key in parent. If the child key is composed of multiple 
attributes (columns), the child-key values are specified with a space between them. There is a positional 
mapping between the values that are specified for the multicolumn key and for the corresponding parent key.
  </listitem>
</itemizedlist>
<para>These attributes are valid only with the &lt;sql:relationship&gt; element.
</para>

</refsect1>
<refsect1 id="MS-A-3b">
<title>Example. Specifying the sql:relationship annotation on an element.</title>
<para>
The following annotated XSD schema includes &apos;Customer&apos; and &apos;Order&apos; elements. 
The &apos;Order&apos; element is a subelement of the &apos;Customer&apos; element.
In the schema, the sql:relationship annotation is specified on the &apos;Order&apos; subelement. The relationship 
itself is defined in the &apos;appinfo&apos; element.
The &apos;relationship&apos; element identifies CustomerID in the Orders table as a foreign key that refers to the 
CustomerID primary key in the Customers table. Therefore, orders that belong to a customer appear as a subelement of 
that &apos;Customer&apos; element.
</para>
<programlisting><![CDATA[
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            xmlns:sql="urn:schemas-microsoft-com:mapping-schema">
<xsd:annotation>
  <xsd:appinfo>
    <sql:relationship name="CustOrders"
          parent="Demo.demo.Customers"
          parent-key="CustomerID"
          child="Demo.demo.Orders"
          child-key="CustomerID" />
  </xsd:appinfo>
</xsd:annotation>

  <xsd:element name="Customer" sql:relation="Demo.demo.Customers" type="CustomerType" />
   <xsd:complexType name="CustomerType" >
     <xsd:sequence>
        <xsd:element name="Order" 
                     sql:relation="Demo.demo.Orders"
                    sql:relationship="CustOrders" >
           <xsd:complexType>
              <xsd:attribute name="OrderID" type="xsd:integer" />
              <xsd:attribute name="CustomerID" type="xsd:string" />
           </xsd:complexType>
        </xsd:element>
     </xsd:sequence>
        <xsd:attribute name="CustomerID"   type="xsd:string" /> 
        <xsd:attribute name="ContactName"  type="xsd:string" />
    </xsd:complexType>
</xsd:schema>
]]></programlisting>
<para>Let the schema is written to the file &apos;CustOr_constant.xsd&apos;, then after loading this file by 
<function>xml_load_mapping_schema_decl</function> function, the first example will produce a result for the XPath query:
</para>
<programlisting><![CDATA[
XPATH [__view 'Customer_Order'] /Customer[@CustomerID="QUEEN"];
]]></programlisting>
<para>
the second example will produce a result for the XQuery query:
</para>
<programlisting><![CDATA[
select xquery_eval('<doc>{for $r in xmlview("Customer_Order")/*[@CustomerID="QUEEN"] return $r}</doc>', xtree_doc('<q/>'))
]]></programlisting>

</refsect1>
</refentry>
