From 39a072389c92b0a160adbc25d010e96f2795ff0c Mon Sep 17 00:00:00 2001
From: Andrei Stefan <astefan@users.noreply.github.com>
Date: Mon, 7 Jan 2019 10:08:51 +0200
Subject: [PATCH] SQL: add sub-selects to the Limitations page (#37012)

---
 docs/reference/sql/limitations.asciidoc       | 21 +++++++++++++++
 .../sql/qa/src/main/resources/docs.csv-spec   | 27 +++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/docs/reference/sql/limitations.asciidoc b/docs/reference/sql/limitations.asciidoc
index b66c246bc42..33a0859a7fd 100644
--- a/docs/reference/sql/limitations.asciidoc
+++ b/docs/reference/sql/limitations.asciidoc
@@ -69,3 +69,24 @@ a field is an array (has multiple values) or not, so without reading all the dat
 When doing aggregations (`GROUP BY`) {es-sql} relies on {es}'s `composite` aggregation for its support for paginating results.
 But this type of aggregation does come with a limitation: sorting can only be applied on the key used for the aggregation's buckets. This
 means that queries like `SELECT * FROM test GROUP BY age ORDER BY COUNT(*)` are not possible.
+
+[float]
+=== Using a sub-select
+
+Using sub-selects (`SELECT X FROM (SELECT Y)`) is **supported to a small degree**: any sub-select that can be "flattened" into a single
+`SELECT` is possible with {es-sql}. For example:
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[limitationSubSelect]
+--------------------------------------------------
+
+The query above is possible because it is equivalent with:
+
+["source","sql",subs="attributes,macros"]
+--------------------------------------------------
+include-tagged::{sql-specs}/docs.csv-spec[limitationSubSelectRewritten]
+--------------------------------------------------
+
+But, if the sub-select would include a `GROUP BY` or `HAVING` or the enclosing `SELECT` would be more complex than `SELECT X
+FROM (SELECT ...) WHERE [simple_condition]`, this is currently **un-supported**.
diff --git a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
index af16675ab81..e04a02558b9 100644
--- a/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
+++ b/x-pack/plugin/sql/qa/src/main/resources/docs.csv-spec
@@ -2130,3 +2130,30 @@ SELECT NOW() AS result;
 2018-12-12T14:48:52.448Z
 // end::nowFunction
 ;
+
+////////////
+// Next two queries need to have the same output, as they should be equivalent.
+// They are used in the "SQL Limitations" page.
+////////////
+limitationSubSelect
+// tag::limitationSubSelect
+SELECT * FROM (SELECT first_name, last_name FROM emp WHERE last_name NOT LIKE '%a%') WHERE first_name LIKE 'A%';
+
+  first_name   |   last_name
+---------------+---------------
+Anneke         |Preusig
+Anoosh         |Peyn
+Arumugam       |Ossenbruggen
+// end::limitationSubSelect
+;
+
+limitationSubSelect
+// tag::limitationSubSelectRewritten
+SELECT first_name, last_name FROM emp WHERE last_name NOT LIKE '%a%' AND first_name LIKE 'A%';
+// end::limitationSubSelectRewritten
+  first_name   |   last_name
+---------------+---------------
+Anneke         |Preusig
+Anoosh         |Peyn
+Arumugam       |Ossenbruggen
+;