added example for flat_map

1 files changed, 13 insertions, 1 deletions

diff --git a/tensorflow/python/data/ops/dataset_ops.py b/tensorflow/python/data/ops/dataset_ops.py
index 8242c7309d..14a1e3d803 100644
--- a/tensorflow/python/data/ops/dataset_ops.py
+++ b/tensorflow/python/data/ops/dataset_ops.py
@@ -1007,8 +1007,20 @@ class Dataset(object):
       return ParallelMapDataset(self, map_func, num_parallel_calls)
 
   def flat_map(self, map_func):
-    """Maps `map_func` across this dataset and flattens the result. Will produce identical results to 'tf.data.Dataset.interleave'
+    """Maps `map_func` across this dataset and flattens the result. 
+    
+    Will produce similar results to `tf.data.Dataset.interleave(cycle_length=1)`. 
+    Use `flat_map` if you want to make sure, that the order of your dataset stays the same.
+    For example:
 
+    ```python
+    # NOTE: The following examples use `{ ... }` to represent the
+    # contents of a dataset. '[...]' represents a tensor.
+    a = {[1,2,3,4,5], [6,7,8,9], [10]}
+    
+    a.flat_map(lambda x: Dataset.from_tensors(x)) == 
+      {[1,2,3,4,5,6,7,8,9,10]}
+    ```
     Args:
       map_func: A function mapping a nested structure of tensors (having shapes
         and types defined by `self.output_shapes` and `self.output_types`) to a