Consultar uma pasta de arquivos Parquet com SQL

Veja tudo o que o Query Streams pode fazer além deste guia Comece a usar gratuitamente

Suportes

+mais

Dados em tempo real

Substitua as exportações por SQL sob demanda

Excel Folhas

Análises de BI e IA

Pergunte à Nova, obtenha SQL + gráficos

Conheça a Nova

+mais

Automação

Sincronização programada para mais de 6 plataformas

Explorar

+mais

API para SQL

Consultar APIs com SQL, sem código

Explorar

O Query Streams é uma plataforma segura de integração de banco de dados em tempo real, e seu conector de pasta Parquet transforma uma pasta de arquivos .parquet em uma tabela SQL ativa que você pode consultar no Microsoft Excel, Google Sheets, Airtable e até mesmo com seu assistente de IA. Saiba mais em QueryStreams.com e inscreva-se gratuitamente Para consultar sua primeira pasta Parquet em minutos.

Alguém te deu uma pasta com arquivos Parquet.

Chega por uma das poucas rotas já bem conhecidas. Uma exportação de um data lake chega a uma parcela de algumas centenas de pessoas. parte-00000.parquet Arquivos. Um trabalho do dbt ou do Spark grava sua saída em algum lugar, e esse lugar acaba sendo uma pasta de rede. Uma equipe de análise entrega um extrato. Uma tabela de um data warehouse é arquivada em disco quando a renovação da licença se torna cara, e dezoito meses depois alguém quer saber o que havia nela.

O problema é que o formato Parquet não é legível para humanos. Clicar duas vezes em um arquivo... .parquet O arquivo não faz nada de útil. Abri-lo em um editor de texto resulta em uma tela cheia de código binário. Os conselhos que você recebe quando pergunta são "use o Spark" ou "escreva um pouco de código em Python", e nenhuma das duas é uma resposta séria para alguém cujo trabalho é apresentar um número ao diretor financeiro na quinta-feira.

O Conector de pasta Parquet é o caminho mais curto. Você aponta o Agente de Fluxos de Consulta para a pasta e cada arquivo correspondente passa a fazer parte de uma única tabela SQL. Nada é convertido, nada é mesclado em um novo arquivo e nada é carregado — os arquivos permanecem exatamente onde estão e você os consulta de onde estão.

O esquema já está dentro do arquivo.

Este é o fato que diferencia o Parquet de todos os outros tipos de pasta, e vale a pena entendê-lo porque explica por que esse conector é tão simples de usar.

Todo arquivo Parquet termina com um rodapé: um bloco de metadados que indica os nomes das colunas, seus tipos de dados exatos, se cada coluna permite valores nulos e quantas linhas o arquivo contém. Esse rodapé é escrito por quem gerou o arquivo e é a palavra final. Não é uma dica ou uma convenção — é a própria declaração do arquivo sobre o seu conteúdo.

Portanto, quando o conector amostra a pasta, ele não está inspecionando os valores dos dados e tirando conclusões a partir deles. Ele pede a cada arquivo amostrado que se descreva, lê a resposta e a fixa como a definição da tabela. Os tipos são declarado em vez de inferidoO que significa que não há necessidade de se preocupar com o tamanho da amostra e nenhuma possibilidade de que a décima milésima linha contradiga o que as cem primeiras indicavam.

Os tipos também são mantidos intactos. Um DECIMAL(18,2) A coluna no arquivo é uma coluna decimal na tabela, não uma aproximação de ponto flutuante de um, porque o valor nunca passa por uma string em seu caminho. Todo o resto nesta família — a varredura de pastas, o registro de arquivos, o cache local criptografado, as tabelas de manutenção — funciona exatamente como descrito em Como funcionam os conectores de conjunto de arquivosO que se segue é apenas o que diferencia o Parquet.

Aquilo sobre o que você nunca precisa discutir

A maneira mais clara de perceber a vantagem é compará-la com um arquivo CSV, que realiza a mesma tarefa sem o rodapé. Tudo em Conector de pasta CSV O que significa detectar, concordar e defender está claramente declarado no Parquet.

Há, consequentemente, poucas opções de configuração. Um conector de pasta CSV oferece delimitador, caractere de aspas, opção de cabeçalho, codificação, strings nulas, formato de data e modo de layout, pois todas essas opções são genuinamente incertas em relação a um arquivo de texto. Um conector de pasta Parquet não possui nenhuma dessas opções, pois o próprio arquivo já responde a essas perguntas — as configurações disponíveis estão listadas mais adiante.

Colunas que apenas alguns arquivos possuem.

Pastas de arquivos Parquet raramente são gravadas de uma só vez. Um pipeline recebe um novo campo em março, então os arquivos de março em diante têm uma coluna que os de janeiro não têm. Este é o único julgamento genuíno que o conector precisa fazer, e ele o faz de uma maneira específica.

A tabela fixada é a união das colunas encontradas nos arquivos amostrados, não em sua interseção. Uma coluna que aparece apenas em alguns deles ainda entra na tabela — ela é simplesmente marcada como nula e lida como NULO para os arquivos que são anteriores a ele. Portanto, você mantém todas as colunas da pasta em vez de perder as que foram adicionadas posteriormente.

Uma coluna sendo ausente é tolerado. Uma coluna que possui um tipo diferente Não é. Se ID do pedido Se um arquivo contém um inteiro de 64 bits e outro contém texto, o conector se recusa a fixar qualquer valor e especifica a discrepância com precisão: qual coluna, qual tipo e em quais dois arquivos. Ele não escolhe um valor específico e não converte silenciosamente um para o outro para que os números coincidam.

Cheirar é barato, porque nada é lido.

Amostras de fluxos de consulta até 64 arquivos quando conecta uma pasta pela primeira vez. Para CSV, isso significa abrir e analisar 64 arquivos. Para Parquet, significa buscar até o final de 64 arquivos e ler um bloco de metadados, o que é uma tarefa trivial mesmo quando os arquivos têm centenas de megabytes cada.

A mesma estratégia funciona durante a sincronização. A contagem de linhas de cada arquivo é extraída do rodapé sem afetar os dados, permitindo que o conector saiba antecipadamente se um arquivo ultrapassará o limite de linhas por arquivo e se a sincronização como um todo está se aproximando do limite de linhas. Ele pode recusar a sincronização e definir um limite. antes O arquivo problemático é gravado na tabela, em vez de o problema ser descoberto no meio do processo e deixar você com uma carga parcial.

O tamanho do arquivo é verificado em primeiro lugar, antes de qualquer movimentação de um único byte. Um arquivo que exceda o limite de tamanho é rejeitado pelo nome e o restante da pasta é sincronizado em torno dele.

Cada linha conhece sua posição no arquivo.

Assim como em todos os conectores de conjunto de arquivos, cada linha contém um _arquivo_fonte coluna nomeando o arquivo de onde veio e um _row_id que é único em toda a tabela. Em uma pasta Parquet, _row_id é melhor do que isso: os leitores do Parquet expõem uma genuína número da linha do arquivoAssim, o identificador é construído a partir do nome do arquivo mais a posição ordinal real daquela linha dentro do arquivo, preenchido com zeros até atingir doze dígitos.

O importante é o espaçamento. Classificar por _row_id O fato de as linhas serem organizadas na ordem do arquivo, em vez da ordem 1, 10, 100, 2 e 12 dígitos, é suficiente para manter essa ordem por um trilhão de linhas em um único arquivo — ultrapassando com folga qualquer limite que você possa definir. O CSV não possui um conceito equivalente, então este é um caso em que o formato colunar oferece uma vantagem adicional, em vez de simplesmente evitar problemas.

SELECT _source_file, COUNT(*) AS row_count, SUM(net_amount) AS net_amount FROM orders GROUP BY _source_file ORDER BY net_amount DESC;

E como o identificador de linha é ordenado, você pode examinar o início de um arquivo específico sem precisar ler a pasta inteira — o que é útil quando uma partição parece suspeita e você quer ver o que realmente contém.

SELECT _row_id, order_id, order_date, net_amount FROM orders WHERE _source_file = 'part-00042.parquet' ORDER BY _row_id LIMIT 20;

Quando um arquivo deixa de corresponder ao pino

Uma vez que o formato é definido, cada arquivo é verificado em relação a ele na entrada — e, novamente, essa verificação é uma leitura do rodapé, não uma leitura de dados, portanto é barata o suficiente para ser feita em todos os arquivos, sempre. Um arquivo que não esteja mais em conformidade é estacionadoSe as linhas permanecerem fora da tabela, o motivo será registrado e o restante da pasta será sincronizado normalmente.

Quatro pontos podem ser considerados motivo de discordância, e vale a pena conhecê-los separadamente porque o terceiro surpreende as pessoas.

• Um tipo foi alterado. A coluna existe, mas o rodapé agora a declara como algo diferente do que estava fixado.
• Uma coluna obrigatória desapareceu. Uma coluna que o pino marcou como não nula está ausente do arquivo.
• Um arquivo removeu uma coluna que costumava ter. Mesmo quando a coluna fixada permite valores nulos, um arquivo que fez Se a coluna for carregada quando a pasta foi amostrada e, desde então, parar de ser carregada, ela será armazenada em vez de lida como nula. Lê-la como nula anularia silenciosamente todas as somas construídas com base nessa coluna, e um total incorreto é pior do que um arquivo ausente.
• Surgiu uma coluna totalmente nova. Uma coluna que o PIN nunca viu e que você não excluiu, estaciona o arquivo em vez de descartá-lo silenciosamente.

A releitura de um arquivo substitui suas linhas em vez de adicionar novas. Tudo o que um arquivo havia contribuído anteriormente é removido e seu conteúdo atual é inserido em uma única transação; portanto, uma partição reescrita não pode deixar duplicatas ou uma tabela parcialmente atualizada caso algo falhe durante o processo.

Todas as configurações de Parquet e quando alterá-las.

O mais útil a dizer sobre este cartão é o que ele é. não nisso. Um conector de pasta Parquet não possui nenhuma configuração específica de formato. Uma pasta CSV tem um delimitador, um caractere de aspas, uma codificação, strings nulas e um formato de data. Uma pasta do Excel tem uma lista de planilhas. Uma pasta JSONL tem uma profundidade de achatamento. O Parquet não tem nada disso, e o motivo é o rodapé: o esquema é declarado dentro de cada arquivo, então não há nada para informar ao conector e nada para ele adivinhar. A questão de "qual opção eu escolhi errado?" não existe aqui.

O que resta é uma lista curta. Todo o resto você vê no Conexão A guia — pastas raiz, subpastas de verificação e profundidade máxima, padrões de exclusão, seguimento de links simbólicos, padrão de análise de nome de arquivo, nomes de token de pasta, intervalo de verificação, hash de conteúdo, política de exclusão, retenção de log de eventos e as diretrizes de verificação — comporta-se de maneira idêntica em todos os tipos de pasta e é documentada uma única vez, na íntegra, em guia do conector File SetEsta seção aborda apenas o que é específico de uma pasta de arquivos Parquet.

Nome da tabela

Obrigatório. O Parquet é um driver de tabela única: cada arquivo que os padrões de inclusão correspondem é unido em uma única tabela, e é assim que essa tabela é chamada em SQL — pedidos, eventos, viagens, seja lá o que a pasta realmente contenha. Somente letras, dígitos e sublinhados, e não pode começar com um dígito; qualquer outra coisa será rejeitada ao salvar, e não durante a sincronização.

Escolha esse nome deliberadamente, pois ele será usado em todas as consultas salvas, em todas as perguntas do Nova e em todas as atualizações de planilhas. Renomeá-lo posteriormente não é destrutivo, mas significa ter que revisar tudo o que você já construiu com base nele. Uma pasta de arquivos de peças chamada parte-00000.parquet Não fornece nenhuma informação sobre o conteúdo das linhas, portanto, o nome da tabela geralmente é o único rótulo legível para humanos que os dados recebem.

Incluir padrões

Padrão: **/*.parquet — definidos automaticamente quando você seleciona a opção Pasta Parquet. Padrões glob, um por linha, definem quais arquivos nas pastas raiz estão no escopo. Se deixado sem alterações, ele seleciona todos os arquivos Parquet na árvore, que é o resultado desejado na primeira vez que você o utiliza para exportar.

Reduzir esse limite é a principal ferramenta que você tem, e quase sempre é uma jogada melhor do que aumentá-lo. As exportações do data lake são particionadas, portanto a estrutura de pastas já inclui o filtro desejado. Se uma verificação for recusada porque o compartilhamento contém mais arquivos do que o limite permite, limite o padrão às partições que você realmente consulta, em vez de tentar atingir o limite de arquivos — um conector que lê quatro mil arquivos é mais rápido para verificar, mais rápido para sincronizar e muito mais fácil de entender do que um que lê quatrocentos mil e filtra posteriormente.

**/*.parquet todos os arquivos Parquet na árvore (o padrão) ano=2026/**/*.parquet um ano de um lago particionado pelo Hive **/part-*.parquet Arquivos de partes do Spark, ignorando extras adicionados manualmente orders/**/*.parquet um conjunto de dados de uma compartilhamento contendo vários

Uma regra pega as pessoas de surpresa, e o mago a declara no próprio campo de batalha: Uma pasta mista consiste em dois conectores na mesma raiz, um para cada driver. Se \\lago\exportações contém arquivos CSV juntamente com Parquet, ampliando esse padrão para **/*.* Não oferece ambos — os dois formatos não podem compartilhar uma forma fixada. Crie um conector de pasta Parquet e um Conector de pasta CSV apontavam para o mesmo caminho, cada um com seu próprio padrão de inclusão e seu próprio nome de tabela.

Substituições de manifesto (JSON)

Escondido atrás Mostrar opções avançadase é mais útil no Parquet do que em qualquer outro lugar. Em todos os outros lugares dessa família, as sobreposições são uma maneira de corrigir algo que o conector adivinhou. Aqui, nada é adivinhado — portanto, uma sobreposição é uma maneira de corrigir algo que o conector não adivinhou. oleoduto fez isso, que é exatamente o caso em que você não pode simplesmente corrigir os arquivos.

Três cenários abrangem quase todos os usos reais. Um trabalho do Spark nomeado como uma coluna. col_14 ou amt_net_x E ninguém quer escrever isso em um relatório. Uma coluna contém informações confidenciais e não deveria existir na tabela. Ou uma coluna numérica precisa de mais precisão na tabela do que a declarada nos arquivos. Todas as três são edições de uma linha, aplicadas quando a forma é fixada, tornando-se parte da definição da tabela em vez de algo que você reaplica em cada consulta.

{ "renomeia": { "qtd": "quantidade" }, "redigita": { "preço": "DECIMAL(18,4)" }, "exclui": [ "notas_internas" ] }

• renomeia — dê um nome melhor à coluna. Você não pode renomeá-la para _arquivo_fonte ou _row_idE duas colunas não podem ser renomeadas com o mesmo nome.
• redigitações — forçar o tipo de uma coluna. O tipo definido aqui é uma instrução deliberada, portanto, é aplicado sem a verificação rigorosa do rodapé que, de outra forma, impediria a execução do arquivo. Somente nomes de tipo simples com precisão opcional: DECIMAL(18,4), VARCHAR, BIGINT, DATA.
• excluir — omitir colunas da tabela por completo. É importante saber que uma coluna excluída também é uma coluna que a verificação de desvios deixa de considerar; portanto, esta é a maneira mais adequada de ignorar um campo que um pipeline altera constantemente.

A caixa deve conter um objeto JSON ou nada — JSON inválido é rejeitado ao salvar, e não ignorado silenciosamente. Esvaziar a caixa apaga suas configurações. e retorna a tabela ao formato declarado pelos rodapés, que é a maneira pretendida de desfazer uma alteração, em vez de excluir e reconstruir o conector.

Por que não existe uma opção de layout de tabela?

As pastas CSV, Excel e JSONL oferecem uma Layout da tabela A escolha — um layout fixo ou uma tabela por layout — se deve ao fato de que esses são os formatos que os humanos montam manualmente, e uma pasta com esses arquivos realmente acumula diferentes conjuntos de colunas ao longo dos anos. O Parquet não possui essa configuração, propositalmente. O Parquet é escrito por máquina por definição: algo gerou esses arquivos programaticamente e, se esse algo estiver emitindo vários formatos diferentes em uma pasta, dividi-los em tabelas separadas mascararia um problema de fluxo de trabalho em vez de expô-lo.

Assim, uma pasta Parquet recebe uma tabela, e a discordância é relatada em vez de resolvida. Colunas ausentes são absorvidas pela união e marcadas como anuláveis; conflitantes. tipos são uma recusa nomeada. Se você realmente estiver armazenando vários conjuntos de dados não relacionados em um único compartilhamento, a solução é um conector por conjunto de dados, com escopo definido. Incluir padrões — o que, de qualquer forma, é mais claro, porque cada um recebe seu próprio nome de tabela.

Limites de ingestão e limites de digitalização

Os quatro limites de ingestão (linhas e bytes, por arquivo e por sincronização) e os limites de varredura (arquivos por varredura, profundidade, orçamento de tempo, paralelismo por raiz) são compartilhados entre todos os tipos de pasta e estão localizados em segundo plano. Mostrar opções avançadasE siga uma regra que vale a pena repetir: deixe uma caixa em branco para aceitar o valor padrão, porque zero nunca significa ilimitado e é recusado de imediato. Seus valores e as razões para levantar cada um deles estão no Guia do conector do conjunto de arquivosOs que mais importam para uma pasta Parquet estão listados na tabela de proteção acima.

O Parquet tem uma vantagem aqui, descrita anteriormente: como a contagem de linhas está no rodapé, o limite de linhas por arquivo é verificado antes que qualquer dado do arquivo seja lido, portanto, uma violação desse limite é uma recusa específica, em vez de uma falha no carregamento. Aumentar o limite ainda é a segunda melhor solução. Primeiro, restrinja o padrão de inclusão.

Importando dados Parquet para o Microsoft Excel

A conversão de Parquet para Excel é o principal motivo para tantas solicitações, e a resposta sincera é que você não deve convertê-la. Uma vez que a pasta esteja configurada como um conector, o suplemento Query Streams para Microsoft Excel executa uma consulta salva e insere as linhas na planilha, atualizando-as sempre que você precisar. Você obtém o formato Parquet no Excel sem uma etapa de conversão, sem um cluster Spark e sem uma cópia dos dados ficando armazenada silenciosamente na pasta de Downloads de alguém. A mesma consulta funciona sem alterações no Google Sheets.

Você precisa de uma conta do Query Streams e do Agente de Rede em execução em uma máquina que possa ver a pasta — um servidor, uma estação de trabalho com o compartilhamento mapeado ou seu próprio laptop. Os conectores de pasta Parquet exigem Agente de rede 2.6 ou mais recente.

1. Instale o agente a partir do página de download se ainda não estiver em execução.
2. No portal, adicione um conector de dados e selecione Pasta Parquet.
3. Insira o caminho da pasta conforme o computador do agente o vê e dê um nome à tabela — esse campo é obrigatório, pois todos os dados da pasta são unidos em uma única tabela.
4. Deixe o padrão de inclusão ativado **/*.parquet a menos que a pasta contenha mais itens do que você deseja na tabela, caso em que você pode restringir o tamanho dela — **/part-*.parquetou uma única partição, como ano=2026/**/*.parquet.
5. Salvar. O agente lê os rodapés de até 64 arquivos, fixa o esquema e relata as colunas e os tipos encontrados.
6. Abra o construtor de consultas, selecione o conector e escreva SQL — ou peça à Nova AI para escrever para você.
7. Salve a consulta e execute-a a partir do suplemento do Microsoft Excel ou do Google Sheets sempre que precisar dos números.

A partir daí, a pasta se comporta como qualquer outra fonte de dados. Ela se conecta ao Microsoft SQL Server, PostgreSQL, MySQL, BigQuery e outros, além de conectores de API como Stripe ou Shopify. Assim, uma tabela arquivada em um compartilhamento de arquivos pode ser conectada a dados de produção ativos em uma única instrução somente leitura, sem a necessidade de carregar nada no data warehouse primeiro.

Perguntas frequentes

Começar a usar

Guias relacionados: Como consultar uma pasta de arquivos com SQL | Combinar vários arquivos CSV em uma única tabela. | Baixe o Agente de Fluxos de Consulta | Todos os guias do Conector de Conjunto de Arquivos

Categoria: Conectores de Conjunto de Arquivos

Tags: parquet para excel, consultar arquivos parquet, ler parquet sem spark, pasta parquet, parquet no excel, conector de pasta parquet, sql em parquet, exportação de data lake

Metadescrição: Consulte uma pasta de arquivos Parquet como uma única tabela SQL e importe os dados para o Microsoft Excel. Sem Spark, sem uploads.