<!--
 -  
 -  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-5">
  <refmeta>
    <refentrytitle>Using Annotated XSD Schemas for Creating XML Views</refentrytitle>
    <refmiscinfo>tutorial</refmiscinfo>
  </refmeta>
  <refnamediv>
    <refname></refname>
    <refpurpose>Filtering Values by Using sql:limit-field and sql:limit-value </refpurpose>
  </refnamediv>

<refsect1 id="MS-A-5a">
<title>Preliminaries</title>
<para>
Rows returned from a database query can be limited on the basis of some limiting value. 
The sql:limit-field is used to identify the database column that contains 
limiting values and sql:limit-value annotations is used to specify a specific limiting value to be used 
to filter the data returned.
The sql:limit-value annotation is optional. If sql:limit-value is not specified, 
a NULL value is assumed.
</para>

</refsect1>
<refsect1 id="MS-A-5b">
<title>Example.</title>
<para>
This is the mapping schema in which the &apos;product_Chai&apos; schema attribute maps to the &apos;ProductID&apos; 
column in the &apos;Demo.demo.Products&apos; relation. The values that are returned for this attribute are limited 
to only &apos;ProductName&apos; having the &apos;Chai&apos; value by specifying the sql:limit-field and sql:limit-value 
annotations. Similarly, 
the &apos;product_Chang&apos; schema attribute returns only the 
&apos;ProductID&apos; limited to &apos;ProductName&apos; having the &apos;Chang&apos; value.

</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="CategoryProduct"
          parent="Demo.demo.Categories"
          parent-key="CategoryID"
          child="Demo.demo.Products"
          child-key="CategoryID" />
  </xsd:appinfo>
</xsd:annotation>

  <xsd:element name="category" sql:relation="Demo.demo.Categories" type="CategoryType" />
   <xsd:complexType name="CategoryType" >
     <xsd:sequence>
        <xsd:element name="product_Chai" 
                       type="xsd:string" 
                     sql:relation="Demo.demo.Products"
                     sql:field="ProductID"
                     sql:limit-field="ProductName"
                     sql:limit-value="Chai"
                     sql:relationship="CategoryProduct" >
        </xsd:element>
        <xsd:element name="product_Chang" 
                       type="xsd:string" 
                     sql:relation="Demo.demo.Products"
                     sql:field="ProductID"
                     sql:limit-field="ProductName"
                     sql:limit-value="Chang"
                     sql:relationship="CategoryProduct" >
        </xsd:element>
     </xsd:sequence>
        <xsd:attribute name="CategoryID"  type="xsd:integer" /> 
        <xsd:attribute name="description"  sql:field="Description"  type="xsd:string" />
    </xsd:complexType>

</xsd:schema>
]]></programlisting>
<para>Let the schema is written to the file &apos;Cat_Product.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 'Cat_Product'] /*[@CategoryID=1]
]]></programlisting>

<para>
the second example will produce a result for the XQuery query:
</para>
<programlisting><![CDATA[
select xquery_eval('<doc>{for $r in xmlview("Cat_Product")/*[@CategoryID=1] return $r}</doc>', xtree_doc('<q/>'))
]]></programlisting>

</refsect1>
</refentry>
