[DOCS] Drafts API changes for transform latest function (#66481)

docs/build.gradle

@@ -1340,6 +1340,10 @@ setups['kibana_sample_data_ecommerce'] = '''
             settings:
               number_of_shards: 1
               number_of_replicas: 0
+            mappings:
+              properties:
+                order_date:
+                  type: date
 '''
 setups['add_timestamp_pipeline'] = '''
   - do:

docs/reference/rest-api/common-parms.asciidoc

@@ -651,8 +651,8 @@ processed in batches instead of individually.
 end::pages-processed[]
 
 tag::pivot[]
-The method for transforming the data. These objects define the pivot function
-`group by` fields and the aggregation to reduce the data.
+The `pivot` method transforms the data by aggregating and grouping it. These
+objects define the `group by` fields and the aggregation to reduce the data.
 end::pivot[]
 
 tag::pivot-aggs[]
@@ -945,6 +945,11 @@ The time delay between the current time and the latest input data time. The
 default value is `60s`.
 end::sync-time-delay[]
 
+tag::transform-latest[]
+The `latest` method transforms the data by finding the latest document for each 
+unique key.
+end::transform-latest[]
+
 tag::transform-settings[]
 Defines optional {transform} settings.
 end::transform-settings[]
@@ -969,6 +974,14 @@ adjusted to a lower value. The minimum value is `10` and the maximum is `10,000`
 The default value is `500`.
 end::transform-settings-max-page-search-size[]
 
+tag::transform-sort[]
+Specifies the date field that is used to identify the latest documents.
+end::transform-sort[]
+
+tag::transform-unique-key[]
+Specifies an array of one or more fields that are used to group the data.
+end::transform-unique-key[]
+
 tag::target-index[]
 `<target-index>`::
 +

docs/reference/transform/apis/preview-transform.asciidoc

@@ -47,6 +47,9 @@ might result in poor mappings. As a work-around, create the destination index
 or an index template with your preferred mappings before you start the
 {transform}.
 
+You must choose either the `latest` or `pivot` method for your {transform}; you
+cannot use both in a single {transform}.
+
 [role="child_attributes"]
 [[preview-transform-request-body]]
 == {api-request-body-title}
@@ -77,6 +80,26 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-pipeline]
 (Optional, <<time-units, time units>>)
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=frequency]
 
+//Begin latest
+`latest`::
+(Required^*^, object)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-latest]
++
+.Properties of `latest`
+[%collapsible%open]
+====
+
+`sort`:::
+(Required, string)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-sort]
+
+`unique_key`:::
+(Required, array of strings)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-unique-key]
+
+====
+//End latest
+
 //Begin pivot
 `pivot`::
 (Required, object)

docs/reference/transform/apis/put-transform.asciidoc

@@ -33,10 +33,13 @@ For more information, see <<built-in-roles>>, <<security-privileges>>, and
 == {api-description-title}
 
 This API defines a {transform}, which copies data from source indices,
-transforms it, and persists it into an entity-centric destination index. The
-entities are defined by the set of `group_by` fields in the `pivot` object. You
-can also think of the destination index as a two-dimensional tabular data
-structure (known as a {dataframe}). The ID for each document in the
+transforms it, and persists it into an entity-centric destination index. If you 
+choose to use the pivot method for your {transform}, the entities are defined by 
+the set of `group_by` fields in the `pivot` object.  If you choose to use the 
+latest method, the entities are defined by the `unique_key` field values in the 
+`latest` object.
+
+You can also think of the destination index as a two-dimensional tabular data structure (known as a {dataframe}). The ID for each document in the
 {dataframe} is generated from a hash of the entity, so there is a unique row
 per entity. For more information, see <<transforms>>.
 
@@ -53,13 +56,14 @@ it had at the time of creation and uses those same roles. If those roles do not
 have the required privileges on the source and destination indices, the
 {transform} fails when it attempts unauthorized operations.
 
-IMPORTANT:  You must use {kib} or this API to create a {transform}.
-            Do not put a {transform} directly into any
-            `.transform-internal*` indices using the Elasticsearch index API.
-            If {es} {security-features} are enabled, do not give users any
-            privileges on `.transform-internal*` indices. If you used transforms
-            prior 7.5, also do not give users any privileges on
-            `.data-frame-internal*` indices.
+IMPORTANT: You must use {kib} or this API to create a {transform}. Do not put a 
+{transform} directly into any `.transform-internal*` indices using the {es}
+index API. If {es} {security-features} are enabled, do not give users any
+privileges on `.transform-internal*` indices. If you used {transforms} prior to
+7.5, also do not give users any privileges on `.data-frame-internal*` indices.
+            
+You must choose either the latest or pivot method for your {transform}; you
+cannot use both in a single {transform}.
 
 [[put-transform-path-parms]]
 == {api-path-parms-title}
@@ -106,9 +110,29 @@ include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=dest-pipeline]
 (Optional, <<time-units, time units>>)
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=frequency]
 
+//Begin latest
+`latest`::
+(Required^*^, object)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-latest]
++
+.Properties of `latest`
+[%collapsible%open]
+====
+
+`sort`:::
+(Required, string)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-sort]
+
+`unique_key`:::
+(Required, array of strings)
+include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=transform-unique-key]
+
+====
+//End latest
+
 //Begin pivot
 `pivot`::
-(Required, object)
+(Required^*^, object)
 include::{es-repo-dir}/rest-api/common-parms.asciidoc[tag=pivot]
 +
 .Properties of `pivot`
@@ -207,9 +231,11 @@ delays.
 [[put-transform-example]]
 == {api-examples-title}
 
+The following {transform} uses the `pivot` method:
+
 [source,console]
 --------------------------------------------------
-PUT _transform/ecommerce_transform
+PUT _transform/ecommerce_transform1
 {
   "source": {
     "index": "kibana_sample_data_ecommerce",
@@ -239,7 +265,7 @@ PUT _transform/ecommerce_transform
   },
   "description": "Maximum priced ecommerce data by customer_id in Asia",
   "dest": {
-    "index": "kibana_sample_data_ecommerce_transform",
+    "index": "kibana_sample_data_ecommerce_transform1",
     "pipeline": "add_timestamp_pipeline"
   },
   "frequency": "5m",
@@ -261,3 +287,31 @@ When the {transform} is created, you receive the following results:
   "acknowledged" : true
 }
 ----
+
+The following {transform} uses the `latest` method: 
+
+[source,console]
+--------------------------------------------------
+PUT _transform/ecommerce_transform2
+{
+  "source": {
+    "index": "kibana_sample_data_ecommerce"
+  },
+  "latest": {
+    "unique_key": ["customer_id"],
+    "sort": "order_date"
+  },
+  "description": "Latest order for each customer",
+  "dest": {
+    "index": "kibana_sample_data_ecommerce_transform2"
+  },
+  "frequency": "5m",
+  "sync": {
+    "time": {
+      "field": "order_date",
+      "delay": "60s"
+    }
+  }
+}
+--------------------------------------------------
+// TEST[setup:kibana_sample_data_ecommerce]