IMPALA-6803: [DOCS] Clarify scope of STRAIGHT_JOIN hint

Add some boilerplate wording and reuse the same text
in several likely spots where readers might expect it
(under the pages for performance tuning with joins, hints,
views, and subqueries).

Change-Id: Ibd8e4d8e5260f5a2b7b5c52dc3269bb373b9c76f
Reviewed-on: http://gerrit.cloudera.org:8080/8336
Reviewed-by: Alex Behm <[email protected]>
Tested-by: Impala Public Jenkins

docs/shared/impala_common.xml

@@ -2864,6 +2864,13 @@ flight_num:           INT32 SNAPPY DO:83456393 FPO:83488603 SZ:10216514/11474301
         <codeph>SELECT</codeph> and any <codeph>DISTINCT</codeph> or <codeph>ALL</codeph> keywords.
       </p>
 
+      <p id="straight_join_nested_queries" rev="IMPALA-6083">
+        The <codeph>STRAIGHT_JOIN</codeph> hint affects the join order of table references in the query
+        block containing the hint. It does not affect the join order of nested queries, such as views,
+        inline views, or <codeph>WHERE</codeph>-clause subqueries. To use this hint for performance
+        tuning of complex queries, apply the hint to all query blocks that need a fixed join order.
+      </p>
+
       <p id="catalog_server_124">
         In Impala 1.2.4 and higher, you can specify a table name with <codeph>INVALIDATE METADATA</codeph> after
         the table is created in Hive, allowing you to make individual tables visible to Impala without doing a full

docs/topics/impala_hints.xml

@@ -136,6 +136,8 @@ INSERT <varname>insert_clauses</varname>
       reordering the tables in a way that makes the join-related hints ineffective.
     </p>
 
+    <p conref="../shared/impala_common.xml#common/straight_join_nested_queries"/>
+
     <p>
       To reduce the need to use hints, run the <codeph>COMPUTE STATS</codeph> statement against all tables involved
       in joins, or used as the source tables for <codeph>INSERT ... SELECT</codeph> operations where the

docs/topics/impala_perf_joins.xml

@@ -157,6 +157,10 @@ under the License.
         table is on the left, followed by the next largest, and so on until the smallest table is on the right.
       </p>
 
+      <note>
+        <p conref="../shared/impala_common.xml#common/straight_join_nested_queries"/>
+      </note>
+
       <p>
         In this example, the subselect from the <codeph>BIG</codeph> table produces a very small result set, but
         the table might still be treated as if it were the biggest and placed first in the join order. Using

docs/topics/impala_subqueries.xml

@@ -202,6 +202,8 @@ Therefore, this is not an efficient construct to use with Impala queries for HBa
 <codeblock>SELECT * FROM t1 one WHERE id IN (SELECT parent FROM t1 two WHERE t1.parent = t2.id);
 </codeblock>
 
+    <p conref="../shared/impala_common.xml#common/straight_join_nested_queries"/>
+
     <p conref="../shared/impala_common.xml#common/internals_blurb"/>
 
     <p>

docs/topics/impala_views.xml

@@ -173,6 +173,8 @@ select * from top_10_days;</codeblock>
 
     <p conref="../shared/impala_common.xml#common/complex_types_views"/>
 
+    <p conref="../shared/impala_common.xml#common/straight_join_nested_queries"/>
+
     <p conref="../shared/impala_common.xml#common/restrictions_blurb"/>
 
     <ul>