Skip to content

Commit 1efa0a4

Browse files
authored
DOC-8207 -- PORT to 3.0-- Add query troubleshooting tip for re-create index (#444) (#445)
https://issues.couchbase.com/browse/DOC-8207 (cherry picked from commit 7fc1dcc)
1 parent 03a3d83 commit 1efa0a4

File tree

3 files changed

+33
-7
lines changed

3 files changed

+33
-7
lines changed

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -72,3 +72,12 @@ The use of TLS, its associated keys and certificates requires using secure stora
7272
The implementation of this storage differs from platform to platform -- see {xref-cbl-pg-p2psync-websocket-using-secure-storage}.
7373

7474
// end::securestorage[]
75+
76+
77+
// tag::index-partial-value[]
78+
.Constraints
79+
[NOTE]
80+
Couchbase Lite for {param-platform} does not currently support partial value indexes; indexes with non-property expressions.
81+
You should only index with properties that you plan to use in the query.
82+
83+
// end::index-partial-value[]

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

Lines changed: 6 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,19 +25,18 @@
2525
//:this-url-issues: {par-url-issues}
2626
// END::REQUIRED EXTERNALS
2727

28-
.Constraints
29-
NOTE:
30-
Couchbase Lite for {param-platform} does not currently supported partial value indexes; that is, indexes with non property expressions.
31-
You should only index with properties that you plan to use in the query.
32-
33-
3428
== Introduction
35-
29+
// tag::overview[]
3630
Before we begin querying documents, let's briefly mention the importance of having an appropriate and balanced approach to indexes.
3731

3832
Creating indexes can speed up the performance of queries.
3933
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.
4034

35+
include::{root-partials}_block-caveats.adoc[tag=index-partial-value]
36+
37+
//end::overview[]
38+
39+
4140
.Creating a new index
4241
====
4342

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

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -154,6 +154,7 @@ Minimizing, if not eliminating, this ordering and re-ordering will obviously red
154154
Ask "is the grouping and-or ordering absolutely necessary?": if it isn't, drop it or modify it to minimize its impact.
155155

156156
== Queries and Indexes
157+
157158
include::{root-commons}indexing.adoc[tag=overview]
158159

159160
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
163164

164165
Searches that begin with or rely upon an inequality with the primary key are inherently less effective than those using a primary key equality.
165166

167+
== Working with the Query Optimizer
168+
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.
169+
This typically happens when SQL Query Optimizer has gathered sufficient stats to recognize a means of optimizing a sub-optimal query.
170+
171+
If only those stats were available from the start.
172+
In fact they are gathered after certain events, such as:
173+
174+
* Following index creation
175+
* On a database close
176+
* When running a database compact.
177+
178+
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.
179+
Then re-generate the Query Explain and note any improvements in optimization.
180+
They may not, in themselves, resolve the issue entirely; but they can provide a uesful guide toward further optimizing changes you could make.
181+
182+
166183
[#use-like-based-queries]
167184
== Wildcard and Like-based Queries
168185

@@ -258,6 +275,7 @@ include::{snippet}[tag="query-explain-nofunction", indent=0]
258275
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.
259276

260277
== Optimization Considerations
278+
261279
Try to minimize the amount of data retrieved.
262280
Reduce it down to the few properties you really *do* need to achieve the required result.
263281

0 commit comments

Comments
 (0)