Configurar e usar o Link do Azure Synapse para Azure Cosmos DB

  • Artigo

APLICA-SE AO: NoSQL MongoDB Gremlin

O Link do Azure Synapse para Azure Cosmos DB é uma funcionalidade de HTAP (processamento transacional híbrido e analítico) nativa de nuvem que permite executar análises quase em tempo real sobre dados operacionais. O Link do Synapse cria uma integração perfeita entre o Azure Cosmos DB e o Azure Synapse Analytics.

O Link do Azure Synapse está disponível para a API de SQL do Azure Cosmos DB ou para a API do Azure cosmos DB para contas do Mongo DB. E está em versão prévia para a API do Gremlin, com ativação por meio de comandos da CLI. Use as etapas a seguir para executar consultas analíticas com o Link do Azure Synapse para Azure Cosmos DB:

Confira também o módulo de treinamento sobre como configurar o Link do Azure Synapse para o Azure Cosmos DB.

A primeira etapa para usar Link do Synapse é habilitá-lo para a conta de banco de dados do Azure Cosmos DB.

Observação

Para usar chaves gerenciadas pelo cliente com o Link do Azure Synapse, configure a identidade gerenciada da conta na política de acesso do Azure Key Vault antes de habilitar o Link do Synapse na conta. Para saber mais, confira o artigo Configurar chaves gerenciadas pelo cliente com identidades gerenciadas de contas do Azure Cosmos DB.

Observação

Para usar o esquema de fidelidade total para contas da API para NoSQL, não é possível usar o portal do Azure para habilitar o Link do Synapse. Esta opção não pode ser alterada depois que o Link do Synapse está habilitado na conta, e você deve usar a CLI do Azure ou o PowerShell para defini-lo. Para saber mais, consulte a documentação de representação de esquema de armazenamento analítico.

Observação

Você precisa da função Colaborador para habilitar o Link do Synapse no nível da conta. E você precisa de pelo menos da função Operador para habilitar o Link do Synapse em seus contêineres ou coleções.

Portal do Azure

  1. Entre no portal do Azure.

  2. Crie uma nova conta do Azure ou selecione uma conta existente do Azure Cosmos DB.

  3. Navegue até sua conta do Azure Cosmos DB e abra o Link do Azure Synapse em Integrações, no painel esquerdo.

  4. Selecione Habilitar. Esse processo pode levar de um a cinco minutos para ser concluído.

    Screenshot showing how to enable Synapse Link feature.

  5. Sua conta agora está habilitada para usar o Link do Synapse. Em seguida, consulte como criar contêineres habilitados para repositório analítico para iniciar automaticamente a replicação dos dados operacionais do repositório transacional no repositório analítico.

Observação

A ativação do Link do Synapse não ativará o repositório analítico automaticamente. Depois de habilitar o Link do Synapse na conta do Cosmos DB, habilite o armazenamento analítico em contêineres para começar a usar o Link do Synapse.

Observação

Você também pode habilitar o Link do Synapse para sua conta usando o Power BI e o painel do Link do Synapse, na seção Integrações do menu de navegação esquerdo.

Ferramentas de linha de comando

Habilite o Link do Synapse em sua conta da API do Azure Cosmos DB para NoSQL ou MongoDB usando a CLI do Azure ou o PowerShell.

CLI do Azure

Use --enable-analytical-storage true para as operações create ou update. Você também precisa escolher o tipo do esquema de representação. Para contas da API para NoSQL, você pode usar --analytical-storage-schema-type com os valores FullFidelity ou WellDefined. Para contas da API para MongoDB, sempre use --analytical-storage-schema-type FullFidelity.

A API do Link do Synapse para Gremlin está em versão prévia. Você pode habilitar o Link do Synapse em grafos novos ou existentes usando a CLI do Azure. Use o comando da CLI abaixo para habilitar o Link do Synapse para sua conta da API do Gremlin:

az cosmosdb create --capabilities EnableGremlin --name MyCosmosDBGremlinDatabaseAccount --resource-group MyResourceGroup --enable-analytical-storage true

Para contas de API do Gremlin existentes, substitua create por update.

PowerShell

Use EnableAnalyticalStorage true para ambas operações create ou update. Você também precisa escolher o tipo do esquema de representação. Para contas da API para NoSQL, você pode usar --analytical-storage-schema-type com os valores FullFidelity ou WellDefined. Para contas da API para MongoDB, sempre use -AnalyticalStorageSchemaType FullFidelity.

Modelo do Azure Resource Manager

Esse modelo do Azure Resource Manager cria uma conta do Azure Cosmos DB habilitada para o Link do Synapse para a API do SQL. Este modelo cria uma conta de API do Core (SQL) em uma região com um contêiner configurado com o TTL analítico habilitado e uma opção de usar taxa de transferência de dimensionamento manual ou automático. Para implantar esse modelo, clique em Implantar no Azure na página do arquivo Leia-me.

Habilitar o Link do Azure Synapse para seus contêineres

A segunda etapa é habilitar Link do Synapse para seus contêineres ou coleções. Isso é feito definindo a propriedade analytical TTL como -1 para retenção infinita, ou para um inteiro positivo, que é o número de segundos que você deseja manter no repositório analítico. Essa configuração pode ser alterada posteriormente. Para obter mais informações, consulte o artigo sobre valores aceitos no TTL analítico.

Observe os seguintes detalhes ao habilitar o Link do Azure Synapse em seus contêineres existentes da API de SQL:

  • O mesmo isolamento de desempenho do processo de sincronização automática do armazenamento analítico se aplica à sincronização inicial e não há nenhum impacto sobre o desempenho da sua carga de trabalho OLTP.
  • A sincronização inicial de um contêiner com o tempo total do armazenamento analítico varia de acordo com o volume de dados e da complexidade dos documentos. Esse processo pode levar desde alguns segundos até vários dias. Use o portal do Azure para monitorar o progresso da migração.
  • A produtividade do contêiner ou da conta de banco de dados também influencia o tempo total de sincronização inicial. Embora as RUs não sejam usadas nessa migração, o total de RUs disponíveis influencia o desempenho do processo. Você pode aumentar temporariamente as RUs disponíveis no ambiente para acelerar o processo.
  • Você não poderá consultar o armazenamento analítico de um contêiner existente enquanto o Link do Synapse estiver habilitado nesse contêiner. Sua carga de trabalho OLTP não será impactada e você poderá continuar lendo dados normalmente. Os dados ingeridos após o início da sincronização inicial serão mesclados no armazenamento analítico pelo processo de sincronização automática do armazenamento analítico regular.

Observação

Agora você pode habilitar o Link do Synapse em suas coleções de API do MongoDB existentes usando a CLI do Azure ou o PowerShell.

Portal do Azure

Novo contêiner

  1. Entre no portal do Azure ou no Azure Cosmos DB Explorer.

  2. Vá até sua conta do Azure Cosmos DB e abra a guia Data Explorer.

  3. Selecione Novo Contêiner e insira um nome para o banco de dados, o contêiner, a chave de partição e os detalhes da taxa de transferência. Ative a opção Repositório analítico. Depois de habilitar o repositório analítico, ele cria um contêiner com analytical TTL propriedade definida como o valor padrão de -1 (retenção infinita). Esse armazenamento analítico que retém todas as versões históricas de registros e pode ser alterado posteriormente.

    Turn on analytical store for Azure Cosmos DB container

  4. Se você não tiver habilitado o Link do Synapse anteriormente nessa conta, ele solicitará que você faça isso porque é um pré-requisito para criar um contêiner habilitado para repositório analítico. Se solicitado, selecione Habilitar Link do Synapse. Esse processo pode levar de um a cinco minutos para ser concluído.

  5. Selecione OKpara criar um armazenamento analítico habilitado para o Azure Cosmos DB.

  6. Depois que o contêiner for criado, verifique se o repositório analítico foi habilitado clicando em Configurações, logo abaixo de Documentos no Data Explorer e verifique se a opção Vida útil do Repositório Analítico está ativada.

Contêiner existente

  1. Entre no portal do Azure ou no Azure Cosmos DB Explorer.

  2. Vá até sua conta do Azure Cosmos DB e abra a guia Link do Azure Synapse.

  3. Na seção Habilitar Link do Azure Synapse para seus contêineres, selecione o contêiner.

    Screenshot showing how to turn on analytical store for an Azure Cosmos DB existing container.

  4. Depois que o contêiner for habilitado, verifique se o repositório analítico foi habilitado clicando em Configurações, logo abaixo de Documentos no Data Explorer, e verifique se a opção Vida útil do Repositório Analítico está ativada.

Observação

Você também pode habilitar o Link do Synapse para sua conta usando o Power BI e o painel do Link do Synapse, na seção Integrações do menu de navegação esquerdo.

Ferramentas de linha de comando

CLI do Azure

As opções a seguir habilitam o Link do Synapse em um contêiner usando a CLI do Azure definindo a propriedade --analytical-storage-ttl.

A API do Link do Synapse para Gremlin está em versão prévia. Você pode habilitar o Link do Synapse em grafos novos ou existentes usando a CLI do Azure. Use o comando da CLI abaixo para habilitar o Link do Synapse para seus grafos da API do Gremlin:

az cosmosdb gremlin graph create --g MyResourceGroup --a MyCosmosDBGremlinDatabaseAccount --d MyGremlinDB --n MyGraph --analytical-storage-ttl –1

Para grafos existentes, substitua create por update.

PowerShell

As opções a seguir habilitam o Link do Synapse em um contêiner usando a CLI do Azure definindo a propriedade -AnalyticalStorageTtl.

SDKs do Azure Cosmos DB – somente API do SQL

SDK .NET

O código .NET a seguir cria um contêiner habilitado para Link do Synapse definindo a propriedade AnalyticalStoreTimeToLiveInSeconds. Para atualizar um contêiner existente, use o método Container.ReplaceContainerAsync.

// Create a container with a partition key, and analytical TTL configured to -1 (infinite retention)
ContainerProperties properties = new ContainerProperties()
{
    Id = "myContainerId",
    PartitionKeyPath = "/id",
    AnalyticalStoreTimeToLiveInSeconds = -1,
};
CosmosClient cosmosClient = new CosmosClient("myConnectionString");
await cosmosClient.GetDatabase("myDatabase").CreateContainerAsync(properties);

SDK do Java v4

O código Java a seguir cria um contêiner habilitado para Link do Synapse definindo a propriedade setAnalyticalStoreTimeToLiveInSeconds. Para atualizar um contêiner existente, use a classe container.replace.

// Create a container with a partition key and  analytical TTL configured to  -1 (infinite retention) 
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");

containerProperties.setAnalyticalStoreTimeToLiveInSeconds(-1);

container = database.createContainerIfNotExists(containerProperties, 400).block().getContainer();

Python V4 SDK

O código Python a seguir cria um contêiner habilitado para Link do Synapse ao definir a propriedade analytical_storage_ttl. Para atualizar um contêiner existente, use o método replace_container.

# Client
client = cosmos_client.CosmosClient(HOST,  KEY )

# Database client
try:
    db = client.create_database(DATABASE)

except exceptions.CosmosResourceExistsError:
    db = client.get_database_client(DATABASE)

# Creating the container with analytical store enabled
try:
    container = db.create_container(
        id=CONTAINER,
        partition_key=PartitionKey(path='/id', kind='Hash'),analytical_storage_ttl=-1
    )
    properties = container.read()
    print('Container with id \'{0}\' created'.format(container.id))
    print('Partition Key - \'{0}\''.format(properties['partitionKey']))

except exceptions.CosmosResourceExistsError:
    print('A container with already exists')

Conectar-se a um espaço de trabalho do Synapse

Use as instruções em Conectar-se ao Link do Azure Synapse sobre como acessar um banco de dados Azure Cosmos DB do Azure Synapse Analytics Studio com o Link do Azure Synapse.

Consultar um repositório analítico usando o Azure Synapse Analytics

Saiba como consultar um repositório analítico com o Apache Spark para Azure Synapse Analytics

Use as instruções no artigo Consultar o repositório analítico do Azure Cosmos DB usando o Spark 3 sobre como consultar com o Synapse Spark 3. Esse artigo fornece alguns exemplos sobre como você pode interagir com o armazenamento analítico de gestos do Synapse. Esses gestos ficam visíveis quando você clica com o botão direito do mouse em um contêiner. Com gestos, você pode gerar código rapidamente e ajustá-lo às suas necessidades. Eles também são perfeitos para descobrir dados com um único clique.

Para a integração do Spark 2, use a instrução no artigo Consultar o repositório analítico do Azure Cosmos DB usando o Spark 2.

Veja o repositório analítico usando o pool de SQL sem servidor no Azure Synapse Analytics

O pool de SQL sem servidor permite consultar e analisar dados em seus contêineres do Azure Cosmos DB que estão habilitados com o Link do Azure Synapse. Você pode analisar dados quase em tempo real sem afetar o desempenho das cargas de trabalho de transações. Ele oferece uma sintaxe T-SQL familiar para consultar os dados do repositório analítico e conectividade integrada a uma grande variedade de ferramentas de consulta de BI e ad hoc por meio da interface T-SQL. Para saber mais, veja o artigo Consultar repositório analítico usando o pool de SQL sem servidor.

Usar o pool de SQL sem servidor para analisar e visualizar dados no Power BI

Use a experiência integrada de BI no portal do Azure Cosmos DB para criar dashboards de BI usando o Link do Synapse com apenas alguns cliques. Para saber mais, consulte como criar painéis de BI usando o Link do Synapse. Essa experiência integrada criará exibições simples de T-SQL em pools de SQL sem servidor no Synapse para os contêineres do Azure Cosmos DB. Você pode criar painéis de BI nessas exibições, que consultarão os contêineres do Azure Cosmos DB em tempo real, usando a Consulta direta, refletindo as alterações mais recentes em seus dados. Não há nenhum impacto de desempenho ou de custo nas suas cargas de trabalho transacionais e nenhuma complexidade no gerenciamento de pipelines de ETL.

Caso deseje usar exibições avançadas do T-SQL com junções nos seus contêineres ou criar dashboards do Power BI no Modo de importação, confira Usar o pool de SQL sem servidor para analisar dados do Azure Cosmos DB com o Link do Synapse.

Aprimorar o desempenho com as melhores práticas

Particionamento personalizado

O particionamento personalizado permite que você particione dados de armazenamento analítico em campos que são comumente usados como filtros em consultas analíticas, resultando em um desempenho de consulta aprimorado. Para saber mais, confira os artigos Introdução ao particionamento personalizado e Como configurar o particionamento personalizado.

Use estas melhores práticas obrigatórias para suas consultas SQL sem servidor.

Você pode encontrar exemplos para começar a usar o Azure Synapse Link no GitHub. Eles demostram soluções ponta a ponta com cenários de varejo e IoT. Encontre também os exemplos correspondentes ao Azure Cosmos DB for MongoDB no mesmo repositório na pasta MongoDB.

Próximas etapas

Para saber mais, consulte a seguinte documentação: