DOC: warning section on memory overflow when joining/merging dataframes on index with duplicate keys

doc/source/merging.rst

@@ -692,6 +692,30 @@ either the left or right tables, the values in the joined table will be
    p.plot([left, right], result,
           labels=['left', 'right'], vertical=False);
    plt.close('all');
+
+Here is another example with duplicate join keys in DataFrames:
+
+.. ipython:: python
+
+   left = pd.DataFrame({'A' : [1,2], 'B' : [2, 2]})
+
+   right = pd.DataFrame({'A' : [4,5,6], 'B': [2,2,2]})
+
+   result = pd.merge(left, right, on='B', how='outer')
+
+.. ipython:: python
+   :suppress:
+
+   @savefig merging_merge_on_key_multiple.png
+   p.plot([left, right], result,
+          labels=['left', 'right'], vertical=False);
+   plt.close('all');
+
+.. warning::
+
+  Joining / merging on duplicate keys can cause a returned frame that is the multiplication of the row dimensions, 
+  may result in memory overflow, which can be dangerous for unsaved work. 
+  Please make sure no duplicate values in keys before joining large DataFrames.
 
 .. _merging.indicator:
 
@@ -817,6 +841,7 @@ equivalent:
     left.join(right, on=key_or_keys)
     pd.merge(left, right, left_on=key_or_keys, right_index=True,
           how='left', sort=False)
+
 
 Obviously you can choose whichever form you find more convenient. For
 many-to-one joins (where one of the DataFrame's is already indexed by the join