Merge pull request #5795 from cockroachdb/20191104-opt-histogram-setting

Document optimizer histogram setting

v19.2/cost-based-optimizer.md

@@ -76,6 +76,21 @@ If you need to turn off automatic statistics collection, follow the steps below:
 
 For instructions showing how to manually generate statistics, see the examples in the [`CREATE STATISTICS` documentation](create-statistics.html).
 
+#### Controlling histogram collection
+
+<span class="version-tag">New in v19.2:</span> By default, the optimizer collects histograms for all index columns (specifically the first column in each index) during automatic statistics collection. If a single column statistic is explicitly requested using manual invocation of [`CREATE STATISTICS`](create-statistics.html), a histogram will be collected, regardless of whether or not the column is part of an index.
+
+If you are an advanced user and need to disable histogram collection for troubleshooting or performance tuning reasons, change the [`sql.stats.histogram_collection.enabled` cluster setting](cluster-settings.html) by running [`SET CLUSTER SETTING`](set-cluster-setting.html) as follows:
+
+{% include copy-clipboard.html %}
+~~~ sql
+SET CLUSTER SETTING sql.stats.histogram_collection.enabled = false;
+~~~
+
+{{site.data.alerts.callout_info}}
+When `sql.stats.histogram_collection.enabled` is set to `false`, histograms are never collected, either as part of automatic statistics collection or by manual invocation of [`CREATE STATISTICS`](create-statistics.html).
+{{site.data.alerts.end}}
+
 ## Query plan cache
 
 CockroachDB uses a cache for the query plans generated by the optimizer. This can lead to faster query execution since the database can reuse a query plan that was previously calculated, rather than computing a new plan each time a query is executed.
@@ -599,6 +614,7 @@ You'll need to make changes to the above configuration to reflect your [producti
 
 - [`SET (session variable)`](set-vars.html)
 - [`SET CLUSTER SETTING`](set-cluster-setting.html)
+- [`RESET CLUSTER SETTING`](reset-cluster-setting.html)
 - [`SHOW (session variable)`](show-vars.html)
 - [`CREATE STATISTICS`](create-statistics.html)
 - [`SHOW STATISTICS`](show-statistics.html)