From 64c5f4a716a754f7d54e76247ec3e4780ef602cf Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Iv=C3=A1n=20Cea=20Fontenla?= <ivan.cea@elastic.co>
Date: Wed, 9 Apr 2025 12:55:15 +0200
Subject: [PATCH] ESQL: Updated RENAME docs with the behaviour of multiple
 column renames

---
 .../esql/processing-commands/rename.asciidoc         | 10 ++++++++++
 .../qa/testFixtures/src/main/resources/docs.csv-spec | 12 ++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/docs/reference/esql/processing-commands/rename.asciidoc b/docs/reference/esql/processing-commands/rename.asciidoc
index 41e2ce9298ae8..9a4c59365b8f1 100644
--- a/docs/reference/esql/processing-commands/rename.asciidoc
+++ b/docs/reference/esql/processing-commands/rename.asciidoc
@@ -26,6 +26,8 @@ name, all but the rightmost column with the same new name are dropped.
 The `RENAME` processing command renames one or more columns. If a column with
 the new name already exists, it will be replaced by the new column.
 
+A `RENAME` with multiple column renames is equivalent to multiple sequential `RENAME` commands.
+
 *Examples*
 
 [source,esql]
@@ -40,3 +42,11 @@ Multiple columns can be renamed with a single `RENAME` command:
 ----
 include::{esql-specs}/docs.csv-spec[tag=renameMultipleColumns]
 ----
+
+
+With multiple `RENAME` commands:
+
+[source,esql]
+----
+include::{esql-specs}/docs.csv-spec[tag=renameMultipleColumnsDifferentCommands]
+----
diff --git a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec
index aa89c775da4cf..2207bb1ce3a09 100644
--- a/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec
+++ b/x-pack/plugin/esql/qa/testFixtures/src/main/resources/docs.csv-spec
@@ -112,6 +112,18 @@ FROM employees
 fn:keyword | ln:keyword
 ;
 
+docsRenameMultipleColumnsDifferentCommands
+// tag::renameMultipleColumnsDifferentCommands[]
+FROM employees
+| KEEP first_name, last_name
+| RENAME first_name AS fn
+| RENAME last_name AS ln
+// end::renameMultipleColumnsDifferentCommands[]
+| LIMIT 0;
+
+fn:keyword | ln:keyword
+;
+
 docsSort
 // tag::sort[]
 FROM employees