Importar do Azure Cosmos DB

Este artigo descreve como usar o módulo importar dados no Azure Machine Learning Studio (clássico) para importar dados do Azure Cosmos DB para uso em um experimento do Machine Learning.

Observação

Aplica-se a: Machine Learning Studio (clássico)

Esse conteúdo pertence apenas ao estúdio (clássico). Módulos de arrastar e soltar semelhantes foram adicionados ao designer de Azure Machine Learning. Saiba mais neste artigo comparando as duas versões.

O Azure Cosmos DB dá suporte ao armazenamento de banco de dados NoSQL usando um modelo de dado flexível. As vantagens de usar as APIs do SQL neste armazenamento de dados para o Machine Learning incluem desempenho rápido e previsível, dimensionamento automático, distribuição global e recursos de consulta avançada.

Junto com o banco de dados SQL do Azure, essa opção permite que você filtre dinamicamente os DataSets de entrada.

Saiba como funciona: saiba mais sobre Azure Cosmos DB

  • Para começar a usar o Machine Learning usando dados do Azure Cosmos DB, você deve ter acesso a uma conta existente do Azure Cosmos DB que contém uma coleção de documentos relacionados.

Observação

A interface do usuário no Azure Machine Learning Studio (clássico) ainda usa o nome DocumentDB em muitos lugares. Portanto, você pode continuar a ver referências ao DocumentDB, embora a API tenha sido incorporada em Azure Cosmos DB.

Como usar importar dados com Azure Cosmos DB

É altamente recomendável que você crie o perfil de seus dados antes de importar, para certificar-se de que o esquema está conforme o esperado. O processo de importação examina um número de linhas de cabeçalho para determinar o esquema, mas as linhas posteriores podem conter colunas extras ou dados que causam erros.

Importar dados usando o assistente

O módulo apresenta um novo assistente para ajudá-lo a escolher uma opção de armazenamento, selecionar entre assinaturas e contas existentes e configurar rapidamente todas as opções.

  1. Adicione o módulo importar dados ao seu experimento. Você pode encontrar o módulo em entrada e saída de dados.

  2. Clique em Iniciar assistente de importação de dados e siga os prompts.

  3. Quando a configuração estiver concluída, para realmente copiar os dados em seu experimento, clique com o botão direito do mouse no módulo e selecione executar selecionado.

Dica

Se você precisar editar uma conexão de dados existente, o assistente carregará todos os detalhes de configuração anteriores. Você não precisa iniciar novamente do zero.

Definir manualmente as propriedades no módulo importar dados

As etapas a seguir descrevem como configurar manualmente a origem da importação.

  1. Adicione o módulo importar dados ao seu experimento. Você pode encontrar esse módulo na categoria entrada e saída de dados .

  2. Para fonte de dados, selecione Azure DocumentDB.

    Talvez seja necessário fornecer informações de conexão para o banco de dados de documentos.

    Dica

    Procure o nome da opção em Machine Learning Studio (clássico) para alterar em uma data posterior. A funcionalidade de importação não foi afetada pela alteração de nome.

  3. Para URL de ponto de extremidade, no portal do Azure, clique em chaves e copie o conteúdo do campo URI na parte superior da página.

  4. Para ID do banco de dados, Cole o nome do banco de dados a ser usado.

    Para obter o nome do banco de dados no portal do Azure, clique em Gerenciador de documentos. Você pode exibir a lista de bancos de dados e coleções neste painel.

  5. Para a chave do DocumentDB, Cole uma chave de acesso para a conta.

    Para localizar as chaves, clique em chaves e, em seguida, copie o conteúdo dos campos chave primária ou chave secundária .

  6. Para ID da coleção, digite o nome da coleção, conforme mostrado no banco de dados CosmosDB especificado.

  7. Defina uma consulta SQL e uma condição de filtro nos dados, usando a consulta SQL e as opções de parâmetros de consulta SQL .

    Para consulta SQL, digite uma consulta que defina os dados a serem recuperados da coleção. Recomendamos que você use o Gerenciador de consultas para criar e testar suas consultas CosmosDB com antecedência.

    Para parâmetros de consulta SQL, forneça uma expressão no formato JSON que possa ser usada para filtrar dinamicamente os dados retornados. Normalmente, você fornece o valor real do valor do parâmetro ao executar o experimento como parte de um serviço Web.

    Se você usar um parâmetro, deverá definir o nome da variável de filtro como parte da cláusula WHERE especificada na caixa de texto consulta SQL .

    Se você não especificar uma expressão de filtro, por padrão, o valor será definido como " {} ", e todos os registros serão retornados.

    Consulte a seção notas técnicas para obter exemplos, problemas conhecidos e conselhos adicionais sobre consultas SQL no CosmosDB.

  8. Selecione a opção usar resultados em cache se você quiser reutilizar os resultados existentes.

    Se você desmarcar essa opção, os dados serão lidos da origem cada vez que o experimento for executado, independentemente de os dados serem ou não iguais.

    Azure Machine Learning não pode comparar os dados armazenados em cache com os dados em sua conta do CosmosDB. Portanto, não há como executar atualizações incrementais de Azure Machine Learning.

    Se desejar importar novamente somente quando os dados forem alterados, você deverá definir essa lógica em outro aplicativo, como Azure Data Factory. Para obter mais informações, consulte mover dados de e para Azure Cosmos DB usando Azure data Factory.

  9. Execute o experimento ou selecione apenas o módulo importar dados e clique em executar selecionado.

Resultados

Depois de executar o módulo ou experimento, você pode clicar com o botão direito do mouse na saída do módulo para visualizar os resultados em formato tabular.

Para capturar um instantâneo desses dados em seu espaço de trabalho do Azure Machine Learning como um DataSet, você pode clicar com o botão direito do mouse na saída do módulo e selecionar salvar como conjunto de dados. No entanto, isso captura apenas os dados disponíveis no momento da importação. Se for esperado que os dados sejam alterados com frequência, execute a importação de dados novamente conforme necessário.

Exemplos

Para obter uma explicação detalhada de como usar Azure Cosmos DB como uma fonte de dados para aprendizado de máquina, consulte a Galeria de ia do Azure.

Notas técnicas

Esta seção contém opções de configuração avançadas e respostas para perguntas frequentes.

Exemplos de consultas simples e parametrizadas

Suponha que você deseja usar apenas os dados em Volcanoes com elevações abaixo de 10000 pés.

Consulta simples

Cole a seguinte consulta na caixa de texto consulta SQL : Select * from volcanodb where volcanodb.Elevation < 10000

Nesse caso, o valor da expressão de filtro é definido como " {} ", e todos os registros são retornados.

Consulta parametrizada

Para obter apenas os dados de vulcão relacionados a um país específico, você pode especificar o valor do país como um parâmetro passado para a consulta em tempo de execução. Isso requer estas alterações:

  1. Na caixa de texto consulta SQL , defina uma variável a ser aplicada ao Country campo como parte da consulta SQL:

    Select * from volcanodb where volcanodb.Country = @param1

  2. Na caixa de texto parâmetros de consulta SQL , especifique o nome do parâmetro e seu valor no formato JSON, desta forma:

    {"@param1":"Turkey"}

Recursos

Se você não tiver um repositório de documentos existente, consulte estes artigos para começar.

Ajuda de migração de dados e sintaxe de consulta

Para obter exemplos de consultas em um armazenamento de dados JSON, baixe a folha de consulta de Azure Cosmos DB consultas.

Se você precisar carregar conteúdo em Azure Cosmos DB, recomendamos a ferramenta de migração de Azure Cosmos DB. Ele valida, carrega e indexa seus dados. A ferramenta dá suporte a várias fontes, incluindo MongoDB, Amazon DynamoDB, HBase, bancos de dados SQL Server e arquivos CSV.

Usando consultas sem esquema

Se os dados forem consistentes e previsíveis, você poderá usar uma sintaxe simples do SQL, como SELECT * FROM <document collection> . Isso é chamado de consulta sem esquema porque você não nomeou os atributos exatos a serem retornados. Tal consulta retornaria todos os campos e todas as linhas da coleção especificada.

No entanto, não especificar um esquema pode levar a resultados inesperados ou a um erro em tempo de execução se os documentos tiverem esquemas inconsistentes. Isso ocorre porque o módulo importar dados tenta inferir o esquema com base em um número predeterminado de linhas da seguinte maneira:

  1. Quando nenhum atributo for especificado, o módulo examinará a primeira linha no banco de dados CosmosDB.
  2. O módulo cria nomes de coluna com base em atributos e adivinha o que os tipos de dados de coluna devem ser baseados na linha de exemplo.
  3. Se as linhas posteriores contiverem qualquer atributo novo ou diferente, um erro em tempo de execução será gerado.

Portanto, é recomendável que você sempre especifique os atributos e valores a serem retornados do armazenamento de dados CosmosDB. Por exemplo, em vez de usar a SELECT * sintaxe, recomendamos que você nomeie todos os atributos recuperados pela consulta, desta forma:

SELECT MyTable.Gender, MyTable.Age, MyTable.Name FROM <document collection>

Parâmetros do módulo

A tabela a seguir inclui apenas os parâmetros para o módulo importar dados que são aplicáveis à opção Azure Cosmos DB.

Name Intervalo Tipo Necessária Padrão Descrição
Fonte de dados list HTTP exigido nenhum A fonte de dados pode ser HTTP, FTP, HTTPS anônimo ou FTPS, um arquivo no armazenamento de BLOBs do Azure, uma tabela do Azure, um banco de dados SQL do Azure, uma tabela Hive, um ponto de extremidade OData ou o Azure Cosmos dB.
URL do Ponto de Extremidade any string exigido nenhum Forneça o URI para o servidor de Azure Cosmos DB
ID do banco de dados any string exigido nenhum Forneça o nome do banco de dados Azure Cosmos DB
Chave do DocumentDB any SecureString exigido nenhum Forneça uma chave de API válida para a conta de Azure Cosmos DB
ID da coleção any string exigido nenhum Forneça o nome de uma coleção no banco de dados de Azure Cosmos DB
Consulta SQL any string exigido nenhum Uma consulta SQL especificando registros para retornar do armazenamento de dados Azure Cosmos DB

Saídas

Nome Tipo Descrição
Conjunto de dados de resultados Tabela de Dados Conjunto de dados com dados baixados

Exceções

Exceção Descrição
Erro 0003 Ocorrerá uma exceção se uma ou mais das entradas forem nulas ou estiverem vazias.
Erro 0029 Ocorrerá uma exceção quando um URI inválido for passado.
Erro 0002 Ocorrerá uma exceção se um ou mais parâmetros não puderem ser analisados ou convertidos do tipo especificado para o tipo exigido pelo método de destino.
Erro 0048 Uma exceção ocorre quando não for possível abrir um arquivo.
Erro 0049 Uma exceção ocorre quando não for possível analisar um arquivo.

Para obter uma lista de erros específicos para módulos do Studio (clássicos), consulte Machine Learning códigos de erro.

Para obter uma lista de exceções de API, consulte Machine Learning códigos de erro da API REST.

Consulte também

Importar dados
Exportar dados
Importar da URL da Web via HTTP
Importar da consulta do hive
Importar do banco de dados SQL do Azure
Importar do armazenamento de BLOBs do Azure
Importar de provedores de feed de dados
Importar de um Banco de dados do SQL Server local