docs: SQL API joins through __cubeJoinField

Author: paveltiunov

docs/content/SQL-API/Joins.mdx

@@ -6,70 +6,68 @@ subCategory: Reference
 menuOrder: 6
 ---
 
-<WarningBox>
-
-The Cube SQL API currently does not support `INNER JOIN`, `LEFT JOIN`,
-`RIGHT JOIN` and `FULL OUTER JOIN`. We plan to support these types of joins in
-future releases.
-
-</WarningBox>
-
-The SQL API supports `CROSS JOIN`s between cubes. When a `CROSS JOIN` is being
-processed by Cube, it generates the correct joining conditions for the
-underlying data source.
+The SQL API supports joins through `__cubeJoinField` virtual column, which is available in every cube table.
+Join can also be done through `CROSS JOIN`. 
+Usage of `__cubeJoinField` in a join instructs Cube to perform join as it's defined in a data schema. 
+Cube generates the correct joining conditions for the underlying data source.
 
 For example, the following query joins the `Orders` and `Products` tables under
 the hood with `Orders.product_id = Products.id`, exactly the same way as the
 REST API query does:
 
 ```sql
-cube=> SELECT * FROM Orders CROSS JOIN Products LIMIT 5;
- count | avgValue | totalValue | number | value |  status   |         createdAt          |        completedAt         | __user | count |           name            |            description             |         createdAt          | __user
--------+----------+------------+--------+-------+-----------+----------------------------+----------------------------+--------+-------+---------------------------+------------------------------------+----------------------------+--------
-     1 |       20 |         20 |     40 |    20 | completed | 2020-10-26 00:00:00.000000 | 2020-11-07 00:00:00.000000 |        |     1 | Incredible Fresh Chicken  | Electronics Generic Fresh Computer | 2020-06-29 00:00:00.000000 |
-     1 |       20 |         20 |     14 |    20 | completed | 2021-02-07 00:00:00.000000 | 2021-03-02 00:00:00.000000 |        |     1 | Unbranded Wooden Mouse    | Outdoors Incredible Rubber Car     | 2019-07-16 00:00:00.000000 |
-     1 |       20 |         20 |     23 |    20 | completed | 2022-07-23 00:00:00.000000 | 2022-08-11 00:00:00.000000 |        |     1 | Handcrafted Plastic Chair | Electronics Sleek Rubber Tuna      | 2021-02-27 00:00:00.000000 |
-     1 |       20 |         20 |     86 |    20 | completed | 2023-04-19 00:00:00.000000 | 2023-04-25 00:00:00.000000 |        |     1 | Practical Metal Chicken   | Toys Awesome Frozen Chips          | 2020-07-24 00:00:00.000000 |
-     1 |       20 |         20 |     27 |    20 | completed | 2019-06-27 00:00:00.000000 | 2019-07-21 00:00:00.000000 |        |     1 | Sleek Rubber Chair        | Computers Refined Cotton Shirt     | 2021-09-26 00:00:00.000000 |
+cube=> SELECT p.name, SUM(o.count) FROM Orders o LEFT JOIN Products p ON o.__cubeJoinField = p.__cubeJoinField GROUP BY 1 LIMIT 5;
+           name           | SUM(o.count) 
+--------------------------+--------------
+ Tasty Plastic Mouse      |          121
+ Intelligent Cotton Ball  |          119
+ Ergonomic Steel Tuna     |          116
+ Intelligent Rubber Pants |          116
+ Generic Wooden Gloves    |          116
+(5 rows)
+```
+
+Or through `CROSS JOIN`:
+
+```sql
+cube=> SELECT p.name, sum(o.count) FROM Orders o CROSS JOIN Products p GROUP BY 1 LIMIT 5;
+           name           | SUM(o.count) 
+--------------------------+--------------
+ Tasty Plastic Mouse      |          121
+ Intelligent Cotton Ball  |          119
+ Ergonomic Steel Tuna     |          116
+ Intelligent Rubber Pants |          116
+ Generic Wooden Gloves    |          116
 (5 rows)
 ```
 
 In the resulting query plan, you won't see any joins as you can't see those for
 REST API queries either:
 
 ```sql
-cube=> EXPLAIN SELECT * FROM Orders CROSS JOIN Products LIMIT 5;
-   plan_type   |            plan
----------------+-----------------------------
- logical_plan  | CubeScan: request={        +
-               |   "measures": [            +
-               |     "Orders.count",        +
-               |     "Orders.avgValue",     +
-               |     "Orders.totalValue",   +
-               |     "Orders.number",       +
-               |     "Products.count"       +
-               |   ],                       +
-               |   "dimensions": [          +
-               |     "Orders.value",        +
-               |     "Orders.status",       +
-               |     "Orders.createdAt",    +
-               |     "Orders.completedAt",  +
-               |     "Products.name",       +
-               |     "Products.description",+
-               |     "Products.createdAt"   +
-               |   ],                       +
-               |   "segments": [],          +
-               |   "limit": 5               +
+cube=> EXPLAIN SELECT p.name, sum(o.count) FROM Orders o LEFT JOIN Products p ON o.__cubeJoinField = p.__cubeJoinField GROUP BY 1 LIMIT 5;
+   plan_type   |         plan          
+---------------+-----------------------
+ logical_plan  | CubeScan: request={  +
+               |   "measures": [      +
+               |     "Orders.count"   +
+               |   ],                 +
+               |   "dimensions": [    +
+               |     "Products.name"  +
+               |   ],                 +
+               |   "segments": [],    +
+               |   "limit": 5         +
                | }
- physical_plan | CubeScanExecutionPlan      +
-               |
+ physical_plan | CubeScanExecutionPlan+
+               | 
 (2 rows)
 ```
 
-This feature allows you to `CROSS JOIN` cubes even with transitive joins only.
+This feature allows you to join cubes even joined transitively only.
 
-Typically, in tools that allow defining custom SQL datasets, you'd use joined
-tables as a dataset SQL. For example:
+In most of the BI tools you'd use `__cubeJoinField` to define joins between cube tables.
+In tools that allow defining custom SQL datasets, you can use joined tables as a dataset SQL. 
+For example:
 
 ```sql
 SELECT o.count as count, p.name as product_name, p.description as product_description
@@ -137,74 +135,38 @@ LIMIT 5;
 Please note even if `product_description` is in the inner selection, it isn't
 evaluated in the final query as it isn't used in any way.
 
+## Proxy Dimensions and Views
+
 As an alternative to achieve joins it is also possible to define proxy dimension
-or measure inside the Cube.
+or measure inside a cube or a view.
+This is the preferred way of joining as it provides you control over the joining path for complex use cases.
 
 ```javascript
-cube(`Orders`, {
-  sql: `SELECT * FROM public.orders`,
-
-  joins: {
-    Users: {
-      relationship: `belongsTo`,
-      sql: `${CUBE}.user_id = ${Users}.id`,
-    },
-  },
-
-  measures: {
-    count: {
-      type: `count`,
-    },
-  },
-
+view(`OrdersUsers`, {
+  includes: [Orders],
   dimensions: {
-    id: {
-      sql: `id`,
-      type: `number`,
-      primaryKey: true,
-    },
-
     // this is proxy dimension
     user_city: {
       sql: `${Users.city}`,
       type: `string`,
     },
   },
 });
-
-cube(`Users`, {
-  sql: `SELECT * FROM public.users`,
-
-  measures: {},
-
-  dimensions: {
-    id: {
-      sql: `id`,
-      type: `number`,
-      primaryKey: true,
-    },
-
-    city: {
-      sql: `city`,
-      type: `string`,
-    },
-  },
-});
 ```
 
 Now, it is possible to get orders count by users city with the following query.
 
 ```
-cube=> SELECT count, user_city FROM Orders;
- count |   user_city
+cube=> SELECT count, user_city FROM OrdersUsers;
+ count |   user_city   
 -------+---------------
-  9524 | New York
-  9408 | San Francisco
-  6360 | Mountain View
-  6262 | Seattle
-  4393 | Los Angeles
-  3183 | Chicago
-  3060 | Austin
-  1804 | Palo Alto
+  1416 | Los Angeles
+  1412 | Seattle
+  1365 | Mountain View
+  1263 | New York
+  1220 | Austin
+  1164 | Chicago
+  1101 | San Francisco
+  1059 | Palo Alto
 (8 rows)
 ```