From 2060709bedadcc41e14ce96680ec99514301324a Mon Sep 17 00:00:00 2001 From: Ryan Kuo <8740013+taroface@users.noreply.github.com> Date: Mon, 9 Dec 2024 17:20:16 -0500 Subject: [PATCH] Clarify NOT VISIBLE indexes (#19168) * Clarify `NOT VISIBLE` indexes --------- Co-authored-by: Marcus Gartner --- src/current/v23.1/alter-index.md | 16 ++++++++-------- src/current/v23.1/indexes.md | 4 ++-- src/current/v23.2/alter-index.md | 14 +++++++------- src/current/v23.2/indexes.md | 4 ++-- src/current/v24.1/alter-index.md | 14 +++++++------- src/current/v24.1/indexes.md | 4 ++-- src/current/v24.2/alter-index.md | 14 +++++++------- src/current/v24.2/indexes.md | 4 ++-- src/current/v24.3/alter-index.md | 14 +++++++------- src/current/v24.3/indexes.md | 4 ++-- 10 files changed, 46 insertions(+), 46 deletions(-) diff --git a/src/current/v23.1/alter-index.md b/src/current/v23.1/alter-index.md index 8005a9c0024..f34257e4a65 100644 --- a/src/current/v23.1/alter-index.md +++ b/src/current/v23.1/alter-index.md @@ -162,20 +162,20 @@ For usage, see [Synopsis](#synopsis). ### `[NOT] VISIBLE` -`ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` sets the visibility of an index. This determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). +`ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). -By default, indexes are visible. If `NOT VISIBLE`, the index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). +By default, indexes are visible. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). In order to keep `NOT VISIBLE` indexes up to date, queries will still write to the index as they insert and update data in the table. -This allows you to create an index and check for query plan changes without affecting production queries. For an example, see [Set an index to be not visible](#set-an-index-to-be-not-visible). +This allows you to create an index and check for query plan changes without affecting production queries. For an example, refer to [Set an index to be not visible](#set-an-index-to-be-not-visible). -Note the following considerations: +Note the following considerations for index visibility: - Primary indexes must be visible. -- Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). -- Indexes that are not visible are still used for foreign key cascades. -- When defining a [unique constraint]({% link {{ page.version.version }}/unique.md %}), the `NOT VISIBLE` syntax cannot be used to make the corresponding index not visible. Instead, use `ALTER INDEX` after creating the unique constraint. +- Queries may still read from `NOT VISIBLE`, [`UNIQUE`]({% link {{ page.version.version }}/create-index.md %}#unique-indexes) indexes to enforce [`UNIQUE` constraints]({% link {{ page.version.version }}/unique.md %}). +- Queries may still read from `NOT VISIBLE` indexes to perform foreign key cascades and enforce [`FOREIGN KEY` constraints]({% link {{ page.version.version }}/foreign-key.md %}). +- When defining a [`UNIQUE` constraint]({% link {{ page.version.version }}/unique.md %}), you cannot use the `NOT VISIBLE` syntax to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the `UNIQUE` constraint. -For examples, see [Set index visibility](#set-index-visibility). +For examples, refer to [Set index visibility](#set-index-visibility). #### Aliases diff --git a/src/current/v23.1/indexes.md b/src/current/v23.1/indexes.md index ef9427df806..8dbd93b2bc8 100644 --- a/src/current/v23.1/indexes.md +++ b/src/current/v23.1/indexes.md @@ -60,9 +60,9 @@ Indexes create a trade-off: they greatly improve the speed of queries, but may s To maximize your indexes' performance, Cockroach Labs recommends following the [secondary index best practices]({% link {{ page.version.version }}/schema-design-indexes.md %}#best-practices). -To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. The index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, see [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). +To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, refer to [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). -Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). For more considerations, see [Index visibility considerations]({% link {{ page.version.version }}/alter-index.md %}#not-visible). +For more index visibility considerations, refer to [`[NOT] VISIBLE`]({% link {{ page.version.version }}/alter-index.md %}#not-visible). {{site.data.alerts.callout_danger}} {% include {{page.version.version}}/sql/add-size-limits-to-indexed-columns.md %} diff --git a/src/current/v23.2/alter-index.md b/src/current/v23.2/alter-index.md index 82b41513b8e..ff2106056e7 100644 --- a/src/current/v23.2/alter-index.md +++ b/src/current/v23.2/alter-index.md @@ -176,18 +176,18 @@ For usage, see [Synopsis](#synopsis). `ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). -By default, indexes are visible. If `NOT VISIBLE`, the index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). +By default, indexes are visible. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). In order to keep `NOT VISIBLE` indexes up to date, queries will still write to the index as they insert and update data in the table. -This allows you to create an index and check for query plan changes without affecting production queries. For an example, see [Set an index to be not visible](#set-an-index-to-be-not-visible). +This allows you to create an index and check for query plan changes without affecting production queries. For an example, refer to [Set an index to be not visible](#set-an-index-to-be-not-visible). -Note the following considerations: +Note the following considerations for index visibility: - Primary indexes must be visible. -- Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). -- Indexes that are not visible are still used for foreign key cascades. -- When defining a [unique constraint]({% link {{ page.version.version }}/unique.md %}), the `NOT VISIBLE` syntax cannot be used to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the unique constraint. +- Queries may still read from `NOT VISIBLE`, [`UNIQUE`]({% link {{ page.version.version }}/create-index.md %}#unique-indexes) indexes to enforce [`UNIQUE` constraints]({% link {{ page.version.version }}/unique.md %}). +- Queries may still read from `NOT VISIBLE` indexes to perform foreign key cascades and enforce [`FOREIGN KEY` constraints]({% link {{ page.version.version }}/foreign-key.md %}). +- When defining a [`UNIQUE` constraint]({% link {{ page.version.version }}/unique.md %}), you cannot use the `NOT VISIBLE` syntax to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the `UNIQUE` constraint. -For examples, see [Set index visibility](#set-index-visibility). +For examples, refer to [Set index visibility](#set-index-visibility). #### Aliases diff --git a/src/current/v23.2/indexes.md b/src/current/v23.2/indexes.md index ef9427df806..8dbd93b2bc8 100644 --- a/src/current/v23.2/indexes.md +++ b/src/current/v23.2/indexes.md @@ -60,9 +60,9 @@ Indexes create a trade-off: they greatly improve the speed of queries, but may s To maximize your indexes' performance, Cockroach Labs recommends following the [secondary index best practices]({% link {{ page.version.version }}/schema-design-indexes.md %}#best-practices). -To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. The index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, see [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). +To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, refer to [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). -Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). For more considerations, see [Index visibility considerations]({% link {{ page.version.version }}/alter-index.md %}#not-visible). +For more index visibility considerations, refer to [`[NOT] VISIBLE`]({% link {{ page.version.version }}/alter-index.md %}#not-visible). {{site.data.alerts.callout_danger}} {% include {{page.version.version}}/sql/add-size-limits-to-indexed-columns.md %} diff --git a/src/current/v24.1/alter-index.md b/src/current/v24.1/alter-index.md index a23e8cf4259..ff2106056e7 100644 --- a/src/current/v24.1/alter-index.md +++ b/src/current/v24.1/alter-index.md @@ -174,18 +174,18 @@ For usage, see [Synopsis](#synopsis). ### `[NOT] VISIBLE` -`ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determine whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). +`ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). -By default, indexes are visible. If `NOT VISIBLE`, the index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). +By default, indexes are visible. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). In order to keep `NOT VISIBLE` indexes up to date, queries will still write to the index as they insert and update data in the table. -This allows you to create an index and check for query plan changes without affecting production queries. For an example, see [Set an index to be not visible](#set-an-index-to-be-not-visible). +This allows you to create an index and check for query plan changes without affecting production queries. For an example, refer to [Set an index to be not visible](#set-an-index-to-be-not-visible). -Note the following considerations: +Note the following considerations for index visibility: - Primary indexes must be visible. -- Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). -- Indexes that are not visible are still used for foreign key cascades. -- When defining a [unique constraint]({% link {{ page.version.version }}/unique.md %}), the `NOT VISIBLE` syntax cannot be used to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the unique constraint. +- Queries may still read from `NOT VISIBLE`, [`UNIQUE`]({% link {{ page.version.version }}/create-index.md %}#unique-indexes) indexes to enforce [`UNIQUE` constraints]({% link {{ page.version.version }}/unique.md %}). +- Queries may still read from `NOT VISIBLE` indexes to perform foreign key cascades and enforce [`FOREIGN KEY` constraints]({% link {{ page.version.version }}/foreign-key.md %}). +- When defining a [`UNIQUE` constraint]({% link {{ page.version.version }}/unique.md %}), you cannot use the `NOT VISIBLE` syntax to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the `UNIQUE` constraint. For examples, refer to [Set index visibility](#set-index-visibility). diff --git a/src/current/v24.1/indexes.md b/src/current/v24.1/indexes.md index ef9427df806..8dbd93b2bc8 100644 --- a/src/current/v24.1/indexes.md +++ b/src/current/v24.1/indexes.md @@ -60,9 +60,9 @@ Indexes create a trade-off: they greatly improve the speed of queries, but may s To maximize your indexes' performance, Cockroach Labs recommends following the [secondary index best practices]({% link {{ page.version.version }}/schema-design-indexes.md %}#best-practices). -To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. The index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, see [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). +To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, refer to [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). -Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). For more considerations, see [Index visibility considerations]({% link {{ page.version.version }}/alter-index.md %}#not-visible). +For more index visibility considerations, refer to [`[NOT] VISIBLE`]({% link {{ page.version.version }}/alter-index.md %}#not-visible). {{site.data.alerts.callout_danger}} {% include {{page.version.version}}/sql/add-size-limits-to-indexed-columns.md %} diff --git a/src/current/v24.2/alter-index.md b/src/current/v24.2/alter-index.md index 82b41513b8e..ff2106056e7 100644 --- a/src/current/v24.2/alter-index.md +++ b/src/current/v24.2/alter-index.md @@ -176,18 +176,18 @@ For usage, see [Synopsis](#synopsis). `ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). -By default, indexes are visible. If `NOT VISIBLE`, the index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). +By default, indexes are visible. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). In order to keep `NOT VISIBLE` indexes up to date, queries will still write to the index as they insert and update data in the table. -This allows you to create an index and check for query plan changes without affecting production queries. For an example, see [Set an index to be not visible](#set-an-index-to-be-not-visible). +This allows you to create an index and check for query plan changes without affecting production queries. For an example, refer to [Set an index to be not visible](#set-an-index-to-be-not-visible). -Note the following considerations: +Note the following considerations for index visibility: - Primary indexes must be visible. -- Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). -- Indexes that are not visible are still used for foreign key cascades. -- When defining a [unique constraint]({% link {{ page.version.version }}/unique.md %}), the `NOT VISIBLE` syntax cannot be used to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the unique constraint. +- Queries may still read from `NOT VISIBLE`, [`UNIQUE`]({% link {{ page.version.version }}/create-index.md %}#unique-indexes) indexes to enforce [`UNIQUE` constraints]({% link {{ page.version.version }}/unique.md %}). +- Queries may still read from `NOT VISIBLE` indexes to perform foreign key cascades and enforce [`FOREIGN KEY` constraints]({% link {{ page.version.version }}/foreign-key.md %}). +- When defining a [`UNIQUE` constraint]({% link {{ page.version.version }}/unique.md %}), you cannot use the `NOT VISIBLE` syntax to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the `UNIQUE` constraint. -For examples, see [Set index visibility](#set-index-visibility). +For examples, refer to [Set index visibility](#set-index-visibility). #### Aliases diff --git a/src/current/v24.2/indexes.md b/src/current/v24.2/indexes.md index ef9427df806..8dbd93b2bc8 100644 --- a/src/current/v24.2/indexes.md +++ b/src/current/v24.2/indexes.md @@ -60,9 +60,9 @@ Indexes create a trade-off: they greatly improve the speed of queries, but may s To maximize your indexes' performance, Cockroach Labs recommends following the [secondary index best practices]({% link {{ page.version.version }}/schema-design-indexes.md %}#best-practices). -To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. The index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, see [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). +To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, refer to [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). -Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). For more considerations, see [Index visibility considerations]({% link {{ page.version.version }}/alter-index.md %}#not-visible). +For more index visibility considerations, refer to [`[NOT] VISIBLE`]({% link {{ page.version.version }}/alter-index.md %}#not-visible). {{site.data.alerts.callout_danger}} {% include {{page.version.version}}/sql/add-size-limits-to-indexed-columns.md %} diff --git a/src/current/v24.3/alter-index.md b/src/current/v24.3/alter-index.md index 82b41513b8e..ff2106056e7 100644 --- a/src/current/v24.3/alter-index.md +++ b/src/current/v24.3/alter-index.md @@ -176,18 +176,18 @@ For usage, see [Synopsis](#synopsis). `ALTER INDEX ... VISIBLE` and `ALTER INDEX ... NOT VISIBLE` determines whether the index is visible to the [cost-based optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}#control-whether-the-optimizer-uses-an-index). -By default, indexes are visible. If `NOT VISIBLE`, the index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). +By default, indexes are visible. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). In order to keep `NOT VISIBLE` indexes up to date, queries will still write to the index as they insert and update data in the table. -This allows you to create an index and check for query plan changes without affecting production queries. For an example, see [Set an index to be not visible](#set-an-index-to-be-not-visible). +This allows you to create an index and check for query plan changes without affecting production queries. For an example, refer to [Set an index to be not visible](#set-an-index-to-be-not-visible). -Note the following considerations: +Note the following considerations for index visibility: - Primary indexes must be visible. -- Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). -- Indexes that are not visible are still used for foreign key cascades. -- When defining a [unique constraint]({% link {{ page.version.version }}/unique.md %}), the `NOT VISIBLE` syntax cannot be used to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the unique constraint. +- Queries may still read from `NOT VISIBLE`, [`UNIQUE`]({% link {{ page.version.version }}/create-index.md %}#unique-indexes) indexes to enforce [`UNIQUE` constraints]({% link {{ page.version.version }}/unique.md %}). +- Queries may still read from `NOT VISIBLE` indexes to perform foreign key cascades and enforce [`FOREIGN KEY` constraints]({% link {{ page.version.version }}/foreign-key.md %}). +- When defining a [`UNIQUE` constraint]({% link {{ page.version.version }}/unique.md %}), you cannot use the `NOT VISIBLE` syntax to make the corresponding index not visible. Instead, use `ALTER INDEX ... NOT VISIBLE` after creating the `UNIQUE` constraint. -For examples, see [Set index visibility](#set-index-visibility). +For examples, refer to [Set index visibility](#set-index-visibility). #### Aliases diff --git a/src/current/v24.3/indexes.md b/src/current/v24.3/indexes.md index ef9427df806..8dbd93b2bc8 100644 --- a/src/current/v24.3/indexes.md +++ b/src/current/v24.3/indexes.md @@ -60,9 +60,9 @@ Indexes create a trade-off: they greatly improve the speed of queries, but may s To maximize your indexes' performance, Cockroach Labs recommends following the [secondary index best practices]({% link {{ page.version.version }}/schema-design-indexes.md %}#best-practices). -To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. The index will not be used in queries unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, see [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). +To observe the impact of an index without affecting a production workload, you can [create an index]({% link {{ page.version.version }}/create-index.md %}) using the `NOT VISIBLE` clause. If an index is `NOT VISIBLE`, queries will not read from the index unless it is specifically selected with an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection) or the property is overridden with the [`optimizer_use_not_visible_indexes` session variable]({% link {{ page.version.version }}/set-vars.md %}#optimizer-use-not-visible-indexes). For an example, refer to [Set an index to be not visible]({% link {{ page.version.version }}/alter-index.md %}#set-an-index-to-be-not-visible). -Indexes that are not visible are still used to enforce `UNIQUE` and `FOREIGN KEY` [constraints]({% link {{ page.version.version }}/constraints.md %}). For more considerations, see [Index visibility considerations]({% link {{ page.version.version }}/alter-index.md %}#not-visible). +For more index visibility considerations, refer to [`[NOT] VISIBLE`]({% link {{ page.version.version }}/alter-index.md %}#not-visible). {{site.data.alerts.callout_danger}} {% include {{page.version.version}}/sql/add-size-limits-to-indexed-columns.md %}