Gerir políticas de indexação no Azure Cosmos DBManage indexing policies in Azure Cosmos DB

Em Azure Cosmos DB, os dados são indexados seguindo as políticas de indexação definidas para cada recipiente.In Azure Cosmos DB, data is indexed following indexing policies that are defined for each container. A política de indexação predefinida para os contentores recém-criados impõe índices de intervalo para qualquer cadeia ou número.The default indexing policy for newly created containers enforces range indexes for any string or number. Esta política pode ser substituída pela sua própria política de indexação personalizada.This policy can be overridden with your own custom indexing policy.

Exemplos de política de indexaçãoIndexing policy examples

Eis alguns exemplos de políticas de indexação mostradas no seu formato JSON, que é como são expostas no portal Azure.Here are some examples of indexing policies shown in their JSON format, which is how they are exposed on the Azure portal. Os mesmos parâmetros podem ser definidos através do CLI Azure ou de qualquer SDK.The same parameters can be set through the Azure CLI or any SDK.

Política de opt-out para excluir seletivamente alguns caminhos de propriedadeOpt-out policy to selectively exclude some property paths

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/*"
            }
        ],
        "excludedPaths": [
            {
                "path": "/path/to/single/excluded/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/excluded/properties/*"
            }
        ]
    }

Esta política de indexação é equivalente à abaixo da que define manualmente kind , e aos seus dataType precision valores padrão.This indexing policy is equivalent to the one below which manually sets kind, dataType, and precision to their default values. Estas propriedades já não são necessárias para definir explicitamente e pode omiti-las inteiramente da sua política de indexação (como mostrado acima).These properties are no longer necessary to explicitly set and you can omit them from your indexing policy entirely (as shown in above example).

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/*",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number",
                        "precision": -1
                    },
                    {
                        "kind": "Range",
                        "dataType": "String",
                        "precision": -1
                    }
                ]
            }
        ],
        "excludedPaths": [
            {
                "path": "/path/to/single/excluded/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/excluded/properties/*"
            }
        ]
    }

Política de opt-in para incluir seletivamente alguns caminhos de propriedadeOpt-in policy to selectively include some property paths

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/path/to/included/property/?"
            },
            {
                "path": "/path/to/root/of/multiple/included/properties/*"
            }
        ],
        "excludedPaths": [
            {
                "path": "/*"
            }
        ]
    }

Esta política de indexação é equivalente à abaixo da que define manualmente kind , e aos seus dataType precision valores padrão.This indexing policy is equivalent to the one below which manually sets kind, dataType, and precision to their default values. Estas propriedades já não são necessárias para definir explicitamente e pode omiti-las inteiramente da sua política de indexação (como mostrado acima).These properties are no longer necessary to explicitly set and you can omit them from your indexing policy entirely (as shown in above example).

    {
        "indexingMode": "consistent",
        "includedPaths": [
            {
                "path": "/path/to/included/property/?",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number"
                    },
                    {
                        "kind": "Range",
                        "dataType": "String"
                    }
                ]
            },
            {
                "path": "/path/to/root/of/multiple/included/properties/*",
                "indexes": [
                    {
                        "kind": "Range",
                        "dataType": "Number"
                    },
                    {
                        "kind": "Range",
                        "dataType": "String"
                    }
                ]
            }
        ],
        "excludedPaths": [
            {
                "path": "/*"
            }
        ]
    }

Nota

É geralmente recomendado usar uma política de indexação de opt-out para permitir que a Azure Cosmos DB indexe proativamente qualquer nova propriedade que possa ser adicionada ao seu modelo.It is generally recommended to use an opt-out indexing policy to let Azure Cosmos DB proactively index any new property that may be added to your model.

Usando um índice espacial apenas num caminho de propriedade específicoUsing a spatial index on a specific property path only

{
    "indexingMode": "consistent",
    "automatic": true,
    "includedPaths": [
        {
            "path": "/*"
        }
    ],
    "excludedPaths": [
        {
            "path": "/_etag/?"
        }
    ],
    "spatialIndexes": [
        {
            "path": "/path/to/geojson/property/?",
            "types": [
                "Point",
                "Polygon",
                "MultiPolygon",
                "LineString"
            ]
        }
    ]
}

Exemplos de política de indexação compósitaComposite indexing policy examples

Além de incluir ou excluir caminhos para propriedades individuais, também pode especificar um índice composto.In addition to including or excluding paths for individual properties, you can also specify a composite index. Se você gostaria de realizar uma consulta que tenha uma ORDER BY cláusula para várias propriedades, é necessário um índice composto nessas propriedades.If you would like to perform a query that has an ORDER BY clause for multiple properties, a composite index on those properties is required. Além disso, os índices compostos terão um benefício de desempenho para consultas que têm um filtro e têm uma cláusula ORDER BY em diferentes propriedades.Additionally, composite indexes will have a performance benefit for queries that have a filter and have an ORDER BY clause on different properties.

Nota

Os caminhos compostos têm um implícito, uma /? vez que apenas o valor escalar nesse caminho é indexado.Composite paths have an implicit /? since only the scalar value at that path is indexed. O /* wildcard não é suportado em caminhos compostos.The /* wildcard is not supported in composite paths. Não deve especificar /? ou /* num caminho composto.You shouldn't specify /? or /* in a composite path.

Índice composto definido para (nome asc, idade desc):Composite index defined for (name asc, age desc):

    {  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"descending"
                }
            ]
        ]
    }

O índice composto acima referido sobre o nome e a idade é necessário para consultas #1 e #2 de consulta:The above composite index on name and age is required for Query #1 and Query #2:

#1 de consulta:Query #1:

    SELECT *
    FROM c
    ORDER BY c.name ASC, c.age DESC

#2 de consulta:Query #2:

    SELECT *
    FROM c
    ORDER BY c.name DESC, c.age ASC

Este índice composto beneficiará a #3 de consulta e a #4 de consulta e otimizará os filtros:This composite index will benefit Query #3 and Query #4 and optimize the filters:

#3 de consulta:Query #3:

SELECT *
FROM c
WHERE c.name = "Tim"
ORDER BY c.name DESC, c.age ASC

#4 de consulta:Query #4:

SELECT *
FROM c
WHERE c.name = "Tim" AND c.age > 18

Índice composto definido para (nome ASC, idade ASC) e (nome ASC, idade DESC):Composite index defined for (name ASC, age ASC) and (name ASC, age DESC):

Pode definir vários índices compostos diferentes dentro da mesma política de indexação.You can define multiple different composite indexes within the same indexing policy.

    {  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"ascending"
                }
            ],
            [  
                {  
                    "path":"/name",
                    "order":"ascending"
                },
                {  
                    "path":"/age",
                    "order":"descending"
                }
            ]
        ]
    }

Índice composto definido para (nome ASC, idade ASC):Composite index defined for (name ASC, age ASC):

É opcional especificar a encomenda.It is optional to specify the order. Se não for especificado, a ordem está a subir.If not specified, the order is ascending.

{  
        "automatic":true,
        "indexingMode":"Consistent",
        "includedPaths":[  
            {  
                "path":"/*"
            }
        ],
        "excludedPaths":[],
        "compositeIndexes":[  
            [  
                {  
                    "path":"/name",
                },
                {  
                    "path":"/age",
                }
            ]
        ]
}

Excluindo todos os caminhos imobiliários, mas mantendo a indexação ativaExcluding all property paths but keeping indexing active

Esta política pode ser utilizada em situações em que a funcionalidade Time-to-Live (TTL) está ativa, mas não é necessário um índice secundário (para utilizar a Azure Cosmos DB como uma loja de valor-chave pura).This policy can be used in situations where the Time-to-Live (TTL) feature is active but no secondary index is required (to use Azure Cosmos DB as a pure key-value store).

    {
        "indexingMode": "consistent",
        "includedPaths": [],
        "excludedPaths": [{
            "path": "/*"
        }]
    }

Sem indexaçãoNo indexing

Esta política vai desligar a indexação.This policy will turn off indexing. Se indexingMode estiver none programado, não é possível definir um TTL no recipiente.If indexingMode is set to none, you cannot set a TTL on the container.

    {
        "indexingMode": "none"
    }

Atualização da política de indexaçãoUpdating indexing policy

Na Azure Cosmos DB, a política de indexação pode ser atualizada utilizando qualquer um dos métodos abaixo:In Azure Cosmos DB, the indexing policy can be updated using any of the below methods:

  • do portal Azurefrom the Azure portal
  • usando o Azure CLIusing the Azure CLI
  • usando PowerShellusing PowerShell
  • usando um dos SDKsusing one of the SDKs

Uma atualização da política de indexação desencadeia uma transformação de índice.An indexing policy update triggers an index transformation. O progresso desta transformação também pode ser acompanhado pelos SDKs.The progress of this transformation can also be tracked from the SDKs.

Nota

Ao atualizar a política de indexação, escreve para a Azure Cosmos DB será ininterrupta.When updating indexing policy, writes to Azure Cosmos DB will be uninterrupted. Saiba mais sobre a indexação das transformaçõesLearn more about indexing transformations

Utilizar o portal do AzureUse the Azure portal

Os contentores Azure Cosmos armazenam a sua política de indexação como um documento JSON que o portal Azure permite editar diretamente.Azure Cosmos containers store their indexing policy as a JSON document that the Azure portal lets you directly edit.

  1. Inicie sessão no portal do Azure.Sign in to the Azure portal.

  2. Crie uma nova conta Azure Cosmos ou selecione uma conta existente.Create a new Azure Cosmos account or select an existing account.

  3. Abra o painel do Data Explorer e selecione o recipiente em que pretende trabalhar.Open the Data Explorer pane and select the container that you want to work on.

  4. Clique em Definições de & escala.Click on Scale & Settings.

  5. Modificar a política de indexação JSON documento (ver exemplos abaixo)Modify the indexing policy JSON document (see examples below)

  6. Clique em Guardar quando terminar.Click Save when you are done.

Gerir Indexação utilizando o portal Azure

Utilizar a CLI do AzureUse the Azure CLI

Para criar um recipiente com uma política de indexação personalizada ver, crie um recipiente com uma política de índice personalizado usando CLITo create a container with a custom indexing policy see, Create a container with a custom index policy using CLI

Utilizar o PowerShellUse PowerShell

Para criar um recipiente com uma política de indexação personalizada ver, crie um recipiente com uma política de índice personalizado usando PowershellTo create a container with a custom indexing policy see, Create a container with a custom index policy using Powershell

Utilize o .NET SDKUse the .NET SDK

O DocumentCollection objeto do .NET SDK v2 expõe uma IndexingPolicy propriedade que permite alterar e adicionar ou remover e IndexingMode IncludedPaths ExcludedPaths .The DocumentCollection object from the .NET SDK v2 exposes an IndexingPolicy property that lets you change the IndexingMode and add or remove IncludedPaths and ExcludedPaths.

// Retrieve the container's details
ResourceResponse<DocumentCollection> containerResponse = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("database", "container"));
// Set the indexing mode to consistent
containerResponse.Resource.IndexingPolicy.IndexingMode = IndexingMode.Consistent;
// Add an included path
containerResponse.Resource.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
// Add an excluded path
containerResponse.Resource.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/name/*" });
// Add a spatial index
containerResponse.Resource.IndexingPolicy.SpatialIndexes.Add(new SpatialSpec() { Path = "/locations/*", SpatialTypes = new Collection<SpatialType>() { SpatialType.Point } } );
// Add a composite index
containerResponse.Resource.IndexingPolicy.CompositeIndexes.Add(new Collection<CompositePath> {new CompositePath() { Path = "/name", Order = CompositePathSortOrder.Ascending }, new CompositePath() { Path = "/age", Order = CompositePathSortOrder.Descending }});
// Update container with changes
await client.ReplaceDocumentCollectionAsync(containerResponse.Resource);

Para acompanhar o progresso da transformação do índice, passe um RequestOptions objeto que define a propriedade para PopulateQuotaInfo true .To track the index transformation progress, pass a RequestOptions object that sets the PopulateQuotaInfo property to true.

// retrieve the container's details
ResourceResponse<DocumentCollection> container = await client.ReadDocumentCollectionAsync(UriFactory.CreateDocumentCollectionUri("database", "container"), new RequestOptions { PopulateQuotaInfo = true });
// retrieve the index transformation progress from the result
long indexTransformationProgress = container.IndexTransformationProgress;

Use o Java SDKUse the Java SDK

O DocumentCollection objeto do Java SDK (ver este Quickstart no que diz respeito à sua utilização) expõe e getIndexingPolicy() setIndexingPolicy() métodos.The DocumentCollection object from the Java SDK (see this Quickstart regarding its usage) exposes getIndexingPolicy() and setIndexingPolicy() methods. O IndexingPolicy objeto que manipulam permite alterar o modo de indexação e adicionar ou remover caminhos incluídos e excluídos.The IndexingPolicy object they manipulate lets you change the indexing mode and add or remove included and excluded paths.

// Retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), null);
containerResponse.subscribe(result -> {
DocumentCollection container = result.getResource();
IndexingPolicy indexingPolicy = container.getIndexingPolicy();

// Set the indexing mode to consistent
indexingPolicy.setIndexingMode(IndexingMode.Consistent);

// Add an included path

Collection<IncludedPath> includedPaths = new ArrayList<>();
IncludedPath includedPath = new IncludedPath();
includedPath.setPath("/*");
includedPaths.add(includedPath);
indexingPolicy.setIncludedPaths(includedPaths);

// Add an excluded path

Collection<ExcludedPath> excludedPaths = new ArrayList<>();
ExcludedPath excludedPath = new ExcludedPath();
excludedPath.setPath("/name/*");
excludedPaths.add(excludedPath);
indexingPolicy.setExcludedPaths(excludedPaths);

// Add a spatial index

Collection<SpatialSpec> spatialIndexes = new ArrayList<SpatialSpec>();
Collection<SpatialType> collectionOfSpatialTypes = new ArrayList<SpatialType>();

SpatialSpec spec = new SpatialSpec();
spec.setPath("/locations/*");
collectionOfSpatialTypes.add(SpatialType.Point);
spec.setSpatialTypes(collectionOfSpatialTypes);
spatialIndexes.add(spec);

indexingPolicy.setSpatialIndexes(spatialIndexes);

// Add a composite index

Collection<ArrayList<CompositePath>> compositeIndexes = new ArrayList<>();
ArrayList<CompositePath> compositePaths = new ArrayList<>();

CompositePath nameCompositePath = new CompositePath();
nameCompositePath.setPath("/name");
nameCompositePath.setOrder(CompositePathSortOrder.Ascending);

CompositePath ageCompositePath = new CompositePath();
ageCompositePath.setPath("/age");
ageCompositePath.setOrder(CompositePathSortOrder.Descending);

compositePaths.add(ageCompositePath);
compositePaths.add(nameCompositePath);

compositeIndexes.add(compositePaths);
indexingPolicy.setCompositeIndexes(compositeIndexes);

// Update the container with changes

 client.replaceCollection(container, null);
});

Para acompanhar o progresso da transformação do índice num contentor, passe um RequestOptions objeto que solicite a informação de quota para ser povoado e, em seguida, recupere o valor do cabeçalho de x-ms-documentdb-collection-index-transformation-progress resposta.To track the index transformation progress on a container, pass a RequestOptions object that requests the quota info to be populated, then retrieve the value from the x-ms-documentdb-collection-index-transformation-progress response header.

// set the RequestOptions object
RequestOptions requestOptions = new RequestOptions();
requestOptions.setPopulateQuotaInfo(true);
// retrieve the container's details
Observable<ResourceResponse<DocumentCollection>> containerResponse = client.readCollection(String.format("/dbs/%s/colls/%s", "database", "container"), requestOptions);
containerResponse.subscribe(result -> {
    // retrieve the index transformation progress from the response headers
    String indexTransformationProgress = result.getResponseHeaders().get("x-ms-documentdb-collection-index-transformation-progress");
});

Use o Node.js SDKUse the Node.js SDK

A ContainerDefinition interface deNode.js SDK (ver este Quickstart sobre a sua utilização) expõe uma indexingPolicy propriedade que permite alterar e adicionar ou remover e indexingMode includedPaths excludedPaths .The ContainerDefinition interface from Node.js SDK (see this Quickstart regarding its usage) exposes an indexingPolicy property that lets you change the indexingMode and add or remove includedPaths and excludedPaths.

Recupere os detalhes do contentorRetrieve the container's details

const containerResponse = await client.database('database').container('container').read();

Desa ajuste o modo de indexação para consistenteSet the indexing mode to consistent

containerResponse.body.indexingPolicy.indexingMode = "consistent";

Adicionar caminho incluído, incluindo um índice espacialAdd included path including a spatial index

containerResponse.body.indexingPolicy.includedPaths.push({
    includedPaths: [
      {
        path: "/age/*",
        indexes: [
          {
            kind: cosmos.DocumentBase.IndexKind.Range,
            dataType: cosmos.DocumentBase.DataType.String
          },
          {
            kind: cosmos.DocumentBase.IndexKind.Range,
            dataType: cosmos.DocumentBase.DataType.Number
          }
        ]
      },
      {
        path: "/locations/*",
        indexes: [
          {
            kind: cosmos.DocumentBase.IndexKind.Spatial,
            dataType: cosmos.DocumentBase.DataType.Point
          }
        ]
      }
    ]
  });

Adicionar caminho excluídoAdd excluded path

containerResponse.body.indexingPolicy.excludedPaths.push({ path: '/name/*' });

Atualizar o recipiente com alteraçõesUpdate the container with changes

const replaceResponse = await client.database('database').container('container').replace(containerResponse.body);

Para acompanhar o progresso da transformação do índice num recipiente, passe um RequestOptions objeto que define a propriedade populateQuotaInfo true para, em seguida, recupere o valor do cabeçalho de x-ms-documentdb-collection-index-transformation-progress resposta.To track the index transformation progress on a container, pass a RequestOptions object that sets the populateQuotaInfo property to true, then retrieve the value from the x-ms-documentdb-collection-index-transformation-progress response header.

// retrieve the container's details
const containerResponse = await client.database('database').container('container').read({
    populateQuotaInfo: true
});
// retrieve the index transformation progress from the response headers
const indexTransformationProgress = replaceResponse.headers['x-ms-documentdb-collection-index-transformation-progress'];

Utilizar o SDK PythonUse the Python SDK

Ao utilizar o Python SDK V3 (ver este Quickstart no que diz respeito à sua utilização), a configuração do recipiente é gerida como um dicionário.When using the Python SDK V3 (see this Quickstart regarding its usage), the container configuration is managed as a dictionary. A partir deste dicionário, é possível aceder à política de indexação e a todos os seus atributos.From this dictionary, it is possible to access the indexing policy and all its attributes.

Recupere os detalhes do contentorRetrieve the container's details

containerPath = 'dbs/database/colls/collection'
container = client.ReadContainer(containerPath)

Desa ajuste o modo de indexação para consistenteSet the indexing mode to consistent

container['indexingPolicy']['indexingMode'] = 'consistent'

Defina uma política de indexação com um caminho incluído e um índice espacialDefine an indexing policy with an included path and a spatial index

container["indexingPolicy"] = {

    "indexingMode":"consistent",
    "spatialIndexes":[
                {"path":"/location/*","types":["Point"]}
             ],
    "includedPaths":[{"path":"/age/*","indexes":[]}],
    "excludedPaths":[{"path":"/*"}]
}

Definir uma política de indexação com um caminho excluídoDefine an indexing policy with an excluded path

container["indexingPolicy"] = {
    "indexingMode":"consistent",
    "includedPaths":[{"path":"/*","indexes":[]}],
    "excludedPaths":[{"path":"/name/*"}]
}

Adicione um índice compostoAdd a composite index

container['indexingPolicy']['compositeIndexes'] = [
                [
                    {
                        "path": "/name",
                        "order": "ascending"
                    },
                    {
                        "path": "/age",
                        "order": "descending"
                    }
                ]
                ]

Atualizar o recipiente com alteraçõesUpdate the container with changes

response = client.ReplaceContainer(containerPath, container)

Passos seguintesNext steps

Leia mais sobre a indexação nos seguintes artigos:Read more about the indexing in the following articles: