svn commit: r937168 - in /db/derby/docs/trunk/src/ref: refderby.ditamap rrefsqlj29840.dita rrefsqljnaturaljoin.dita

[ka...@apache.org]

Author: kahatlen
Date: Fri Apr 23 07:05:06 2010
New Revision: 937168

URL: http://svn.apache.org/viewvc?rev=937168&view=rev
Log:
DERBY-4506: Document NATURAL JOIN in the reference manual

Added:
    db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita   (with props)
Modified:
    db/derby/docs/trunk/src/ref/refderby.ditamap
    db/derby/docs/trunk/src/ref/rrefsqlj29840.dita

Modified: db/derby/docs/trunk/src/ref/refderby.ditamap
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/refderby.ditamap?rev=937168&r1=937167&r2=937168&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/refderby.ditamap (original)
+++ db/derby/docs/trunk/src/ref/refderby.ditamap Fri Apr 23 07:05:06 2010
@@ -259,6 +259,7 @@ limitations under the License.
 </topicref>
 <topicref href="rrefsqljcrossjoin.dita" navtitle="CROSS JOIN operation">
 </topicref>
+<topicref href="rrefsqljnaturaljoin.dita" navtitle="NATURAL JOIN operation"/>
 </topicref>
 <topicref href="rrefqueries.dita" navtitle="SQL queries">
 <topicref href="rrefsqlj21571.dita" navtitle="Query"></topicref>

Modified: db/derby/docs/trunk/src/ref/rrefsqlj29840.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqlj29840.dita?rev=937168&r1=937167&r2=937168&view=diff
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqlj29840.dita (original)
+++ db/derby/docs/trunk/src/ref/rrefsqlj29840.dita Fri Apr 23 07:05:06 2010
@@ -42,6 +42,10 @@ rows from the second table.</p></li>
 <li><xref href="rrefsqljcrossjoin.dita#rrefsqljcrossjoin"></xref> <p> Specifies a
 join that produces the Cartesian product of two tables. It has no explicit join
 clause.</p></li>
+<li><xref href="rrefsqljnaturaljoin.dita#rrefsqljnaturaljoin"></xref>
+<p>Specifies an inner or outer join between two tables. It has no
+explicit join clause. Instead, one is created implicitly using the
+common columns from the two tables.</p></li>
 </ul> <p>In all cases, you can specify additional restrictions on one
 or both of the tables being joined in outer join clauses or in the <xref href="rrefsqlj33602.dita#rrefsqlj33602">WHERE
 clause</xref>.</p> </refsyn>

Added: db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita
URL: http://svn.apache.org/viewvc/db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita?rev=937168&view=auto
==============================================================================
--- db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita (added)
+++ db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita Fri Apr 23 07:05:06 2010
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements.  See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License.  You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN"
+ "../dtd/reference.dtd">
+<reference id="rrefsqljnaturaljoin" xml:lang="en-us">
+<title>NATURAL JOIN operation</title>
+<prolog><metadata>
+<keywords><indexterm>NATURAL JOIN operation</indexterm></keywords>
+</metadata></prolog>
+<refbody>
+
+<section>
+
+<p>
+A NATURAL JOIN is a <xref href="rrefsqlj29840.dita#rrefsqlj29840">
+JOIN operation</xref> that creates an implicit join clause for you
+based on the common columns in the two tables being joined. Common
+columns are columns that have the same name in both tables.
+</p>
+
+<p>
+A NATURAL JOIN can be an INNER join, a LEFT OUTER join, or a RIGHT
+OUTER join. The default is INNER join.
+</p>
+
+<p>
+If the SELECT statement in which the NATURAL JOIN operation appears
+has an asterisk (*) in the select list, the asterisk will be expanded
+to the following list of columns (in this order):
+</p>
+
+<ul>
+<li>All the common columns in the first (left) table</li>
+<li>Every column in the first (left) table that is not a common column</li>
+<li>Every column in the second (right) table that is not a common column</li>
+</ul>
+
+<p>
+An asterisk qualified by a table name (for example, COUNTRIES.*) will
+be expanded to every column of that table that is not a common column.
+</p>
+
+</section>
+
+<refsyn>
+<title>Syntax</title>
+<codeblock><b><i><xref href="rreftableexpression.dita#rreftableexpression">TableExpression</xref></i> NATURAL [ { LEFT | RIGHT } [ OUTER ] | INNER ] JOIN { <xref href="rrefsqlj33215.dita#rrefsqlj33215">TableViewOrFunctionExpression</xref> | ( <i><xref href="rreftableexpression.dita#rreftableexpression">TableExpression</xref></i> ) }</b></codeblock>
+</refsyn>
+
+<example>
+<title>Examples</title>
+
+<p>
+If the tables COUNTRIES and CITIES have two common columns named
+COUNTRY and COUNTRY_ISO_CODE, the following two SELECT statements are
+equivalent:
+</p>
+
+<codeblock><b>SELECT * FROM COUNTRIES NATURAL JOIN CITIES</b></codeblock>
+
+<codeblock><b>SELECT * FROM COUNTRIES JOIN CITIES
+    USING (COUNTRY, COUNTRY_ISO_CODE)</b></codeblock>
+
+<p>
+The following example is similar to the one above, but it also
+preserves unmatched rows from the first (left) table:
+</p>
+
+<codeblock><b>SELECT * FROM COUNTRIES NATURAL LEFT JOIN CITIES</b></codeblock>
+
+</example>
+
+</refbody>
+</reference>

Propchange: db/derby/docs/trunk/src/ref/rrefsqljnaturaljoin.dita
------------------------------------------------------------------------------
    svn:eol-style = native