Import CSV

Descrição

Importe arquivos de texto delimitado do PlaidCloud Document. Isso inclui, entre outros, os seguintes tipos de delimitador:

vírgula (, )
barra vertical (|)
ponto e vírgula (; )
tabulação
espaço ( )
arroba (@)
til (~)
dois-pontos (:)

Exemplos

Ainda não há exemplos…

Parâmetros de importação

Importar origem e destino

O seletor de arquivos nesta transformação permite escolher um arquivo armazenado em um local de documentos do PlaidCloud para importar.

Você também pode escolher um diretório para importar, e todos os arquivos dentro dele serão importados como parte da execução da transformação.

Conta de Origem

Escolha uma conta de documentos do PlaidCloud à qual você tenha acesso. Isso permite selecionar um diretório ou arquivo na próxima seleção.

Dentro de um projeto, a lista também oferece Padrão do projeto no topo — um substituto para a conta que o projeto tiver definida como padrão no momento. Uma nova etapa já vem com Padrão do projeto selecionado quando o projeto tem um; uma etapa existente mantém a conta com a qual foi salva até você alterá-la. Uma etapa deixada em Padrão do projeto é executada com a conta que for o padrão do projeto no momento — se nenhuma estiver definida, a execução falha e cita o projeto, em vez de recorrer a outra conta.

Opção de Pesquisa

A opção Pesquisar permite encontrar todos os arquivos correspondentes abaixo de um caminho de diretório especificado para importar. Isso pode ser particularmente útil se muitos arquivos precisam ser incluídos, mas estão armazenados em diretórios aninhados ou misturados a outros arquivos do mesmo diretório que você não quer importar.

O caminho de pesquisa selecionado é o diretório inicial da busca. O processo de pesquisa procura todos os arquivos dentro desse diretório, bem como nos subdiretórios, que correspondam às condições de pesquisa especificadas. Verifique se os critérios de pesquisa também podem ser aplicados aos arquivos dos subdiretórios.

A pesquisa pode ser aplicada usando as seguintes condições:

Exata: corresponde exatamente ao texto pesquisado
Começa com: corresponde a qualquer arquivo que comece com o texto pesquisado
Contém: corresponde a qualquer arquivo que contenha o texto pesquisado
Termina com: corresponde a qualquer arquivo que termine com o texto pesquisado

Um assistente de IA ou a API REST também pode definir a pesquisa como glob, um padrão com curinga como CO Store*.yxdb comparado com o nome completo do arquivo sem diferenciar maiúsculas de minúsculas, ou regex, uma expressão regular com a qual o nome completo do arquivo deve corresponder. Uma expressão regular diferencia maiúsculas de minúsculas, a menos que comece com (?i).

Caminho do Arquivo de Origem

Quando um arquivo ou diretório de arquivos específico é necessário para a importação, escolher o arquivo ou diretório é uma opção melhor do que usar a pesquisa.

Para selecionar o arquivo ou diretório, basta usar o botão de navegação para escolher o caminho da conta de documentos selecionada acima.

Substituição de Variáveis

Tanto na opção de pesquisa quanto na opção de arquivo/diretório específico, é possível usar variáveis no caminho, no texto de pesquisa e nos nomes de arquivo.

Um exemplo que usa a variável current_month para apontar dinamicamente para o arquivo correto:

legal_entity/inputs/{current_month}/ledger_values.csv

Tabela de Destino

A seleção de destino para importações é limitada a tabelas, já que as visões não contêm os dados subjacentes.

Opção Dinâmica

A opção Dinâmica permite especificar uma tabela usando texto, inclusive variáveis. Isso é útil ao empregar fluxos de trabalho orientados por variáveis, em que as referências a tabelas e visões são relativas às variáveis especificadas.

Um exemplo que usa a variável current_month para apontar dinamicamente para a tabela de destino:

legal_entity/inputs/{current_month}/ledger_values

Opção Estática

Quando uma tabela específica é desejada como destino da importação, deixe a caixa Dinâmico desmarcada e selecione a tabela de destino.

Se a tabela de destino não existir, selecione o botão Criar novo para criar a tabela no local desejado.

O Explorador de tabelas está sempre disponível em qualquer seleção de tabela. Clique no botão Explorador de tabelas à direita da seleção de tabela e uma janela do Explorador de tabelas será aberta.

Opção Remover caracteres não ASCII

Ao selecionar esta opção, a importação remove qualquer conteúdo que não seja ASCII. Embora o PlaidCloud ofereça suporte total a Unicode (UTF-8), arquivos do mundo real podem conter todo tipo de codificação e caracteres soltos que dificultam o processamento.

Se o conteúdo do arquivo deve conter somente ASCII, marcar esta caixa ajuda a garantir que o processo de importação seja executado sem problemas.

Opção Excluir Arquivos Após a Importação

Esta opção permite que o processo de importação exclua o arquivo da conta de documentos do PlaidCloud após a conclusão bem-sucedida da importação.

Isso pode ser útil se os arquivos de importação são gerados e podem ser recriados a partir de um sistema de registro, ou se não há motivo para reter os arquivos de entrada brutos depois de processados.

Somente os arquivos importados são excluídos. Um arquivo que foi ignorado ou que gerou um aviso durante a importação permanece na pasta.

Opção Ignorar Nova Importação Se os Arquivos de Origem Não Mudaram

Quando esta opção está ativada, uma execução do fluxo de trabalho com esta etapa ignora a importação inteira — download, conversão e reconstrução da tabela — se os arquivos de origem e as configurações da etapa não mudaram desde a última execução bem-sucedida. Isso evita repetir o trabalho quando um fluxo de trabalho agendado é executado novamente com arquivos de origem que não mudaram.

A etapa compara cada arquivo de origem por caminho, tamanho e data da última modificação (além de um hash de conteúdo, quando a origem o fornece). Se algum arquivo for adicionado, removido ou alterado, ou se a configuração da etapa mudar, a importação é executada normalmente. A opção vem ativada por padrão — desmarque-a para sempre importar novamente — e importações manuais avulsas sempre são executadas.

Para ignorar a importação, a tabela de destino também precisa ainda conter as linhas carregadas pela última importação. Se a tabela tiver sido esvaziada desde então ou se a contagem de linhas não puder ser lida, a importação é executada novamente em vez de ser ignorada, o que deixaria as etapas seguintes sem dados.

Algumas origens (por exemplo, SFTP) não fornecem um hash de conteúdo; nelas, o sinal de mudança é apenas o tamanho e a data da última modificação do arquivo. Um arquivo substituído no local com o mesmo tamanho e a mesma data de modificação seria tratado como inalterado e ignorado — desmarque esta opção em uma etapa cuja origem possa ser atualizada dessa forma.

Inspecionar arquivo de origem selecionado

Ao pressionar o botão Detectar configurações do arquivo de origem, o PlaidCloud abre o arquivo e o inspeciona para tentar determinar o formato dos dados. Verifique sempre as configurações detectadas para confirmar que parecem corretas.

Uma etapa cujo arquivo não retorna nenhuma coluna não pode ser salva: o salvamento é interrompido com Nenhuma coluna detectada. Quando o PlaidCloud não consegue ler o arquivo, a mensagem informa o motivo, por exemplo, uma extensão incomum para um arquivo delimitado ou um caminho de arquivo que usa uma variável de fluxo de trabalho não definida. Caso contrário, verifique se o delimitador e os caracteres de aspas e de escape correspondem ao arquivo, se ele é um arquivo de texto delimitado e se não está vazio.

Formato dos dados

Delimitador

Como mencionado acima, Inspecionar origem tenta determinar o delimitador no arquivo de origem. Se você preferir outro delimitador, use esta seção para especificá-lo. Os usuários podem escolher em uma lista de delimitadores padrão. Uma etapa sem delimitador definido usa vírgula.

vírgula (, )
barra vertical (|)
ponto e vírgula (; )
tabulação
espaço ( )
arroba (@)
til (~)
dois-pontos (:)

Tipo de cabeçalho

Como os arquivos CSV podem ou não conter cabeçalhos, o PlaidCloud oferece uma forma de usar os cabeçalhos, ignorá-los ou usar a ordem das colunas para determinar o alinhamento delas.

Sem cabeçalho: o arquivo CSV não contém cabeçalho. Use a lista de origem no Data Mapper para determinar o alinhamento das colunas
Com cabeçalho - usar cabeçalho e substituir lista de campos: o arquivo CSV tem um cabeçalho. Use os nomes de cabeçalho especificados e ignore a lista de origem no Data Mapper.
Com cabeçalho - ignorar cabeçalho e usar a lista de campos: o arquivo CSV tem um cabeçalho, mas ele deve ser ignorado. Use os nomes de cabeçalho especificados pela lista de origem no Data Mapper.

Tipo de cabeçalho é armazenado em header_treatment como use ou skip para as duas opções de cabeçalho. O Importar Excel também aceita dynamic.

Formato de data

Esta configuração é útil quando as datas contidas no arquivo CSV não são facilmente reconhecidas como datas e horas. O processo de importação tenta converter as datas, mas um pouco de informação extra pode ajudar nessa conversão.

Um valor que o warehouse não consegue ler com o formato informado é armazenado como vazio, sem interromper a importação; assim, um formato que não corresponde ao arquivo produz uma coluna de datas vazias e uma importação que ainda informa sucesso. Depois de alterar esta configuração, confira a coluna importada antes de confiar no resultado.

Caracteres especiais

As entradas de caracteres especiais controlam como o PlaidCloud trata a presença de determinados caracteres e o que eles significam no processamento do CSV

Caractere de aspas: é o caractere usado para indicar um conjunto de texto delimitado que deve ser processado como um único campo. Quando não definido, é aspas duplas (").
Caractere de escape: é o caractere usado para indicar que o caractere seguinte deve ser processado como está, sem ser interpretado como caractere especial. Útil quando um campo pode conter o delimitador. Quando não definido, é a barra invertida (\).
Caractere nulo: como os arquivos CSV não têm tipos de dados, este caractere permite indicar que o valor deve ser NULL, e não uma string vazia ou 0.
Campos vazios: um campo vazio é carregado como NULL em todos os lakehouses, tanto em colunas de texto quanto numéricas; portanto, um número em branco é NULL, e não 0. Uma célula que contém apenas espaços é carregada como está.
Negativos à direita: alguns sistemas de origem geram números negativos com o símbolo de negativo no final, em vez de no início. Esta configuração processa esses valores como números negativos.

Seleção de linhas

Para arquivos de entrada com registros estranhos, defina Ignorar linhas como o número de linhas a ignorar antes de processar os dados. Isso é útil se os arquivos contêm blocos de cabeçalho que precisam ser ignorados antes de chegar aos dados tabulares.

As linhas ignoradas incluem linhas em branco. Com um Tipo de cabeçalho igual a Com cabeçalho - usar cabeçalho e substituir lista de campos, o cabeçalho é lido da primeira linha após as linhas ignoradas, de modo que os dados são mapeados para as colunas de destino pelo nome do cabeçalho. Um arquivo que contém apenas as linhas ignoradas e um cabeçalho, sem linhas de dados, não importa nada, e a etapa ainda assim é concluída.

Exemplo: exportação de lista do SAP

Uma exportação de lista do SAP, como KE24, KSB1 ou FAGLL03, começa com um bloco de seleção, muitas vezes com linhas em branco, antes do cabeçalho das colunas:

Line Item Journal Entries
Company Code: 1000
Posting Date: 2026-09-01 to 2026-09-30

Company Code|Document Number|Posting Date|Amount
1000|100004512|2026-09-03|1,500.00

O cabeçalho está na linha 5, portanto há quatro linhas antes dele. Defina Ignorar linhas como 4 e Tipo de cabeçalho como Com cabeçalho - usar cabeçalho e substituir lista de campos. A importação lê Company Code, Document Number, Posting Date e Amount como nomes de coluna, e a primeira linha de dados é a linha seguinte ao cabeçalho.

Selecione Keep Quoted Empty Fields (“”) As Empty String para carregar um campo vazio entre aspas como string vazia, em vez de NULL.

Configurações adicionais

Mais opções de CSV contém estes campos:

Codificação (encoding) — o codec Python com o qual o arquivo é lido, em vez de detectá-lo. Bytes que não podem ser decodificados são lidos como U+FFFD.
Delimitadores (delimiters) — uma matriz JSON com todos os textos que separam colunas, em vez de um único delimitador. Cada um pode ter vários caracteres. Selecione Vários delimitadores seguidos contam como um (combine_delimiters) para contar vários delimitadores seguidos como um só.
Delimitador de linha (row_delimiter) — o texto que encerra uma linha quando está fora de aspas; uma quebra de linha em outro lugar passa a fazer parte do valor. Se ficar em branco, qualquer quebra de linha encerra uma linha.
Prefixo de linha de comentário (comment) — as linhas que começam com este texto não são importadas. Comentários (comments) lista comentários como pares Começa com e Termina com, que são removidos onde quer que estejam fora de aspas; sem Termina com, um comentário vai até o fim da linha.
Continuação de linha (line_continuation) — este texto antes de uma quebra de linha une a linha à seguinte.
Aspa de fechamento (quote_end) — a aspa que encerra um valor entre aspas, quando difere de Caractere de aspas. Selecione Um valor entre aspas mantém as aspas (keep_quotes) para manter as aspas de um valor entre aspas.
Importar uma linha vazia como uma linha de valores vazios (keep_blank_lines) — uma linha vazia é importada como uma linha de valores vazios, em vez de ser omitida.

Seleção de dados da tabela

Configuração do Data Mapper

Data Mapper de tabela

O Data Mapper é usado para mapear as colunas dos dados de origem para a tabela de dados de destino.

Inspeção e Preenchimento do Mapeador

O botão de menu Inspecionar origem oferece formas adicionais de mapear colunas da origem para o destino:

Preencher ambas as tabelas de mapeamento: propaga todos os valores da tabela de dados de origem para a tabela de dados de destino. Este é o comportamento padrão.
Preencher somente a tabela de mapeamento de origem: mapeia apenas todos os valores da tabela de dados de origem. Isso é útil ao modificar um fluxo de trabalho existente quando a estrutura de colunas da origem mudou.
Preencher somente a tabela de mapeamento de destino: propaga todos os valores apenas para a tabela de dados de destino.

Se as opções de coluna de origem e de destino não forem suficientes, é possível adicionar outras colunas à tabela de dados de destino de várias maneiras:

Propagar tudo insere todas as colunas de origem na tabela de dados de destino, quer elas já existam ou não.
Propagar selecionadas insere apenas as colunas de origem selecionadas.
Clique com o botão direito no lado do destino e selecione Inserir linha para inserir uma linha imediatamente acima da linha selecionada.
Clique com o botão direito no lado do destino e selecione Anexar linha para inserir uma linha no final (extrema direita) da tabela de dados de destino.

Exclusão de Colunas

Para excluir colunas da tabela de dados de destino, selecione as colunas desejadas, clique com o botão direito e selecione Excluir.

Colunas de Origem que Não Estão Mais Listadas

Uma linha de destino pode indicar uma Coluna de origem que a tabela de dados de origem não lista mais, por exemplo depois que a origem foi inspecionada novamente. A etapa nunca remove essa linha por você. Em vez disso, o nome da coluna aparece em vermelho, após um sinal de aviso ⚠, e ao passar o mouse sobre ele é exibida a informação de que a coluna não está nas colunas de origem. Em uma etapa com várias tabelas, como uma união, cada tabela é verificada em relação às suas próprias colunas de origem.

Uma linha com resumo Constante, Expressão ou Contagem (incluindo nulos) nunca é sinalizada, porque a etapa não lê a coluna de origem dela. Nada é sinalizado enquanto a tabela de dados de origem não listar nenhuma coluna, por exemplo antes de a origem ser inspecionada pela primeira vez.

Ao salvar uma etapa que ainda tem linhas sinalizadas, uma caixa de diálogo Colunas obsoletas encontradas as lista sob a guia ou a tabela em que estão e oferece três opções:

Remover todas e salvar — remove as linhas sinalizadas e, em seguida, salva.
Salvar mesmo assim — salva a etapa como está.
Cancelar — volta para a etapa sem salvar.

Para manter uma linha e eliminar o aviso dela, adicione a coluna de volta à tabela de dados de origem ou escolha uma coluna que a tabela de dados de origem liste.

Tipo de Dados da Coluna

Toda coluna de destino tem um Tipo. Uma coluna propagada da origem mantém o tipo da coluna de origem; uma linha que você adiciona manualmente começa como Texto, e você define o Tipo para indicar o que ela deve realmente ser — uma coluna que você pretende somar ou ordenar precisa do tipo numérico ou de data, porque texto é ordenado e somado como texto.

Uma etapa salva com uma coluna sem nenhum tipo ainda é executada. O tipo é determinado quando a etapa é iniciada, a partir da coluna de origem que essa coluna lê. Onde não há de onde lê-lo, ele é tratado como texto: as colunas de uma etapa Extrair SQL vêm da consulta que você escreveu, e não de uma origem mapeada, e onde várias origens têm o mesmo nome de coluna com tipos divergentes, usa-se texto em vez de adivinhar um deles — um palpite errado gera uma conversão que o data warehouse pode rejeitar, e qualquer coisa pode ser convertida em texto.

Definir o Tipo você mesmo continua sendo a forma de dizer o que uma coluna deve ser. Deixá-lo sem definição significa aceitar o tipo que a coluna de origem tiver.

Alteração da Ordem das Colunas

Para reorganizar as colunas na tabela de dados de destino, selecione as colunas desejadas. Você pode usar:

Setas de movimentação em massa: selecione a opção de movimentação desejada nas setas no canto superior direito
Menu de contexto: clique com o botão direito e selecione Mover para o início, Mover para cima, Mover para baixo ou Mover para o final.

Reduzir o Resultado a Registros Distintos

Para retornar apenas opções distintas, selecione a opção de menu Distintos. Isso exibe um conjunto de caixas de seleção para cada coluna da origem. Basta marcar a caixa ao lado da coluna correspondente para retornar apenas resultados distintos.

Dependendo da situação, talvez seja melhor considerar o uso de resumo.

O processo de distinção mantém o primeiro registro exclusivo encontrado e descarta os demais. Talvez você queira aplicar uma ordenação aos dados se a consistência entre execuções for importante.

Agregação e Agrupamento

Para agregar resultados, selecione a opção de menu Resumir. Isso exibe um conjunto de caixas de seleção para cada coluna da tabela de dados de destino. Escolha um método de resumo adequado para cada coluna.

Quando Inspecionar origem preenche as colunas, uma coluna numérica começa como Agrupar por em vez de Soma se o nome dela se parecer com um identificador, como id, customer_id, Order No ou CustomerKey, se a tabela dela a definir como chave ou se a junção a usar como chave.

Agrupar por
Soma
Mínimo
Máximo
Primeiro
Último
Contagem
Contagem (incluindo nulos)
Média
Desvio padrão
Desvio padrão amostral
Desvio padrão populacional
Variância
Variância amostral
Variância populacional
Avançado sem Agrupar por

Para uso avançado do Data Mapper, como expressões, limpeza e constantes, consulte Uso avançado do Data Mapper

Filtros de dados

Filtros de dados da tabela

Para oferecer o máximo de flexibilidade, há filtros de dados tanto nos dados de origem quanto nos dados de destino. Em conjuntos de dados maiores, filtrar linhas na origem pode ser especialmente vantajoso, pois as demais operações são executadas sobre um conjunto de dados menor.

Selecionar subconjunto de dados

Este tipo de filtro permite filtrar os dados de origem de entrada com base nas condições especificadas.

Aplicar filtro secundário aos dados de resultado

Este tipo de filtro permite aplicar um filtro aos dados de resultado já transformados, com base nas condições especificadas. Aplicar um filtro ao resultado transformado permite fazer exclusões com base em resultados de cálculos complexos, sumarizações ou funções de janela.

Divisão final da tabela de dados (limite)

O recurso de divisão de linhas permite limitar as linhas do conjunto de resultados com base em um intervalo e um ponto de partida.

Sintaxe de filtro

A sintaxe de filtro usa o Python SQLAlchemy, a mesma sintaxe das outras expressões.

Veja exemplos e funções de expressão na área Expressões.