Integrations5 min read

Consultas SQL com DuckDB

Consulte dados de planilhas e bancos de dados externos usando SQL

Visão Geral

O ModelMonkey inclui um mecanismo SQL integrado desenvolvido com DuckDB, permitindo que você execute consultas SQL diretamente nos dados das suas planilhas. Você também pode consultar bancos de dados externos (PostgreSQL, BigQuery) e até combinar dados de múltiplas fontes.

Isso é útil quando você precisa de controle preciso sobre transformações de dados, deseja realizar agregações complexas ou precisa combinar dados de fontes diferentes de maneiras que a linguagem natural pode não expressar com clareza.

Tip

Você não precisa escrever SQL por conta própria. Basta descrever o que deseja em linguagem natural, e o ModelMonkey gerará e executará a consulta SQL adequada para você.

Quando as Consultas SQL São Utilizadas

O ModelMonkey utiliza automaticamente consultas SQL quando sua solicitação envolve:

Agregações Complexas
Agrupamento de dados, cálculo de somas, médias, contagens ou outras operações estatísticas em muitas linhas.

Filtragem e Ordenação
Localização de registros específicos com base em múltiplas condições ou ordenação de grandes conjuntos de dados por diversos critérios.

Combinação de Dados
Integração dos dados da sua planilha com bancos de dados externos ou mesclagem de múltiplas planilhas.

Transformações de Dados
Reformatação, cálculo de novas colunas ou reestruturação de dados de maneiras que exigem processamento linha a linha.

Você também pode solicitar explicitamente ao ModelMonkey que "use SQL" ou "execute uma consulta SQL" caso prefira a precisão do SQL para uma operação específica.

Consultando Dados de Planilhas

Os dados da sua planilha são acessíveis por meio da função sheet_range(). Essa função recebe uma referência em notação A1 e retorna os dados como uma tabela consultável.

Requisitos Importantes

A primeira linha do intervalo deve conter cabeçalhos de coluna
Os nomes das colunas são derivados da linha de cabeçalho
Cabeçalhos vazios resultam em colunas com nomes como "column_1", "column_2", etc.

Formatos de Intervalo Suportados

Planilha completa: sheet_range('Sheet1!A:Z')
Intervalo específico: sheet_range('Sales!A1:D100')
Intervalos nomeados com caracteres especiais são escapados automaticamente

text

-- Query all data from a sheet
SELECT * FROM sheet_range('Sheet1!A1:D100')

-- Filter and aggregate
SELECT category, SUM(amount) as total
FROM sheet_range('Sales!A1:E500')
WHERE date >= '2024-01-01'
GROUP BY category

-- Sort by multiple columns
SELECT * FROM sheet_range('Customers!A:F')
ORDER BY region ASC, revenue DESC

Exemplos de consultas em planilhas

Consultando Bancos de Dados Externos

Se você tiver conexões de dados externos configuradas, pode consultá-las usando o nome da conexão:

PostgreSQL
Referencie as tabelas como connection_name.schema.table. O esquema padrão é geralmente "public".

BigQuery
Referencie as tabelas como connection_name.dataset.table.

As consultas a bancos de dados externos funcionam exatamente como o SQL padrão. Você pode usar todos os recursos suportados pelo DuckDB, incluindo joins, subconsultas, funções de janela e CTEs.

Tip

Configure suas conexões externas primeiro no painel External Data Connections antes de consultá-las.

text

-- Query a PostgreSQL table
SELECT * FROM my_postgres.public.customers
WHERE country = 'USA'

-- Query a BigQuery table
SELECT event_date, COUNT(*) as events
FROM my_bigquery.analytics.page_views
GROUP BY event_date

-- Join PostgreSQL with BigQuery
SELECT p.name, b.total_events
FROM my_postgres.public.products p
JOIN my_bigquery.analytics.product_stats b
  ON p.id = b.product_id

Exemplos de consultas a bancos de dados externos

Combinando Dados de Planilhas e Bancos de Dados

Um dos recursos mais poderosos é a capacidade de combinar dados de diferentes fontes. Você pode unir dados de planilhas com bancos de dados externos em uma única consulta.

Casos de Uso Comuns

Enriquecer registros de planilhas com dados de clientes do seu banco de dados
Comparar dados de rastreamento local com seu data warehouse
Validar entradas de planilhas em relação a tabelas de referência externas
Combinar dados de vendas de planilhas com o catálogo de produtos do banco de dados

text

-- Join spreadsheet orders with database customers
SELECT
  s.order_id,
  s.order_date,
  s.amount,
  c.customer_name,
  c.email,
  c.tier
FROM sheet_range('Orders!A1:D500') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
WHERE s.amount > 1000

-- Cross-database aggregation
SELECT
  c.country,
  COUNT(*) as order_count,
  SUM(s.amount) as total_sales
FROM sheet_range('Sales!A1:C1000') s
JOIN my_postgres.public.customers c
  ON s.customer_id = c.id
GROUP BY c.country
ORDER BY total_sales DESC

Exemplos de joins entre fontes distintas

Opções de Saída das Consultas

Os resultados das consultas podem ser entregues de duas maneiras:

Resultados Inline (Padrão)
Os resultados são retornados diretamente ao ModelMonkey para análise e raciocínio. Isso é útil para consultas exploratórias em que você deseja entender os dados antes de decidir o que fazer com eles.

Retorna até 20 linhas por padrão (configurável até 100)
Inclui tipos de coluna e metadados
Ideal para exploração rápida de dados

Saída em Planilha
Os resultados são gravados diretamente em uma nova aba da sua planilha. Isso é útil quando você deseja manter os resultados da consulta para trabalho posterior.

Cria uma nova aba com o nome especificado
Inclui todas as linhas (sem limite de linhas)
Linha de cabeçalho adicionada automaticamente
Perfeito para criação de relatórios ou preparação de dados

Tip

Peça ao ModelMonkey para "salvar os resultados em uma nova aba" ou "gravar a saída em uma aba chamada Results" para usar o modo de saída em planilha.

Tratamento de Tipos de Dados

O ModelMonkey infere automaticamente os tipos de coluna a partir dos dados da sua planilha:

Tipos Suportados

Números: Inteiros e decimais são detectados e tratados como tipos numéricos
Booleanos: Valores TRUE/FALSE são reconhecidos como booleanos
Texto: Todo o restante é tratado como texto (VARCHAR)
Datas: Valores de data nas células são normalmente tratados como texto; use funções de data do SQL para analisá-los

Processo de Inferência de Tipo
O ModelMonkey faz uma amostragem das primeiras linhas de dados para determinar o tipo adequado para cada coluna. Se uma coluna contiver tipos mistos, o padrão será texto para evitar perda de dados.

text

-- Parse date strings in queries
SELECT
  order_id,
  strptime(order_date, '%Y-%m-%d') as parsed_date,
  amount
FROM sheet_range('Orders!A1:C100')
WHERE strptime(order_date, '%Y-%m-%d') >= DATE '2024-01-01'

-- Cast numeric strings
SELECT
  product_name,
  CAST(price AS DOUBLE) as numeric_price
FROM sheet_range('Products!A1:B50')

Trabalhando com tipos de dados

Considerações de Desempenho

Execução de Consultas

As consultas têm um tempo limite de 30 segundos
O conjunto de resultados máximo é de 16.384 linhas por segurança
Intervalos grandes de planilhas são carregados na memória para consulta

Boas Práticas

Especifique intervalos precisos em vez de colunas inteiras (por exemplo, A1:D500 em vez de A:D)
Use cláusulas WHERE para filtrar cedo e reduzir os dados processados
Para conjuntos de dados muito grandes, considere usar a saída em planilha para evitar problemas de memória
Indexe tabelas grandes em bancos de dados externos para joins mais rápidos

Cache
Os resultados das consultas não são armazenados em cache entre as solicitações. Cada consulta relê os dados atuais da planilha, garantindo que você sempre obtenha os valores mais recentes.

Warning

Intervalos muito grandes (dezenas de milhares de linhas) podem tornar a execução das consultas mais lenta. Considere filtrar os dados ou usar bancos de dados externos para análises em grande escala.

Funcionalidades SQL Suportadas

O ModelMonkey suporta uma ampla gama de funcionalidades SQL por meio do DuckDB:

Operações Padrão

SELECT, FROM, WHERE, ORDER BY, LIMIT
GROUP BY com funções de agregação (SUM, COUNT, AVG, MIN, MAX, etc.)
Cláusulas DISTINCT e HAVING
UNION, INTERSECT, EXCEPT

Joins

INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL OUTER JOIN
Cross joins e self joins
Joins com múltiplas tabelas

Funcionalidades Avançadas

Subconsultas e CTEs (cláusulas WITH)
Funções de janela (ROW_NUMBER, RANK, LAG, LEAD, etc.)
Expressões CASE
Funções de string, funções de data, funções matemáticas

Não Suportado

INSERT, UPDATE, DELETE (as consultas são somente leitura)
CREATE TABLE, ALTER TABLE (sem modificações de esquema)
Stored procedures ou funções definidas pelo usuário

Exemplos de Consultas

Aqui estão alguns exemplos práticos de consultas SQL que você pode utilizar:

text

-- Monthly sales summary
SELECT
  strftime(strptime(date, '%Y-%m-%d'), '%Y-%m') as month,
  COUNT(*) as num_orders,
  SUM(amount) as total_revenue,
  AVG(amount) as avg_order_value
FROM sheet_range('Orders!A1:D1000')
GROUP BY month
ORDER BY month DESC

-- Find duplicate entries
SELECT email, COUNT(*) as count
FROM sheet_range('Contacts!A1:E500')
GROUP BY email
HAVING COUNT(*) > 1

-- Top customers by spending
SELECT
  customer_id,
  SUM(amount) as total_spent,
  COUNT(*) as num_orders
FROM sheet_range('Orders!A1:D1000')
GROUP BY customer_id
ORDER BY total_spent DESC
LIMIT 10

-- Running total with window function
SELECT
  date,
  amount,
  SUM(amount) OVER (ORDER BY date) as running_total
FROM sheet_range('Transactions!A1:C100')

Exemplos práticos de consultas SQL

Solução de Problemas

Erros de "Column not found"

Verifique se a linha de cabeçalho contém os nomes de coluna esperados
Os nomes de coluna diferenciam maiúsculas de minúsculas
Espaços em nomes de coluna funcionam, mas podem precisar de aspas em consultas complexas

Erros de "Invalid range"

Verifique se o nome da aba está escrito corretamente
Certifique-se de que o intervalo existe e contém dados
Verifique se há caracteres especiais nos nomes das abas que precisam de escape

Erros de "Query timeout"

Simplifique sua consulta ou reduza o intervalo de dados
Adicione cláusulas WHERE para filtrar dados mais cedo
Considere usar a saída em planilha para conjuntos de resultados grandes

Erros de "Connection not found"

Verifique se o nome da conexão externa está correto
Confirme se a conexão está ativa no painel External Data Connections
Certifique-se de que você tem permissão para acessar o banco de dados externo

Resultados vazios ou inesperados

Verifique se os tipos de dados correspondem às suas condições WHERE
Confirme se os formatos de data correspondem ao que está na sua planilha
Procure por espaços no início ou no final em dados de texto