Importar e query dados usando o suplemento do Databricks para Excel

O Databricks Excel Add-in conecta o seu workspace do Databricks ao Microsoft Excel, trazendo dados governados do Lakehouse diretamente para as suas planilhas.

Esta página descreve como usar o suplemento do Databricks para Excel para importar e analisar dados do Databricks no Excel. Você pode navegar e importar tabelas do Databricks por meio de uma interface intuitiva em que nenhum conhecimento de SQL é necessário. Embora o suplemento ofereça a flexibilidade de executar queries SQL personalizadas, ele é opcional.

Pré-requisitos

• Antes de usar o suplemento do Excel, verifique se você o configurou.
• Você tem acesso ao Databricks SQL e pelo menos a permissão CAN USE em um SQL warehouse.

Selecionar um SQL warehouse

Escolha qual SQL warehouse usar:

1. No canto superior direito do painel do suplemento do Databricks no Excel, clique no menu suspenso.
2. Selecione o SQL warehouse que você deseja usar.

Importar dados do Databricks

Importe dados do Databricks no Excel selecionando uma tabela, escrevendo uma query SQL ou importando uma tabela dinâmica.

nota

Você pode importar views de métricas do Unity Catalog usando tabelas dinâmicas, query SQL e funções personalizadas.

Criar tabelas dinâmicas

Para criar uma tabela dinâmica a partir de tabelas e views do Unity Catalog no Excel:

1. No painel do Databricks Excel Add-in, na New import tab, selecione Select data como o Import method .

2. Em Catalog , selecione a tabela da qual deseja criar uma tabela dinâmica e clique em Select .

3. Marque a caixa de seleção Pivot Data .

4. (Opcional) Selecione Live query para fazer a execução da query e atualizar automaticamente uma nova planilha conforme você cria a tabela dinâmica. Para obter mais informações, consulte Live query.

5. Configure Row , Column e Value arrastando cada campo para a área correta.

6. (Opcional) Adicione um Filter . Para obter mais informações sobre filtros, consulte Filtrar dados importados.

7. (Opcional) Defina um limite de linha para a sua importação.

8. Importe seus resultados. Escolha uma das seguintes opções:

   • Clique em Save and import para salvar a query para reutilização no Excel workbook e importar os resultados.
   • Clique na seta para baixo e clique em Importar resultados para importar os resultados sem salvar a query. Use esta opção quando quiser continuar editando uma importação.

nota

As tabelas dinâmicas só podem ser importadas para uma nova planilha.

Ao trabalhar com métricas do Unity Catalog em tabelas dinâmicas, você poderá ver Sum(measure) exibido nos resultados. Esse é o comportamento esperado e nenhuma agregação adicional ocorre. O Excel exige que os valores tenham uma função de agregação, mas como os dados contêm valores exclusivos, nenhuma agregação ocorre.

Query ativa

A live query executa sua query de tabela dinâmica e atualiza a planilha automaticamente conforme você edita a tabela dinâmica, para que você veja os resultados à medida que atualiza os campos, em vez de após clicar em Import . A live query executa a query novamente após você alterar pelo menos uma linha ou coluna e um valor. Para retornar ao fluxo padrão, desative o recurso.

Quando a Live query está ativada, a tabela dinâmica é sempre criada e atualizada em uma nova planilha. Além disso, o construtor de tabela dinâmica exibe um botão Salvar importação em vez de Importar .

Se o Excel for fechado enquanto você estiver editando uma tabela dinâmica ativa, a tab Imports exibirá uma opção de recuperação para que você possa restaurar a última configuração salva para essa importação.

Selecionar tabelas

Os dados são importados como um objeto de tabela do Excel. Você pode mover a tabela ou renomear a planilha, e o suplemento do Excel faz o refresh dos dados no novo local.

Para importar dados de uma tabela do Databricks, faça o seguinte:

1. No painel do Databricks Excel Add-in, na New import tab, selecione Select data como o Import method .
2. Escolha uma tabela para importar do Catalog Explorer. Você pode filtrar o catálogo por proprietário, status de certificação e outras propriedades usando o filtro .
3. Clique em Selecionar .
4. Em Colunas , clique na seta para baixo e desmarque as colunas que você não deseja importar, ou deixe todas as colunas selecionadas para importar a tabela inteira.
5. (Opcional) Adicione um Filter . Para obter mais informações sobre filtros, consulte Filtrar dados importados.
6. (Opcional) Para ver uma amostra da importação, clique em Preview .
7. (Opcional) Defina um limite de linhas para restringir o número de linhas importadas.
8. (Opcional) Para identificar seus dados importados, insira um Nome da importação .
9. Em Destino de saída , escolha importar os dados para uma nova planilha ou para a planilha atual. Se você importar para a planilha atual, os dados começarão na referência de célula inserida (por default A1).
10. Importe seus resultados. Escolha uma das seguintes opções:
    • Clique em Save and import para salvar a query para reutilização no Excel workbook e importar os resultados.
    • Clique na seta para baixo e clique em Importar resultados para importar os resultados sem salvar a query. Use esta opção quando quiser continuar editando uma importação.

Escrever queries SQL

O método de importação Escrever SQL oferece suporte a funções SQL e procedimentos armazenados.

Para fazer a execução de queries SQL personalizadas no seu workspace do Databricks, faça o seguinte:

1. No painel do suplemento do Excel para Databricks, na tab New import , selecione Write SQL como o Import method .

2. Insira um nome para a sua query para identificá-la mais tarde.

3. Escreva uma nova query ou use uma query existente do seu Workspace do Databricks.

   • Escreva sua query SQL no editor. Você pode consultar qualquer tabela no Unity Catalog que tenha permissão para acessar.

     • Clique em Catalog Explorer para view seus esquemas e tabelas.

   • Para usar uma query do seu workspace do Databricks ou uma query existente no Excel, clique em na pasta. Se você usar uma query existente do seu workspace do Databricks, as edições feitas no Excel não serão refletidas no Databricks.

nota

As queries devem ser explicitamente salvas no Databricks usando o botão Salvar no canto superior direito do editor de queries antes de aparecerem no Excel.

4. (Opcional) Para adicionar parâmetros de query, clique em +Adicionar ao lado de Parâmetros . Clique no parâmetro e insira o Nome do parâmetro e o Valor do parâmetro .

   • Para o valor do parâmetro, você pode inserir um valor específico ou clicar no botão de caixa e seta para especificar uma referência de célula. Selecione uma célula ou um intervalo de células e clique na seta para preencher automaticamente o valor do parâmetro.

5. Em Destino de saída , escolha importar os dados para uma nova planilha ou para a planilha atual. Se você importar para a planilha atual, os dados começarão na referência de célula inserida (por default A1).

6. Para visualizar os resultados da sua query, clique em execução .

7. Importe seus resultados. Escolha uma das seguintes opções:

   • Clique em Save and import para salvar a query para reutilização no Excel workbook e importar os resultados.
   • Clique na seta para baixo e clique em Importar resultados para importar os resultados sem salvar a query. Use esta opção quando quiser continuar editando uma importação.

Você também pode usar funções personalizadas para adicionar parâmetros de query. Consulte Escrever SQL.

Filtrar dados importados

Ao importar dados selecionando uma tabela ou criando uma tabela dinâmica, é possível aplicar filtros para restringir os resultados.

Os filtros de strings não diferenciam maiúsculas de minúsculas e são em cascata. Quando você aplica mais de um filtro, os valores disponíveis para cada filtro dependem das seleções nos filtros anteriores. Por exemplo, se você filtrar por país e, em seguida, adicionar um filtro por cidade, o filtro de cidade oferecerá apenas cidades do país selecionado.

Para definir filtros, clique em + ao lado de Filters , selecione a coluna à qual deseja aplicar um filtro e insira sua condição de filtro. Para filtros que exigem um valor, você pode executar uma das seguintes ações:

• Insira o valor.

• Para gerar uma lista de até 5.000 valores de filtro distintos, você pode usar:

  1. Clique em Values e, em seguida, em Get filter values .
  2. Clique na seta para baixo e selecione um ou mais valores na lista.

• Para usar uma referência de célula:

  1. Clique em Cells .
  2. Selecione uma célula ou intervalo de células.
  3. Clique no cursor .

A tabela a seguir descreve cada filtro disponível e sua entrada esperada.

Filtrar	Entrada esperada	Descrição
IS NULL	Nenhuma	Localiza linhas nas quais o valor da coluna é nulo.
IS NOT NULL	Nenhuma	Localiza linhas nas quais o valor da coluna não é nulo.
EQUALS	Um número ou uma string de texto	Localiza linhas em que o valor da coluna corresponde exatamente ao valor especificado.
NOT EQUALS	Um número ou uma string de texto	Localiza linhas em que o valor da coluna não corresponde ao valor especificado.
STARTS WITH	Uma strings de texto	Localiza linhas em que o valor da coluna começa com o texto especificado.
ENDS WITH	Uma strings de texto	Localiza linhas em que o valor da coluna termina com o texto especificado.
CONTAINS	Uma strings de texto	Localiza linhas em que o valor da coluna contém o texto especificado em qualquer lugar da strings.

Filtrar	Entrada esperada	Descrição
IS NULL	Nenhuma	Localiza linhas nas quais o valor da coluna é nulo.
IS NOT NULL	Nenhuma	Localiza linhas nas quais o valor da coluna não é nulo.
EQUALS	Um número ou uma string de texto	Localiza linhas em que o valor da coluna corresponde exatamente ao valor especificado.
NOT EQUALS	Um número ou uma string de texto	Localiza linhas em que o valor da coluna não corresponde ao valor especificado.
STARTS WITH	Uma strings de texto	Localiza linhas em que o valor da coluna começa com o texto especificado.
ENDS WITH	Uma strings de texto	Localiza linhas em que o valor da coluna termina com o texto especificado.
CONTAINS	Uma strings de texto	Localiza linhas em que o valor da coluna contém o texto especificado em qualquer lugar da strings.

Campos calculados

Um campo calculado é uma coluna derivada de dados existentes, como profit computado a partir de revenue e cost. O suplemento do Excel não oferece suporte à criação de campos calculados usando o método de importação Select data . Para adicionar um campo calculado, use um dos seguintes métodos:

• Escrever SQL : use o método de importação Escrever SQL para compute colunas calculadas com qualquer expressão SQL. Consulte Escrever queries SQL.
• Genie One : Peça ao Genie One para retornar seus dados com as colunas calculadas necessárias e, em seguida, importe os resultados. Consulte Usar o Genie One no Microsoft Excel.

O Databricks recomenda o uso do Genie One para campos calculados.

Use funções personalizadas do Databricks no Excel

O suplemento do Excel fornece funções personalizadas que você pode usar em fórmulas do Excel para importar dados do Databricks.

Selecionar uma tabela

A função DATABRICKS.Table importa dados de uma tabela do Unity Catalog.

Sintaxe:

Text

=DATABRICKS.Table(catalog_name.schema_name.table_name, [column1, ...], [limit])

Parâmetros:

• catalog_name.schema_name.table_name (obrigatório): o nome da tabela totalmente qualificado.
• columns (opcional): uma matriz de nomes de colunas a serem importadas. Omitir este parâmetro para importar todas as colunas.
• limit (opcional): o número máximo de linhas a serem importadas. Omita esse parâmetro para importar todas as linhas, até o limite de 10 MB.

Exemplo:

Text

=DATABRICKS.Table("main.default.customers", {"customer_id", "customer_name"}, 100)

Esta fórmula importa as colunas customer_id e customer_name da tabela main.default.customers, limitada a 100 linhas.

Escrever SQL

A função DATABRICKS.SQL executa uma query SQL que usa parâmetros de query e retorna os resultados.

Sintaxe:

Especifique os parâmetros usando valores.

Text

=DATABRICKS.SQL("query_text", {parameter1_name, parameter1_value; ...})

Especifique os parâmetros usando um intervalo de células. Defina os parâmetros de nome e valor em células que estejam na mesma linha.

Text

=DATABRICKS.SQL("query_text", {param_name_cell: param_value_cell; ...})

Parâmetros:

• query_text (obrigatório): a query SQL para execução.
• parameters (obrigatório): um mapeamento de valores de parâmetro a serem substituídos na query.

Exemplo:

Text

=DATABRICKS.SQL("SELECT * FROM samples.bakehouse.sales_suppliers WHERE longitude > :long_param AND latitude > :lat_param LIMIT 10", {"long_param",20; "lat_param",10})

=DATABRICKS.SQL("SELECT * FROM samples.bakehouse.sales_suppliers WHERE city = :city", M4:N4)

Esta fórmula executa uma query que filtra dados de ventas por longitude e latitude, usando os valores de parâmetro fornecidos.

Gerenciar queries

Gerencie suas importações existentes na página Imports.

Editar uma importação existente

Para editar uma importação existente:

1. No painel de suplemento do Databricks no Excel, clique na tab Imports .
2. Encontre a importação que deseja editar.
3. Clique no menu de três pontos ao lado da importação.
4. Clique em Editar para editar sua importação.

Fazer refresh dos dados

O suplemento do Excel não faz refresh dos dados automaticamente. A forma como você faz o refresh dos dados depende de como você os importou. Os dados importados usando um método de importação (selecionar uma tabela, gravar uma query SQL ou criar uma tabela dinâmica) fazem refresh na tab Imports . Os dados importados usando uma função personalizada devem ser recalculados.

Atualize as importações com os valores mais recentes do Databricks. O suplemento executa a query ou seleção de tabela original novamente e atualiza sua planilha com dados novos:

• Para fazer o refresh de uma única importação:

  1. No painel de suplemento do Databricks no Excel, clique na tab Imports .
  2. Clique em refresh ao lado da importação que você deseja atualizar.

• Para fazer o refresh de todas as importações:

  1. Clique em Refresh All no painel do Databricks Add-in.

importante

Ao fazer o refresh dos dados, o suplemento do Excel limpa todos os dados existentes na tabela especificada e recarrega os dados mais recentes do Databricks. Quaisquer colunas personalizadas adicionadas por você à tabela serão excluídas durante o processo de refresh.

Dados importados de funções personalizadas, como DATABRICKS.Table e DATABRICKS.SQL, não são refresh quando você reabre uma planilha. Para refresh os dados importados de funções personalizadas, faça login no Databricks Add-in e, em seguida, recalcule a planilha ou altere um valor referenciado pela função personalizada.

Implicações do compartilhamento

Quando você compartilha uma pasta de trabalho do Excel que contém dados do Databricks, considere as seguintes implicações de acesso a dados e segurança:

Visibilidade dos dados importados

Quando um destinatário dá refresh em uma importação, o Suplemento usa as permissões do Unity Catalog do destinatário. Se eles não tiverem acesso aos dados subjacentes, a refresh falhará.

Para pastas de trabalho em que a privacidade de dados é uma preocupação, você pode usar a seguinte alternativa:

1. Crie uma pasta de trabalho com todas as fórmulas e importações necessárias.
2. Exclua os dados importados da planilha.
3. Compartilhe a pasta de trabalho com o destinatário.
4. Peça ao destinatário que faça refresh dos dados.

O destinatário vê apenas os dados aos quais tem acesso com base nas permissões do Unity Catalog.

Acesso a Workspace e ativos de dados

• Os usuários sem acesso aos objetos do Unity Catalog referenciados na pasta de trabalho não podem dar refresh nos dados. Para dar refresh nos dados, os usuários devem ter permissões de leitura nas tabelas e views subjacentes no Unity Catalog.
• Os usuários devem ter acesso à tabela subjacente no Databricks para editar importações existentes.

Visibilidade de query

Usuários com acesso de edição à pasta de trabalho podem view as queries usadas para gerar os dados por meio do suplemento do Databricks, mesmo que não tenham acesso aos dados subjacentes no Unity Catalog.

Alternativa para salvar como um padrão

O suplemento do Excel para Databricks não oferece suporte ao salvamento de uma pasta de trabalho como padrão, mas você pode compartilhar uma pasta de trabalho para que outros usuários possam ver as queries importadas. Consulte Implicações do compartilhamento para obter considerações sobre acesso a dados e segurança.

Como uma alternativa para o compartilhamento de uma workbook como um padrão, faça um dos seguintes procedimentos:

• Compartilhe o arquivo local com outro usuário. O destinatário pode renomear o arquivo e ver as queries salvas.
• No SharePoint, compartilhe a pasta de trabalho com outro usuário. Quando outro usuário fizer download do arquivo, as importações salvas serão preservadas.

Limitações

• Custom functions : para funções personalizadas, os resultados das queries são limitados a 25 MiB devido a limitações da API de execução de SQL.
• Carregamento de dados : o carregamento de dados poderá falhar se alguma célula na pasta de trabalho estiver no modo de edição.
• Limite de linhas do Excel Desktop : o Excel Desktop aceita no máximo 1.048.576 linhas por planilha.
• Limite de tamanho de arquivo do Excel for the web : O Excel for the web oferece suporte a um tamanho máximo de arquivo de pasta de trabalho de aproximadamente 25 MB para visualização e edição.
• Live query desempenho : com o recurso Live query ativado, cada edição de tabela dinâmica realiza a execução de uma nova query no seu SQL Warehouse. Os resultados não são armazenados em cache localmente; portanto, edições frequentes em tabelas dinâmicas grandes podem adicionar latência e custo ao warehouse.