From 04546b65ec481c511ebaf38eac346f351854d92b Mon Sep 17 00:00:00 2001
From: Abhishek Agarwal <1477457+abhishekagarwal87@users.noreply.github.com>
Date: Wed, 21 Oct 2020 02:19:13 +0530
Subject: [PATCH] Additional documentation for query caching (#10503)

* Add documentation for when caching is unsupported

* Minor changes

* Minor doc fix

* Review comments

* Add more details

* Fix spelling check

* Fix doc for union query

* Trailing dot
---
 docs/querying/caching.md    | 14 ++++++++++++++
 docs/querying/datasource.md | 12 ++++++++++--
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/docs/querying/caching.md b/docs/querying/caching.md
index d6ac90250e9..74120c9b277 100644
--- a/docs/querying/caching.md
+++ b/docs/querying/caching.md
@@ -82,3 +82,17 @@ Note that the task executor processes only support caches that keep their data l
 This restriction exists because the cache stores results at the level of intermediate partial segments generated by the
 ingestion tasks. These intermediate partial segments will not necessarily be identical across task replicas, so
 remote cache types such as `memcached` will be ignored by task executor processes.
+
+## Unsupported queries
+
+Query caching is not available for following:
+- Queries, that involve a `union` datasource, do not support result-level caching. Refer to the 
+[related issue](https://github.com/apache/druid/issues/8713) for details. Please note that not all union SQL queries are executed using a union datasource. You can use the `explain` operation to see how the union query in sql will be executed.
+- Queries, that involve an `Inline` datasource or a `Lookup` datasource, do not support any caching. 
+- Queries, with a sub-query in them, do not support any caching though the output of sub-queries itself may be cached. 
+Refer to the [Query execution](query-execution.md#query) page for more details on how sub-queries are executed.
+- Join queries do not support any caching on the broker [More details](https://github.com/apache/druid/issues/10444).
+- GroupBy v2 queries do not support any caching on broker [More details](https://github.com/apache/druid/issues/3820).
+- Data Source Metadata queries are not cached anywhere.
+- Queries, that have `bySegment` set in the query context, are not cached on the broker. They are currently cached on 
+historical but this behavior will potentially be removed in the future.  
diff --git a/docs/querying/datasource.md b/docs/querying/datasource.md
index 4b35208a67f..b7625920835 100644
--- a/docs/querying/datasource.md
+++ b/docs/querying/datasource.md
@@ -113,6 +113,16 @@ use table datasources.
 ### `union`
 
 <!--DOCUSAURUS_CODE_TABS-->
+<!--SQL-->
+```sql
+SELECT col1, COUNT(*)
+FROM (
+  SELECT col1, col2, col3 FROM tbl1
+  UNION ALL
+  SELECT col1, col2, col3 FROM tbl2
+)
+GROUP BY col1
+```
 <!--Native-->
 ```json
 {
@@ -134,8 +144,6 @@ another will be treated as if they contained all null values in the tables where
 The list of "dataSources" must be nonempty. If you want to query an empty dataset, use an [`inline` datasource](#inline)
 instead.
 
-Union datasources are not available in Druid SQL.
-
 Refer to the [Query execution](query-execution.md#union) page for more details on how queries are executed when you
 use union datasources.