[couchdb-documentation] 01/01: Documentation for background indexing

[ko...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

kocolosk pushed a commit to branch ken-docs
in repository https://gitbox.apache.org/repos/asf/couchdb-documentation.git

commit c52130d0d4542386f7879ffb68e5b5d5751cc269
Author: Adam Kocoloski <ko...@apache.org>
AuthorDate: Wed Sep 11 15:46:40 2019 -0400

    Documentation for background indexing
---
 src/config/index.rst       |  1 +
 src/config/indexbuilds.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)

diff --git a/src/config/index.rst b/src/config/index.rst
index eebdc17..9ab1ace 100644
--- a/src/config/index.rst
+++ b/src/config/index.rst
@@ -26,6 +26,7 @@ Configuration
     http
     auth
     compaction
+    indexbuilds
     logging
     replicator
     query-servers
diff --git a/src/config/indexbuilds.rst b/src/config/indexbuilds.rst
new file mode 100644
index 0000000..ac51657
--- /dev/null
+++ b/src/config/indexbuilds.rst
@@ -0,0 +1,50 @@
+.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
+.. use this file except in compliance with the License. You may obtain a copy of
+.. the License at
+..
+..   http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+.. License for the specific language governing permissions and limitations under
+.. the License.
+
+.. default-domain:: config
+.. highlight:: ini
+
+===================
+Background Indexing
+===================
+
+Secondary indexes in CouchDB are not updated during document write operations. In order to
+avoid high latencies when reading indexes following a large block of writes, CouchDB
+automatically kicks off background jobs to keep secondary indexes "warm". The daemon
+responsible for this process is internally known as "ken" and can be configured using the
+following settings.
+
+.. _config/index_builds:
+
+.. config:section:: ken :: Background Index Builds
+
+    .. config:option:: batch_channels :: Steady-state build concurrency
+
+        This setting controls the number of background view builds that can be running in
+        parallel at any given time. The default is 20.
+
+    .. config:option:: incremental_channels :: Additional slots for short jobs
+
+        It is possible for all the slots in the normal build system to be occupied by
+        long-running index rebuilds (e.g. if new design documents are posted to several
+        databases simultaneously). In order to avoid already-built indexes from falling
+        behind when this occurs, CouchDB will allow for a number of short background
+        indexing jobs to run even when all slots are full. This setting controls how many
+        additional short jobs are allowed to run concurrently with the main jobs. The
+        default is 80.
+
+    .. config:option:: max_incremental_updates :: Threshold defining a job as short
+
+        CouchDB estimates whether an indexing job is "incremental" or not by looking at
+        the difference in sequence numbers between the current index and the main
+        database. If the difference is larger than the threshold defined here the
+        background job will only be allowed to run in the main queue. Defaults to 1000.