Merge pull request #215080 from jcocchi/index-pk-for-exclude-policy

update indexing docs for including partition key with exclude strategy

Author: prmerger-automator[bot]

articles/cosmos-db/index-policy.md

@@ -26,12 +26,12 @@ In some situations, you may want to override this automatic behavior to better s
 Azure Cosmos DB supports two indexing modes:
 
 - **Consistent**: The index is updated synchronously as you create, update or delete items. This means that the consistency of your read queries will be the [consistency configured for the account](consistency-levels.md).
-- **None**: Indexing is disabled on the container. This is commonly used when a container is used as a pure key-value store without the need for secondary indexes. It can also be used to improve the performance of bulk operations. After the bulk operations are complete, the index mode can be set to Consistent and then monitored using the [IndexTransformationProgress](how-to-manage-indexing-policy.md#dotnet-sdk) until complete.
+- **None**: Indexing is disabled on the container. This mode is commonly used when a container is used as a pure key-value store without the need for secondary indexes. It can also be used to improve the performance of bulk operations. After the bulk operations are complete, the index mode can be set to Consistent and then monitored using the [IndexTransformationProgress](how-to-manage-indexing-policy.md#dotnet-sdk) until complete.
 
 > [!NOTE]
 > Azure Cosmos DB also supports a Lazy indexing mode. Lazy indexing performs updates to the index at a much lower priority level when the engine is not doing any other work. This can result in **inconsistent or incomplete** query results. If you plan to query an Azure Cosmos DB container, you should not select lazy indexing. New containers cannot select lazy indexing. You can request an exemption by contacting [email protected] (except if you are using an Azure Cosmos DB account in [serverless](serverless.md) mode which doesn't support lazy indexing).
 
-By default, indexing policy is set to `automatic`. It's achieved by setting the `automatic` property in the indexing policy to `true`. Setting this property to `true` allows Azure Cosmos DB to automatically index documents as they are written.
+By default, indexing policy is set to `automatic`. It's achieved by setting the `automatic` property in the indexing policy to `true`. Setting this property to `true` allows Azure Cosmos DB to automatically index documents as they're written.
 
 ## <a id="index-size"></a>Index size
 
@@ -71,16 +71,17 @@ Taking the same example again:
 
 - the path to anything under `headquarters` is `/headquarters/*`
 
-For example, we could include the `/headquarters/employees/?` path. This path would ensure that we index the employees property but would not index additional nested JSON within this property.
+For example, we could include the `/headquarters/employees/?` path. This path would ensure that we index the employees property but wouldn't index additional nested JSON within this property.
 
 ## Include/exclude strategy
 
 Any indexing policy has to include the root path `/*` as either an included or an excluded path.
 
-- Include the root path to selectively exclude paths that don't need to be indexed. This is the recommended approach as it lets Azure Cosmos DB proactively index any new property that may be added to your model.
-- Exclude the root path to selectively include paths that need to be indexed.
+- Include the root path to selectively exclude paths that don't need to be indexed. This approach is recommended as it lets Azure Cosmos DB proactively index any new property that may be added to your model.
 
-- For paths with regular characters that include: alphanumeric characters and _ (underscore), you don't have to escape the path string around double quotes (for example, "/path/?"). For paths with other special characters, you need to escape the path string around double quotes (for example, "/\"path-abc\"/?"). If you expect special characters in your path, you can escape every path for safety. Functionally, it doesn't make any difference if you escape every path Vs just the ones that have special characters.
+- Exclude the root path to selectively include paths that need to be indexed. The partition key property path isn't indexed by default with the exclude strategy and should be explicitly included if needed.
+
+- For paths with regular characters that include: alphanumeric characters and _ (underscore), you don't have to escape the path string around double quotes (for example, "/path/?"). For paths with other special characters, you need to escape the path string around double quotes (for example, "/\"path-abc\"/?"). If you expect special characters in your path, you can escape every path for safety. Functionally, it doesn't make any difference if you escape every path or just the ones that have special characters.
 
 - The system property `_etag` is excluded from indexing by default, unless the etag is added to the included path for indexing.
 
@@ -92,9 +93,9 @@ When including and excluding paths, you may encounter the following attributes:
 
 - `precision` is a number defined at the index level for included paths. A value of `-1` indicates maximum precision. We recommend always setting this value to `-1`.
 
-- `dataType` can be either `String` or `Number`. This indicates the types of JSON properties which will be indexed.
+- `dataType` can be either `String` or `Number`. This indicates the types of JSON properties that will be indexed.
 
-It is no longer necessary to set these properties. When not specified, these properties will have the following default values:
+It's no longer necessary to set these properties. When not specified, these properties will have the following default values:
 
 | **Property Name**     | **Default Value** |
 | ----------------------- | -------------------------------- |
@@ -114,7 +115,7 @@ Here's an example:
 
 **Excluded Path**: `/food/ingredients/*`
 
-In this case, the included path takes precedence over the excluded path because it is more precise. Based on these paths, any data in the `food/ingredients` path or nested within would be excluded from the index. The exception would be data within the included path: `/food/ingredients/nutrition/*`, which would be indexed.
+In this case, the included path takes precedence over the excluded path because it's more precise. Based on these paths, any data in the `food/ingredients` path or nested within would be excluded from the index. The exception would be data within the included path: `/food/ingredients/nutrition/*`, which would be indexed.
 
 Here are some rules for included and excluded paths precedence in Azure Cosmos DB:
 
@@ -136,13 +137,13 @@ When you define a spatial path in the indexing policy, you should define which i
 
 * LineString
 
-Azure Cosmos DB, by default, will not create any spatial indexes. If you would like to use spatial SQL built-in functions, you should create a spatial index on the required properties. See [this section](sql-query-geospatial-index.md) for indexing policy examples for adding spatial indexes.
+Azure Cosmos DB, by default, won't create any spatial indexes. If you would like to use spatial SQL built-in functions, you should create a spatial index on the required properties. See [this section](sql-query-geospatial-index.md) for indexing policy examples for adding spatial indexes.
 
 ## Composite indexes
 
 Queries that have an `ORDER BY` clause with two or more properties require a composite index. You can also define a composite index to improve the performance of many equality and range queries. By default, no composite indexes are defined so you should [add composite indexes](how-to-manage-indexing-policy.md#composite-index) as needed.
 
-Unlike with included or excluded paths, you can't create a path with the `/*` wildcard. Every composite path has an implicit `/?` at the end of the path that you don't need to specify. Composite paths lead to a scalar value and this is the only value that is included in the composite index.
+Unlike with included or excluded paths, you can't create a path with the `/*` wildcard. Every composite path has an implicit `/?` at the end of the path that you don't need to specify. Composite paths lead to a scalar value that is the only value included in the composite index.
 
 When defining a composite index, you specify:
 
@@ -157,7 +158,7 @@ When defining a composite index, you specify:
 
 The following considerations are used when using composite indexes for queries with an `ORDER BY` clause with two or more properties:
 
-- If the composite index paths do not match the sequence of the properties in the `ORDER BY` clause, then the composite index can't support the query.
+- If the composite index paths don't match the sequence of the properties in the `ORDER BY` clause, then the composite index can't support the query.
 
 - The order of composite index paths (ascending or descending) should also match the `order` in the `ORDER BY` clause.
 
@@ -180,15 +181,15 @@ You should customize your indexing policy so you can serve all necessary `ORDER
 
 If a query has filters on two or more properties, it may be helpful to create a composite index for these properties.
 
-For example, consider the following query which has both an equality and range filter:
+For example, consider the following query that has both an equality and range filter:
 
 ```sql
 SELECT *
 FROM c
 WHERE c.name = "John" AND c.age > 18
 ```
 
-This query will be more efficient, taking less time and consuming fewer RU's, if it is able to leverage a composite index on `(name ASC, age ASC)`.
+This query will be more efficient, taking less time and consuming fewer RUs, if it's able to leverage a composite index on `(name ASC, age ASC)`.
 
 Queries with multiple range filters can also be optimized with a composite index. However, each individual composite index can only optimize a single range filter. Range filters include `>`, `<`, `<=`, `>=`, and `!=`. The range filter should be defined last in the composite index.
 
@@ -200,13 +201,13 @@ FROM c
 WHERE c.name = "John" AND c.age > 18 AND c._ts > 1612212188
 ```
 
-This query will be more efficient with a composite index on `(name ASC, age ASC)` and `(name ASC, _ts ASC)`. However, the query would not utilize a composite index on `(age ASC, name ASC)` because the properties with equality filters must be defined first in the composite index. Two separate composite indexes are required instead of a single composite index on `(name ASC, age ASC, _ts ASC)` since each composite index can only optimize a single range filter.
+This query will be more efficient with a composite index on `(name ASC, age ASC)` and `(name ASC, _ts ASC)`. However, the query wouldn't utilize a composite index on `(age ASC, name ASC)` because the properties with equality filters must be defined first in the composite index. Two separate composite indexes are required instead of a single composite index on `(name ASC, age ASC, _ts ASC)` since each composite index can only optimize a single range filter.
 
 The following considerations are used when creating composite indexes for queries with filters on multiple properties
 
 - Filter expressions can use multiple composite indexes.
-- The properties in the query's filter should match those in composite index. If a property is in the composite index but is not included in the query as a filter, the query will not utilize the composite index.
-- If a query has additional properties in the filter that were not defined in a composite index, then a combination of composite and range indexes will be used to evaluate the query. This will require fewer RU's than exclusively using range indexes.
+- The properties in the query's filter should match those in composite index. If a property is in the composite index but isn't included in the query as a filter, the query won't utilize the composite index.
+- If a query has other properties in the filter that aren't defined in a composite index, then a combination of composite and range indexes will be used to evaluate the query. This will require fewer RUs than exclusively using range indexes.
 - If a property has a range filter (`>`, `<`, `<=`, `>=`, or `!=`), then this property should be defined last in the composite index. If a query has more than one range filter, it may benefit from multiple composite indexes.
 - When creating a composite index to optimize queries with multiple filters, the `ORDER` of the composite index will have no impact on the results. This property is optional.
 
@@ -289,8 +290,8 @@ ORDER BY c.firstName, c.lastName
 
 The following considerations apply when creating composite indexes to optimize a query with a filter and `ORDER BY` clause:
 
-* If you do not define a composite index on a query with a filter on one property and a separate `ORDER BY` clause using a different property, the query will still succeed. However, the RU cost of the query can be reduced with a composite index, particularly if the property in the `ORDER BY` clause has a high cardinality.
-* If the query filters on properties, these should be included first in the `ORDER BY` clause.
+* If you don't define a composite index on a query with a filter on one property and a separate `ORDER BY` clause using a different property, the query will still succeed. However, the RU cost of the query can be reduced with a composite index, particularly if the property in the `ORDER BY` clause has a high cardinality.
+* If the query filters on properties, these properties should be included first in the `ORDER BY` clause.
 * If the query filters on multiple properties, the equality filters must be the first properties in the `ORDER BY` clause.
 * If the query filters on multiple properties, you can have a maximum of one range filter or system function utilized per composite index. The property used in the range filter or system function should be defined last in the composite index.
 * All considerations for creating composite indexes for `ORDER BY` queries with multiple properties as well as queries with filters on multiple properties still apply.
@@ -316,7 +317,7 @@ The following considerations apply when creating composite indexes to optimize a
 * If the query filters on multiple properties, the equality filters must be the first properties in the composite index.
 * You can have a maximum of one range filter per composite index and it must be on the property in the aggregate system function.
 * The property in the aggregate system function should be defined last in the composite index.
-* The `order` (`ASC` or `DESC`) does not matter.
+* The `order` (`ASC` or `DESC`) doesn't matter.
 
 | **Composite Index**                      | **Sample Query**                                  | **Supported by Composite Index?** |
 | ---------------------------------------- | ------------------------------------------------------------ | --------------------------------- |
@@ -336,13 +337,13 @@ A container's indexing policy can be updated at any time [by using the Azure por
 > [!NOTE]
 > You can track the progress of index transformation in the Azure portal or [by using one of the SDKs](how-to-manage-indexing-policy.md).
 
-There is no impact to write availability during any index transformations. The index transformation uses your provisioned RUs but at a lower priority than your CRUD operations or queries.
+There's no impact to write availability during any index transformations. The index transformation uses your provisioned RUs but at a lower priority than your CRUD operations or queries.
 
-There is no impact to read availability when adding new indexed paths. Queries will only utilize new indexed paths once an index transformation is complete. In other words, when adding a new indexed paths, queries that benefit from that indexed path will have the same performance before and during the index transformation. After the index transformation is complete, the query engine will begin to use the new indexed paths.
+There's no impact to read availability when adding new indexed paths. Queries will only utilize new indexed paths once an index transformation is complete. In other words, when adding a new indexed path, queries that benefit from that indexed path will have the same performance before and during the index transformation. After the index transformation is complete, the query engine will begin to use the new indexed paths.
 
-When removing indexed paths, you should group all your changes into one indexing policy transformation. If you remove multiple indexes and do so in one single indexing policy change, the query engine provides consistent and complete results throughout the index transformation. However, if you remove indexes through multiple indexing policy changes, the query engine will not provide consistent or complete results until all index transformations complete. Most developers do not drop indexes and then immediately try to run queries that utilize these indexes so, in practice, this situation is unlikely.
+When removing indexed paths, you should group all your changes into one indexing policy transformation. If you remove multiple indexes and do so in one single indexing policy change, the query engine provides consistent and complete results throughout the index transformation. However, if you remove indexes through multiple indexing policy changes, the query engine won't provide consistent or complete results until all index transformations complete. Most developers don't drop indexes and then immediately try to run queries that utilize these indexes so, in practice, this situation is unlikely.
 
-When you drop an indexed path, the query engine will immediately stop using it and instead do a full scan.
+When you drop an indexed path, the query engine will immediately stop using it, and will do a full scan instead.
 
 > [!NOTE]
 > Where possible, you should always try to group multiple indexing changes into one single indexing policy modification
@@ -351,8 +352,8 @@ When you drop an indexed path, the query engine will immediately stop using it a
 
 Using the [Time-to-Live (TTL) feature](time-to-live.md) requires indexing. This means that:
 
-- it is not possible to activate TTL on a container where the indexing mode is set to `none`,
-- it is not possible to set the indexing mode to None on a container where TTL is activated.
+- it isn't possible to activate TTL on a container where the indexing mode is set to `none`,
+- it isn't possible to set the indexing mode to None on a container where TTL is activated.
 
 For scenarios where no property path needs to be indexed, but TTL is required, you can use an indexing policy with an indexing mode set to `consistent`, no included paths, and `/*` as the only excluded path.