[SQL-CVS] r728 - trunk/SQLObject/docs

[<sub...@co...>]

Author: phd
Date: 2005-04-18 15:04:43 +0000 (Mon, 18 Apr 2005)
New Revision: 728

Added:
   trunk/SQLObject/docs/SQLObjectJoins.txt
Modified:
   trunk/SQLObject/docs/FAQ.txt
   trunk/SQLObject/docs/SQLObject.txt
Log:
Added documentation for JOINs and aliases.


Modified: trunk/SQLObject/docs/FAQ.txt
===================================================================
--- trunk/SQLObject/docs/FAQ.txt	2005-04-18 14:36:32 UTC (rev 727)
+++ trunk/SQLObject/docs/FAQ.txt	2005-04-18 15:04:43 UTC (rev 728)
@@ -54,6 +54,18 @@
 .. raw:: html
    :file: ../examples/snippets/leftjoin-more-query.html
 
+SQL-wise
+~~~~~~~~
+
+Use LEFTJOIN() from sqlobject.sqlbuilder.
+
+
+How can I join a table with itself?
+-----------------------------------
+
+Use Alias from sqlobject.sqlbuilder.
+
+
 How Does Inheritance Work?
 --------------------------
 

Modified: trunk/SQLObject/docs/SQLObject.txt
===================================================================
--- trunk/SQLObject/docs/SQLObject.txt	2005-04-18 14:36:32 UTC (rev 727)
+++ trunk/SQLObject/docs/SQLObject.txt	2005-04-18 15:04:43 UTC (rev 728)
@@ -38,6 +38,7 @@
 .. include:: SQLObjectLegacy.txt
 .. include:: SQLObjectDBConnection.txt
 .. include:: SQLObjectExported.txt
+.. include:: SQLObjectJoins.txt
 
 For more information on SQLBuilder, read the `SQLBuilder
 Documentation`_.

Added: trunk/SQLObject/docs/SQLObjectJoins.txt
===================================================================
--- trunk/SQLObject/docs/SQLObjectJoins.txt	2005-04-18 14:36:32 UTC (rev 727)
+++ trunk/SQLObject/docs/SQLObjectJoins.txt	2005-04-18 15:04:43 UTC (rev 728)
@@ -0,0 +1,60 @@
+LEFT JOIN and other JOINs
+-------------------------
+
+First look in the FAQ_, question "How can I do a LEFT JOIN?"
+
+Still here? Well. To perform a JOIN use one of the JOIN helpers from
+sqlobject.sqlbuilder. Pass an instance of the helper to .select() method.
+For example::
+
+    from sqlobject.sqlbuilder import LEFTJOINOn
+    MyTable.select(join=LEFTJOINOn(Table1, Table2, Table1.q.name == Table2.q.value))
+
+will generate the query::
+
+    SELECT * FROM my_table, table1 LEFT JOIN table2 ON table1.name = table2.value;
+
+.. _FAQ: FAQ.html
+
+If you want to join with the primary table - leave the first table None::
+
+    MyTable.select(join=LEFTJOINOn(None, Table1, MyTable.q.name == Table1.q.value))
+
+will generate the query::
+
+    SELECT * FROM my_table LEFT JOIN table2 ON my_table.name = table1.value;
+
+The join argument for .select() can be a JOIN() or a list/tuples of
+JOIN()s.
+
+
+How can I join a table with itself?
+-----------------------------------
+
+Use Alias from sqlobject.sqlbuilder. Example::
+
+    from sqlobject.sqlbuilder import Alias
+    alias = Alias(MyTable, "my_table_alias")
+    MyTable.select(MyTable.q.name == alias.q.value)
+
+will generate the query::
+
+    SELECT * FROM my_table, my_table AS my_table_alias WHERE my_table.name = my_table_alias.value;
+
+Can I use LEFTJOIN() with aliases?
+----------------------------------
+
+Sure! That's a situation the JOINs an aliases were primary developed for.
+Code::
+
+    from sqlobject.sqlbuilder import LEFTJOINOn, Alias
+    alias = Alias(OtherTable, "other_table_alias")
+    MyTable.select(MyTable.q.name == OtherTable.q.value,
+        join=LEFTJOINOn(MyTable, alias, MyTable.col1 == alias.q.col2))
+
+will result in the query::
+
+    SELECT * FROM other_table,
+        my_table LEFT JOIN other_table AS other_table_alias
+    WHERE my_table.name == other_table.value AND
+        my_table.col1 = other_table_alias.col2.