DOC-13246: Updates after review (#882)

Author: simon-dew

modules/ROOT/pages/index-partitions.adoc

@@ -15,7 +15,7 @@ include::partial$_show_page_header_block.adoc[]
 
 Partitioned indexes in Sync Gateway offer horizontal scalability for large deployments by sharding indexes across multiple nodes.
 This can decrease performance, as each partition is queried separately and results are aggregated.
-Only `allDocs` and channels indexes can be partitioned.
+Only `allDocs` and `channels` indexes can be partitioned.
 
 [#when-to-use]
 == When to Use Partitioned Indexes
@@ -55,10 +55,7 @@ The size of Sync Gateway's indexes is correlated to:
 * The number of documents in a collection.
 * The number of channels each document is assigned to.
 
-If index size is a concern, your first approach should be to:
-
-* Split documents across multiple collections.
-* Review and minimize channel fan-out.
+If index size is a concern, your first approach should be to split documents across multiple collections.
 
 Query performance is sensitive to channel design.
 Systems with many small channels tend to perform worse than those using fewer, larger channels.
@@ -86,7 +83,7 @@ The advantage is no downtime; the disadvantage is temporarily higher resource us
 
 . Wait for completion via xref:rest_api_admin_static.adoc#tag/Database-Management/operation/get_db-_index_init[`GET /{db}/_index_init`].
 
-. Run xref:rest_api_admin_static.adoc#tag/Database-Configuration/operation/post_db-_config[`POST /{db}/_config`] to use new indexes.
+. Run xref:rest_api_admin_static.adoc#tag/Database-Configuration/operation/post_db-_config[`POST /{db}/_config`] with `index.num_partitions` updated in the configuration to use new indexes.
 
 . Run xref:rest_api_admin_static.adoc#tag/Server/operation/post__post_upgrade[`POST /_post_upgrade`] to remove old indexes.
 
@@ -143,7 +140,7 @@ If your deployment uses xref:configuration-overview.adoc#lbl-config-grp[Configur
 Misalignment between config groups can lead to unexpected deletion of active indexes if xref:rest_api_admin_static.adoc#tag/Server/operation/post__post_upgrade[`POST /_post_upgrade`] is run.
 This will result in:
 
-* Doing a CBS sequential scan on the Query nodes, which will seriously degrade performance of Query nodes.
+* Couchbase Server (version 7.6 and later) falling back on a sequential scan of the Query nodes, which will seriously degrade Query performance.
 
 * Recreating indexes that were deleted by another config when a node is rebooted with a different `index.num_partitions`, even after xref:rest_api_admin_static.adoc#tag/Server/operation/post__post_upgrade[`POST /_post_upgrade`] is run.
 
@@ -155,9 +152,9 @@ This will result in:
 
 To identify the current index configuration, you can:
 
-* Use xref:rest_api_admin_static.adoc#tag/Database-Management/operation/get_db-_index_init[`GET /{db}/_index_init`] to verify the `settings.num_partitions` in use.
+* Use xref:rest_api_admin_static.adoc#tag/Database-Configuration/operation/get_db-_config[`GET /{db}/_config`] to check the active configuration in `index.num_partitions`.
 
-* Use xref:rest_api_admin_static.adoc#tag/Database-Configuration/operation/get_db-_config[`GET /{db}/_config`] to check the active configuration.
+* Use xref:rest_api_admin_static.adoc#tag/Database-Management/operation/get_db-_index_init[`GET /{db}/_index_init`] to see if there is an index creation in progress.
 
 [#failures]
 === Identify Failures

modules/ROOT/pages/indexing.adoc

@@ -21,9 +21,6 @@ Sync Gateway 3.3 supports partitioned indexes.
 This enables you to divide and spread a large index across multiple nodes.
 For details, see xref:index-partitions.adoc[].
 
-Sync Gateway 2.1 and earlier used system Views instead.
-You can continue to define views through the xref:rest_api_admin.adoc#tag/Unsupported[Sync Gateway Admin REST API], but this feature is unsupported.
-
 == Configuration
 This capability is enabled by default and is supported by two properties in the configuration file which can be adjusted:
 

modules/ROOT/pages/upgrading.adoc

@@ -274,7 +274,7 @@ When Sync Gateway starts, it will publish a Design Document which contains the V
       "channels":{
          "map":"function (doc, meta) { ... }"
       },
-      ...
+      // ...
    },
    "index_xattr_on_deleted_docs":true
 }
@@ -306,7 +306,7 @@ $ curl -X PUT http://localhost:8092/<BUCKET_NAME>/_design/dev_sync_gateway/ -d @
 
 This should return:
 
-[source,bash]
+[source,json]
 ----
 {"ok":true,"id":"_design/dev_sync_gateway"}
 ----
@@ -671,12 +671,14 @@ It is recommended to test the upgrade on a staging environment before upgrading
 
 The known issue xref:release-notes.adoc#2-5-0[CBG-394], means that the upgrade will *require downtime* when enabling shared bucket access on an existing deployment that is running with GSI indexing. This is to allow all documents to migrate, using index-based data requests whilst migration is in progress could result in an incomplete data set being returned (containing only those docs migrated at the time of the request). You are advised to schedule a maintenance window to allow time for migration to complete.
 
-| *Sync Gateway 2.1 or above*
-`index.num_replicas: 1`
-| *Sync Gateway 2.1 or above*
+| *Sync Gateway 2.1 to 3.2*
+`num_index_replicas: 2` (or n)
+| *Sync Gateway 3.3 or later*
 `index.num_replicas: 2` (or n)
 2+|
 After restarting Sync Gateway with the updated configuration file, the number of Index Replicas in the Couchbase Server cluster is automatically updated.
+
+As of Sync Gateway 3.3, `num_index_replicas` still works, but this option has been deprecated in favor of `index.num_replicas`.
 |===
 
 == Migrating from Bucket Shadowing

modules/ROOT/pages/whatsnew.adoc

@@ -26,7 +26,7 @@ include::partial$block-caveats.adoc[tags=eventing-mixed-mode]
 
 Sync Gateway 3.3 introduces support for partitioned indexes.
 Partitioned indexes offer horizontal scalability for large deployments by sharding indexes across multiple nodes.
-Only `allDocs` and channels indexes can be partitioned.
+Only `allDocs` and `channels` indexes can be partitioned.
 
 Partitioned indexes are not intended for general use in Sync Gateway.
 They may decrease performance, as each partition is queried separately and results are aggregated.
@@ -41,7 +41,7 @@ Sync Gateway 3.3 introduces an option to disable the xref:rest_api_public.adoc#t
 That operation is intended mainly for debugging in a small setup.
 With a large number of documents, it may lead to timeouts and out-of-memory conditions on the Query nodes.
 
-In any sizeable setup, it is recommended that you should instead use the xref:rest_api_public.adoc#tag/Database-Management/operation/get_keyspace-_changes[`GET /{keyspace}/_changes`] operation to get all documents for a user, or the xref:rest_api_public.adoc#tag/Document/operation/post_keyspace-_bulk_docs[`POST /{keyspace}/_bulk_docs`] operation to return any number of documents.
+In any sizeable setup, it is recommended that you should instead use the xref:rest_api_public.adoc#tag/Database-Management/operation/get_keyspace-_changes[`GET /{keyspace}/_changes`] operation to get all documents for a user, or the xref:rest_api_public.adoc#tag/Document/operation/post_keyspace-_bulk_docs[`POST /{keyspace}/_bulk_docs`] operation to return a specific subset of documents.
 
 To disable the xref:rest_api_public.adoc#tag/Document/operation/get_keyspace-_all_docs[`GET /{keyspace}/_all_docs`] operation in the Public REST API, set xref:configuration-schema-database.adoc#disable_public_all_docs[`disable_public_all_docs`] to `true` in the database configuration.
 This option is set to `false` by default; it will be set to `true` by default in a future release.