diff --git a/docs/build.gradle b/docs/build.gradle
index 08cb2de971320..ef3df77339309 100644
--- a/docs/build.gradle
+++ b/docs/build.gradle
@@ -1137,6 +1137,7 @@ buildRestTests.setups['seats'] = '''
             {"theatre": "Graye", "cost": 33, "row": 2, "number": 6, "sold": false}
             {"index":{"_id": "4"}}
             {"theatre": "Skyline", "cost": 20, "row": 5, "number": 2, "sold": false}'''
+
 buildRestTests.setups['kibana_sample_data_ecommerce'] = '''
   - do:
         indices.create:
diff --git a/docs/reference/data-frames/pivoting.asciidoc b/docs/reference/data-frames/pivoting.asciidoc
new file mode 100644
index 0000000000000..e54cf17db3dc4
--- /dev/null
+++ b/docs/reference/data-frames/pivoting.asciidoc
@@ -0,0 +1,173 @@
+[role="xpack"]
+[testenv="basic"]
+[[pivoting]]
+== Transforming your data with {dataframes}
+
+beta[]
+
+coming[7.2.0]
+
+<<ml-dataframes,{dataframes-cap}>> enable you to retrieve information from an
+{es} index, transform it, and store it in a new index.
+
+The following example demonstrates how to use {dataframe-transforms} with the
+{kibana-ref}/add-sample-data.html[{kib} sample data], in particular the
+eCommerce orders sample data.
+
+. Choose your _source index_.
++
+--
+If you're not already familiar with the `kibana_sample_data_ecommerce` index,
+explore the *Revenue* dashboard in {kib}.
+
+If you're interested in a subset of the data in the source index, you can
+optionally include a {ref}/search-request-query.html[query] element when you
+create the {dataframe-transform}.
+  
+--
+
+. Determine how you want to pivot the data. 
++
+--
+For example, you might want to gain insight into how particular products are
+selling by grouping by product IDs and calculating the average price, the count
+of customer IDs that purchased each product, and the sum of each product sold.
+
+Alternatively, you might want to look at the behavior of individual customers by
+grouping by customer ID and calculating how much they spent on average each
+year.
+
+NOTE: You must group your data by at least one field and choose at least one
+aggregation.
+
+--
+
+. Optional: Preview the transformed data and modify your choices until you are
+satisfied with the results. 
++
+--
+Use the wizard on the *Machine learning* page in {kib} or the
+{ref}/preview-data-frame-transform.html[preview {dataframe-transforms} API].
+
+////
+[source,js]
+--------------------------------------------------
+POST _data_frame/transforms/_preview
+{
+  "source": {
+    "index": "kibana_sample_data_ecommerce"
+  },
+  "pivot": {
+    "group_by": {
+      "customer_id": {
+        "terms": {
+          "field": "customer_id"
+        }
+      }
+    },
+    "aggregations": {
+      "max_price": {
+        "max": {
+          "field": "taxful_total_price"
+        }
+      }
+    }
+  }
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:set up sample data]
+////
+--
+
+. Create the {dataframe-transform}. 
++
+--
+Use {kib} or the
+{ref}/put-data-frame-transform.html[create {dataframe-transform} API].
+
+////
+For example:
+
+[source,js]
+--------------------------------------------------
+PUT _data_frame/transforms/ecommerce_transform
+{
+  "source": {
+    "index": "kibana_sample_data_ecommerce",
+    "query": {
+      "term": {
+        "geoip.continent_name": {
+          "value": "Asia"
+        }
+      }
+    }
+  },
+  "dest": {
+    "index": "kibana_sample_data_ecommerce_transform"
+  },
+  "pivot": {
+    "group_by": {
+      "customer_id": {
+        "terms": {
+          "field": "customer_id"
+        }
+      }
+    },
+    "aggregations": {
+      "max_price": {
+        "max": {
+          "field": "taxful_total_price"
+        }
+      }
+    }
+  },
+  "description": "Maximum priced ecommerce data by customer_id in Asia"
+}
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:setup kibana sample data]
+////
+--
+
+. Start the {dataframe-transform}.
++
+--
+////
+[source,js]
+--------------------------------------------------
+POST _data_frame/transforms/ecommerce_transform/_start
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:setup kibana sample data]
+////
+--
+
+. Verify that the destination index was created successfully and explore your
+transformed data.
+
+. Stop the {dataframe-transform}.
++
+--
+////
+[source,js]
+--------------------------------------------------
+POST _data_frame/transforms/ecommerce_transform/_stop
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:set up kibana samples]
+////
+--
+
+. Optional: Delete the {dataframe-transform}. 
++
+--
+////
+[source,js]
+--------------------------------------------------
+DELETE _data_frame/transforms/ecommerce_transform
+--------------------------------------------------
+// CONSOLE
+// TEST[skip:setup kibana sample data]
+////
+--