Merge f929b41 into 877cbf6

docs/sql/queries.txt

@@ -48,9 +48,10 @@ Aliases can be used to change the output name of the columns::
 FROM Clause
 -----------
 
-The ``FROM`` clause is used to reference the table to query. A table is referenced
-by schema and table name and can optionally be aliased. If the table ``t`` is
-only referenced by table name, crate assumes the table ``doc.t`` was meant.
+The ``FROM`` clause is used to reference one or two tables.
+A table is referenced by schema and table name and can optionally be aliased.
+If the table ``t`` is only referenced by table name, Crate assumes the table
+``doc.t`` was meant.
 Schemas that were newly created using :ref:`ref-create-table` must be
 referenced explicitly.
 
@@ -89,6 +90,60 @@ A table can be aliased for the sake of brevity too::
     +-------------------+
     SELECT 1 row in set (... sec)
 
+
+.. _sql_dql_cross_join:
+
+Cross Joins
+...........
+
+Referencing two tables results in a ``Cross Join``. The result contains
+every possible combination (Cartesian product) of their
+rows( T1 * T2 * ...)::
+
+    cr> select articles.name as article, colors.name as color, price
+    ... from articles cross join colors
+    ... where price > 5000.0
+    ... order by price, color, article;
+    +------------------------------+---------------+----------+
+    | article                      | color         |    price |
+    +------------------------------+---------------+----------+
+    | Infinite Improbability Drive | Antique White | 19999.99 |
+    | Infinite Improbability Drive | Gold          | 19999.99 |
+    | Infinite Improbability Drive | Midnight Blue | 19999.99 |
+    | Infinite Improbability Drive | Olive Drab    | 19999.99 |
+    | Starship Titanic             | Antique White | 50000.0  |
+    | Starship Titanic             | Gold          | 50000.0  |
+    | Starship Titanic             | Midnight Blue | 50000.0  |
+    | Starship Titanic             | Olive Drab    | 50000.0  |
+    +------------------------------+---------------+----------+
+    SELECT 8 rows in set (... sec)
+
+Alternatively, the join can be done implicitly:
+
+    cr> select articles.name as article, colors.name as color, price
+    ... from articles, colors
+    ... where price > 5000.0
+    ... order by price, color, article;
+    +------------------------------+---------------+----------+
+    | article                      | color         |    price |
+    +------------------------------+---------------+----------+
+    | Infinite Improbability Drive | Antique White | 19999.99 |
+    | Infinite Improbability Drive | Gold          | 19999.99 |
+    | Infinite Improbability Drive | Midnight Blue | 19999.99 |
+    | Infinite Improbability Drive | Olive Drab    | 19999.99 |
+    | Starship Titanic             | Antique White | 50000.0  |
+    | Starship Titanic             | Gold          | 50000.0  |
+    | Starship Titanic             | Midnight Blue | 50000.0  |
+    | Starship Titanic             | Olive Drab    | 50000.0  |
+    +------------------------------+---------------+----------+
+    SELECT 8 rows in set (... sec)
+
+.. note::
+
+    Joining more than two tables are currently unsupported.
+    Additionally, all selected columns have to appear in the order by clause.
+
+
 .. _sql_dql_distinct_clause:
 
 DISTINCT Clause
@@ -397,7 +452,7 @@ NOT
 
     [ NOT ] boolean_expression
 
-The result type is boolean 
+The result type is boolean.
 
     ==========  ======
     expression  result
@@ -412,7 +467,7 @@ The result type is boolean
    This is not compliant with the SQL standard and doesn't adhere to the
    three-valued-logic.  According to the standard NOT ( NULL ) should actually
    return NULL.
-   
+
 
 
 .. _sql_dql_in:

docs/sql/reference/select.txt

@@ -12,7 +12,7 @@ Synopsis
 ::
 
     SELECT [ ALL | DISTINCT ] * | expression [ [ AS ] output_name ] [, ...]
-      FROM table_ident [ [AS] table_alias ]
+      FROM table_reference [{CROSS JOIN | , } table_reference [{CROSS JOIN | ,} ...]]
       [ WHERE condition ]
       [ GROUP BY expression [, ...] [HAVING condition] ]
       [ ORDER BY expression [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] ]
@@ -91,7 +91,14 @@ FROM Clause
 
 The FROM clause specifies the source table for the SELECT::
 
-    FROM table_ident [ [AS] table_alias ]
+    FROM table_reference [{CROSS JOIN | , } table_reference [{CROSS JOIN | ,} ...]]
+
+Table Reference
+...............
+
+A table reference is a table ident with an optional table alias::
+
+    table_ident [ [AS] table_alias ]
 
 :table_ident: The name (optionally schema-qualified) of an existing table.
 
@@ -100,6 +107,18 @@ The FROM clause specifies the source table for the SELECT::
   the actual name of the table. For example given ``FROM foo AS f``, the
   remainder of the SELECT must refer to this 'FROM' item as 'f' not 'foo'.
 
+.. _sql_reference_joined_tables:
+
+Joined Tables
+.............
+
+If more than one table references are listed the tables are joined, see :ref:`sql_dql_cross_join` ::
+
+    FROM table_reference [, table_reference [, ...]]
+
+There is also an explicit join syntax::
+
+    FROM table_reference [CROSS JOIN table_reference [CROSS JOIN ...]]
 
 WHERE Clause
 ------------

docs/src/crate/articles.json

@@ -0,0 +1,4 @@
+{ "id": "1", "name": "Starship Titanic", "price": 50000.0}
+{ "id": "2", "name": "Towel", "price": 1.29}
+{ "id": "3", "name": "Kill-o-Zap blaster pistol", "price": 3499.99}
+{ "id": "4", "name": "Infinite Improbability Drive", "price": 19999.99}

docs/src/crate/colors.json

@@ -0,0 +1,4 @@
+{ "id": "1", "name": "Antique White", "rgb": "#faebd7", "coolness": 0}
+{ "id": "2", "name": "Midnight Blue", "rgb": "#191970", "coolness": 10.0}
+{ "id": "3", "name": "Gold", "rgb": "#ffd700", "coolness": 3.0}
+{ "id": "4", "name": "Olive Drab", "rgb": "#6b8e23", "coolness": 5.0}

docs/src/crate/tests.py

@@ -130,9 +130,11 @@ def setUpLocations(test):
     cmd.stmt("""copy locations from '{0}'""".format(locations_file))
     cmd.stmt("""refresh table locations""")
 
+
 def tearDownLocations(test):
     cmd.stmt("""drop table locations""")
 
+
 def setUpUserVisits(test):
     test.globs['cmd'] = cmd
     cmd.stmt("""
@@ -147,9 +149,46 @@ def setUpUserVisits(test):
     cmd.stmt("""copy uservisits from '{0}'""".format(uservisits_file))
     cmd.stmt("""refresh table uservisits""")
 
+
 def tearDownUserVisits(test):
     cmd.stmt("""drop table uservisits""")
 
+
+def setUpArticles(test):
+    test.globs['cmd'] = cmd
+    cmd.stmt("""
+        create table articles (
+          id integer primary key,
+          name string,
+          price float
+        ) clustered by(id) into 2 shards with (number_of_replicas=0)""".strip())
+    articles_file = os.path.abspath(os.path.join(os.path.dirname(__file__), "articles.json"))
+    cmd.stmt("""copy articles from '{0}'""".format(articles_file))
+    cmd.stmt("""refresh table articles""")
+
+
+def tearDownArticles(test):
+    cmd.stmt("""drop table colors""")
+
+
+def setUpColors(test):
+    test.globs['cmd'] = cmd
+    cmd.stmt("""
+        create table colors (
+          id integer primary key,
+          name string,
+          rgb string,
+          coolness float
+        ) with (number_of_replicas=0)""".strip())
+    colors_file = os.path.abspath(os.path.join(os.path.dirname(__file__), "colors.json"))
+    cmd.stmt("""copy colors from '{0}'""".format(colors_file))
+    cmd.stmt("""refresh table colors""")
+
+
+def tearDownColors(test):
+    cmd.stmt("""drop table colors""")
+
+
 def setUpQuotes(test):
     test.globs['cmd'] = cmd
     cmd.stmt("""
@@ -164,25 +203,51 @@ def setUpQuotes(test):
     shutil.copy(project_path('sql/src/test/resources/essetup/data/copy', 'test_copy_from.json'),
                 os.path.join(import_dir, "quotes.json"))
 
+
 def tearDownQuotes(test):
     cmd.stmt("""drop table quotes""")
 
+
 def setUpLocationsAndQuotes(test):
     setUpLocations(test)
     setUpQuotes(test)
 
+
+def setUpColorsAndArticles(test):
+    setUpColors(test)
+    setUpArticles(test)
+
+
 def tearDownLocationsAndQuotes(test):
     tearDownLocations(test)
     tearDownQuotes(test)
 
+
+def tearDownColorsAndArticles(test):
+    tearDownArticles(test)
+    tearDownColors(test)
+
+
 def setUpLocationsQuotesAndUserVisits(test):
     setUpLocationsAndQuotes(test)
     setUpUserVisits(test)
 
+
 def tearDownLocationsQuotesAndUserVisits(test):
     tearDownLocationsAndQuotes(test)
     tearDownUserVisits(test)
 
+
+def setUpLocationsQuotesAndArticles(test):
+    setUpLocationsAndQuotes(test)
+    setUpColorsAndArticles(test)
+
+
+def tearDownLocationsQuotesAndArticles(test):
+    tearDownLocationsAndQuotes(test)
+    tearDownColorsAndArticles(test)
+
+
 def setUpTutorials(test):
     setUp(test)
     import_dir = '/tmp/best_practice_data'
@@ -196,6 +261,7 @@ def setUpTutorials(test):
     shutil.copy(project_path(source_dir, 'data_import_1408312800.json'),
                 os.path.join(import_dir, "users_1408312800.json"))
 
+
 def setUp(test):
     test.globs['cmd'] = cmd
     test.globs['wait_for_schema_update'] = wait_for_schema_update
@@ -238,15 +304,27 @@ def test_suite():
                'sql/arithmetic.txt',
                'sql/scalar.txt',
                'sql/system.txt',
-               'sql/queries.txt',
                'hello.txt'):
         s = doctest.DocFileSuite('../../' + fn, parser=crash_parser,
                                  setUp=setUpLocationsAndQuotes,
                                  tearDown=tearDownLocationsAndQuotes,
                                  optionflags=doctest.NORMALIZE_WHITESPACE |
                                  doctest.ELLIPSIS)
+
         s.layer = empty_layer
         docs_suite.addTest(s)
+
+    for fn in ('sql/queries.txt', ):
+        s = doctest.DocFileSuite('../../' + fn,
+                                   parser=crash_parser,
+                                   setUp=setUpLocationsQuotesAndArticles,
+                                   tearDown=setUpLocationsQuotesAndArticles,
+                                   optionflags=doctest.NORMALIZE_WHITESPACE |
+                                   doctest.ELLIPSIS)
+        s.layer = empty_layer
+        docs_suite.addTest(s)
+
+
     for fn in ('sql/dml.txt',):
         s = doctest.DocFileSuite('../../' + fn, parser=crash_parser,
                                  setUp=setUpLocationsQuotesAndUserVisits,