Join examples

.gitignore

@@ -55,3 +55,4 @@ src/datatable/_build_info.py
 
 # vscode settings
 .vscode/settings.json
+.vscode/c_cpp_properties.json

docs/api/dt/join.rst

@@ -3,3 +3,7 @@
     :src: src/core/expr/py_join.cc ojoin::pyobj::m__init__
     :doc: src/core/expr/py_join.cc doc_join
     :tests: tests/test-join.py
+
+
+
+

src/core/expr/py_join.cc

@@ -63,6 +63,55 @@ except: ValueError
 See Also
 --------
 - :ref:`Tutorial on joins <join tutorial>`
+
+Examples
+--------
+
+.. code-block:: python
+
+    df1 = dt.Frame("""    date    X1  X2
+                      01-01-2020  H   10
+                      01-02-2020  H   30
+                      01-03-2020  Y   15
+                      01-04-2020  Y   20""")
+
+    df2 = dt.Frame("""X1  X3
+                      H   5
+                      Y   10""")
+
+
+First, create a key on the right frame (``df2``). Note that the join key(``X1``) has unique values and has the same name in the left frame(``df1``)::
+
+    df2.key = "X1"
+
+Join is now possible::
+
+    df1[:, :, join(df2)]
+
+.. dtframe::
+    :names: date,X1,X2,X3
+    :types: str32,str32,int8,int8
+    :shape: 4, 4
+
+    0,01-01-2020,H,10,5
+    1,01-02-2020,H,30,5
+    2,01-03-2020,Y,15,10
+    3,01-04-2020,Y,20,10
+
+You can refer to columns of the joined frame using prefix :data:`g. <dt.g>`, similar to how columns of the left frame can be accessed using prefix :data:`f. <dt.f>`::
+
+    df1[:, update(X2=f.X2 * g.X3), join(df2)]
+    df1
+
+.. dtframe::
+    :names: date,X1,X2
+    :types: str32,str32,int8
+    :shape: 4, 3
+
+    0,01-01-2020,H,50
+    1,01-02-2020,H,150
+    2,01-03-2020,Y,150
+    3,01-04-2020,Y,200
 )";
 
 static PKArgs args___init__(