Como configurar o Azure Cosmos DB para exibições materializadas NoSQL (visualização)

APLICA-SE A: NoSQL

Importante

As exibições materializadas do Azure Cosmos DB para NoSQL estão atualmente em visualização. Você pode habilitar esse recurso usando o portal do Azure. Esta pré-visualização é fornecida sem um contrato de nível de serviço. No momento, não recomendamos que você use exibições materializadas para cargas de trabalho de produção. Alguns recursos desta visualização podem não ser suportados ou podem ter recursos restritos. Para obter mais informações, consulte os termos de uso suplementares para visualizações do Microsoft Azure.

As visualizações materializadas fornecem uma maneira poderosa de otimizar o desempenho da consulta e simplificar a lógica do aplicativo, criando exibições de seus dados com uma chave de partição diferente e/ou modelo de dados. Este artigo descreve como criar exibições materializadas e como usá-las para lidar com consultas entre partições de forma eficiente.

Pré-requisitos

• Uma conta existente do Azure Cosmos DB.
  • Se você tiver uma assinatura do Azure, crie uma nova conta.
  • Se não tiver uma subscrição do Azure, crie uma conta gratuita antes de começar.
  • Como alternativa, você pode experimentar o Azure Cosmos DB gratuitamente antes de confirmar.

Habilitar visualizações materializadas

O recurso de exibições materializadas precisa ser habilitado para sua conta do Azure Cosmos DB antes de provisionar um construtor ou criar modos de exibição.

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Vá para sua conta do Azure Cosmos DB para NoSQL.

3. No menu de recursos, selecione Configurações.

4. Na seção Recursos em Configurações, alterne a opção Modo de Exibição Materializado para API NoSQL (visualização) para Ativado.

5. Na nova caixa de diálogo, selecione Ativar para habilitar esse recurso para a conta.

CLI do Azure

Use a CLI do Azure para habilitar o recurso de exibições materializadas usando um comando nativo ou uma operação de API REST em sua conta do Azure Cosmos DB para NoSQL.

1. Entre na CLI do Azure.

   Azure CLI

   az login
   

   Nota

   Isso requer a CLI do Azure, veja como instalar a CLI do Azure.

2. Defina as variáveis para o grupo de recursos e o nome da conta do Azure Cosmos DB para NoSQL existente.

   Azure CLI

   # Variable for resource group name
   $resourceGroupName="<resource-group-name>"
   
   # Variable for account name
   $accountName="<account-name>"
   
   # Variable for Azure subscription
   $subscriptionId="<subscription-id>"
   

3. Crie um novo arquivo JSON chamado capabilities.json usando o manifesto de recursos.

   JSON

   {
     "properties": {
       "enableMaterializedViews": true
     }
   }
   

4. Obtenha o identificador da conta e armazene-o em uma variável de shell chamada $accountId.

   Azure CLI

   $accountId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"
   

5. Habilite o recurso de visualização de visualizações materializadas para a conta usando a API REST e az rest com um verbo HTTP PATCH .

   Azure CLI

   az rest \
       --method PATCH \
       --uri "https://management.azure.com/$accountId/?api-version=2022-11-15-preview" \
       --body @capabilities.json
   

Criar um construtor de vistas materializado

Depois que o recurso de exibições materializadas estiver habilitado para sua conta, você verá uma nova página na seção Configurações do portal do Azure para o Construtor de Exibições Materializadas. Você deve provisionar um construtor de visualizações materializadas antes de criar exibições em sua conta. O construtor é responsável por hidratar automaticamente os dados nas visualizações e mantê-los sincronizados com os contêineres de origem. Saiba mais sobre as opções de provisionamento do construtor de exibição materializado.

Portal do Azure

1. Inicie sessão no portal do Azure.

2. Vá para sua conta do Azure Cosmos DB para NoSQL.

3. No menu de recursos, selecione Construtor de Visualizações Materializadas.

4. Na página Construtor de Visualizações Materializadas, configure a SKU e o número de instâncias para o construtor.

   Nota

   Esta opção de menu de recursos e a página aparecem apenas quando o recurso de visualizações materializadas está habilitado para a conta.

5. Selecione Guardar.

CLI do Azure

1. Defina as variáveis para o grupo de recursos e o nome da conta do Azure Cosmos DB para NoSQL existente.

   Azure CLI

   # Variable for resource group name
   $resourceGroupName="<resource-group-name>"
   
   # Variable for account name
   $accountName="<account-name>"
   
   # Variable for Azure subscription
   $subscriptionId="<subscription-id>"
   

2. Crie um novo arquivo JSON chamado builder.json usando o manifesto do construtor. Atualize o instanceCount e instanceSize conforme necessário.

   JSON

   {
     "properties": {
       "serviceType": "materializedViewsBuilder",
       "instanceCount": 1,
       "instanceSize": "Cosmos.D4s"
     }
   }
   

3. Obtenha o identificador da conta e armazene-o em uma variável de shell chamada $accountId.

   Azure CLI

   $accountId="/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"
   

4. Habilite o construtor de visualizações materializadas para a conta usando a API REST e az rest com um verbo HTTP PUT :

   Azure CLI

   az rest \
       --method PUT \
       --uri "https://management.azure.com$accountId/services/materializedViewsBuilder/?api-version=2022-11-15-preview" \
       --body @builder.json
   

5. Aguarde alguns minutos e, em seguida, verifique o status usando az rest novamente com o verbo HTTP GET . O status na saída agora deve ser Running.

   Azure CLI

   az rest \
       --method GET \
       --uri "https://management.azure.com$accountId/services/materializedViewsBuilder/?api-version=2022-11-15-preview"
   

Criar uma vista materializada

Depois que o recurso for habilitado e o construtor de exibições materializado for provisionado, você poderá criar exibições materializadas usando a API REST.

1. Use o portal do Azure, os SDKs do Azure, a CLI do Azure ou a API REST para criar um contêiner de origem que tenha /customerId como caminho da chave de partição. Nomeie este contêiner de mv-srcorigem .

   Nota

   O /customerId campo é usado apenas como um exemplo neste artigo. Para seus próprios contêineres, selecione uma chave de partição que funcione para sua solução.

2. Insira alguns itens no contêiner de origem. Para seguir os exemplos mostrados neste artigo, certifique-se de que os itens têm customerId e emailAddress campos. Um item de exemplo pode ter esta aparência:

   JSON

   {
     "id": "eaf0338e-2b61-4163-822f-7bef75bf51de",
     "customerId": "36c7cc3d-1709-45c6-819f-10e5586a6cb7",
     "emailAddress": "justine@contoso.com",
     "name": "Justine"
   }
   

   Nota

   Neste exemplo, você preenche o contêiner de origem com dados de exemplo antes de adicionar uma exibição. Você também pode criar uma exibição materializada a partir de um contêiner de origem vazio.

3. Agora, crie uma exibição materializada nomeada mv-target com um caminho de chave de partição que seja diferente do contêiner de origem. Para este exemplo, especifique /emailAddress como o caminho da chave de partição para o mv-target contêiner.

   1. Crie um manifesto de definição para uma exibição materializada e salve-o em um arquivo JSON chamado mv-definition.json:

      JSON

      {
        "location": "North Central US",
        "tags": {},
        "properties": {
          "resource": {
            "id": "mv-target",
            "partitionKey": {
              "paths": [
                "/emailAddress"
              ]
            },
            "materializedViewDefinition": {
              "sourceCollectionId": "mv-src",
              "definition": "SELECT c.customerId, c.emailAddress FROM c"
            }
          },
          "options": {
            "throughput": 400
          }
        }
      }        
      

   Importante

   No modelo, observe que o caminho da chave de partição está definido como /emailAddress. O sourceCollectionId define o contêiner de origem para o modo de exibição e o definition contém uma consulta para determinar o modelo de dados do modo de exibição. Saiba mais sobre como definir exibições materializadas e as restrições de consulta.

   O contêiner de origem da exibição materializada e a consulta de definição não podem ser alterados depois de criados.

4. Em seguida, faça uma chamada à API REST para criar a exibição materializada, conforme definido no arquivo mv-definition.json . Use a CLI do Azure para fazer a chamada da API REST.

   1. Crie uma variável para o nome da exibição materializada e o nome do banco de dados de origem:

      Azure CLI

      # This should match the resource ID you defined in your json file
      $materializedViewName = "mv-target"
      
      # Database name for the source and view containers
      $databaseName = "<Database that contains source container>"
      
      # Azure Cosmos DB account name
      $accountName = "<Azure Cosmos DB account name>"
      
      # Resource name for your Azure Cosmos DB account
      $resourceGroupName = "<Resource group for Azure Cosmos DB account>"
      
      # Subscription id for your Azure Cosmos DB account
      $subscriptionId = "<Subscription id>"
      

   2. Construa o ID do recurso usando essas variáveis.

      Azure CLI

      $accountId = "/subscriptions/$subscriptionId/resourceGroups/$resourceGroupName/providers/Microsoft.DocumentDB/databaseAccounts/$accountName"
      

   3. Faça uma chamada à API REST para criar a exibição materializada:

      Azure CLI

      az rest \
          --method PUT \
          --uri "https://management.azure.com$accountId/sqlDatabases/ \
                $databaseName/containers/$materializedViewName/?api-version=2022-11-15-preview" \
          --body @mv-definition.json \
          --headers content-type=application/json
      

   4. Verifique o status da criação do contêiner de exibição materializado usando a API REST:

      Azure CLI

      az rest \
          --method GET \
          --uri "https://management.azure.com$accountId/sqlDatabases/
                $databaseName/containers/$materializedViewName/?api-version=2022-11-15-preview" \
          --headers content-type=application/json \
          --query "{mvCreateStatus: properties.Status}"
      

5. Depois que a exibição materializada é criada, o construtor de exibição materializada sincroniza automaticamente as alterações com o contêiner de origem. Tente executar operações de criação, atualização e exclusão no contêiner de origem. Você verá as mesmas alterações propagadas para o contêiner de exibição materializado.

Consultar dados de vistas materializadas

Neste exemplo, temos um contêiner de origem particionado em customerId e um modo de exibição particionado em emailAddress. Sem a exibição, as consultas que incluem apenas o emailAddress seriam partições cruzadas, mas agora elas podem ser usadas contra a exibição em vez disso para aumentar a eficiência.

Consultar dados de exibições materializadas é semelhante a consultar dados de qualquer outro contêiner. Você pode usar o portal do Azure, SDKs do Azure ou API REST para consultar dados em exibições materializadas.

.NET

C#

Container container = client.GetDatabase("mv-db").GetContainer("mv-target");

FeedIterator<MyClass> myQuery = container.GetItemQueryIterator<MyClass>(new QueryDefinition("SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"));

Java

Java

CosmosAsyncDatabase container = client.getDatabase("mv-db");
CosmosAsyncContainer container = database.getContainer("mv-target");

CosmosPagedFlux<MyClass> pagedFluxResponse = container.queryItems(
        "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'", null, MyClass.class);

Node.js

JavaScript

const database = client.database("mv-db");
const container = database.container("mv-target");

const querySpec = {
    query: "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
 };
const { resources: items } = await container.items
    .query(querySpec)
    .fetchAll();

Python

Python

database = client.get_database_client("mv-db")
container = database.get_container_client("mv-target")

query = "SELECT * FROM c WHERE c.emailAddress = 'justine@contoso.com'"
container.query_items(
    query=query
)

Próximos passos

Modelagem e particionamento dedados Visão geral das visualizações materializadas