DOC-8207 -- PORT to 3.0-- Add query troubleshooting tip for re-create…

modules/ROOT/pages/_partials/_block-caveats.adoc

@@ -72,3 +72,12 @@ The use of TLS, its associated keys and certificates requires using secure stora
 The implementation of this storage differs from platform to platform -- see {xref-cbl-pg-p2psync-websocket-using-secure-storage}.
 
 // end::securestorage[]
+
+
+// tag::index-partial-value[]
+.Constraints
+[NOTE]
+Couchbase Lite for {param-platform} does not currently support partial value indexes; indexes with non-property expressions.
+You should only index with properties that you plan to use in the query.
+
+// end::index-partial-value[]

modules/ROOT/pages/_partials/commons/common-indexing.adoc

@@ -25,19 +25,18 @@
 //:this-url-issues: {par-url-issues}
 // END::REQUIRED EXTERNALS
 
-.Constraints
-NOTE:
-Couchbase Lite for {param-platform} does not currently supported partial value indexes; that is, indexes with non property expressions.
-You should only index with properties that you plan to use in the query.
-
-
 == Introduction
-
+// tag::overview[]
 Before we begin querying documents, let's briefly mention the importance of having an appropriate and balanced approach to indexes.
 
 Creating indexes can speed up the performance of queries.
 A query will typically return results more quickly if it can take advantage of an existing database index to search, narrowing down the set of documents to be examined.
 
+include::{root-partials}_block-caveats.adoc[tag=index-partial-value]
+
+//end::overview[]
+
+
 .Creating a new index
 ====
 

modules/ROOT/pages/_partials/commons/common-query-troubleshooting.adoc

@@ -154,6 +154,7 @@ Minimizing, if not eliminating, this ordering and re-ordering will obviously red
 Ask "is the grouping and-or ordering absolutely necessary?": if it isn't, drop it or modify it to minimize its impact.
 
 == Queries and Indexes
+
 include::{root-commons}indexing.adoc[tag=overview]
 
 The Query optimizer converts your query into a parse tree that groups zero or more _and-connected_ clauses together (as dictated by your `where` conditionals) for effective query engine processing.
@@ -163,6 +164,22 @@ Less good is if the query must scan the whole index; although the compact nature
 
 Searches that begin with or rely upon an inequality with the primary key are inherently less effective than those using a primary key equality.
 
+== Working with the Query Optimizer
+You may have noticed that sometimes a query runs faster on a second run, or after re-opening the database, or after deleting and recreating an index.
+This typically happens when SQL Query Optimizer has gathered sufficient stats to recognize a means of optimizing a sub-optimal query.
+
+If only those stats were available from the start.
+In fact they are gathered after certain events, such as:
+
+* Following index creation
+* On a database close
+* When running a database compact.
+
+So, if your analysis of the <<qe-output, Query Explain output>> indicates a sub-optimal query and your rewrites fail to sufficiently optimize it, consider compacting the database.
+Then re-generate the Query Explain and note any improvements in optimization.
+They may not, in themselves, resolve the issue entirely; but they can provide a uesful guide toward further optimizing changes you could make.
+
+
 [#use-like-based-queries]
 == Wildcard and Like-based Queries
 
@@ -258,6 +275,7 @@ include::{snippet}[tag="query-explain-nofunction", indent=0]
 Knowing this, you can consider how you create the index; for example, using {url-api-method-function-lower} when you create the index and then always using lowercase comparisons.
 
 == Optimization Considerations
+
 Try to minimize the amount of data retrieved.
 Reduce it down to the few properties you really *do* need to achieve the required result.