Importar CSV

Descrição

Importa ficheiros de texto delimitado do PlaidCloud Document. 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 sem exemplos…

Parâmetros de importação

Import Source and Target

O seletor de ficheiros nesta transformação permite escolher um ficheiro guardado numa localização de documentos do PlaidCloud para importar.

Também pode escolher um diretório para importar, e todos os ficheiros nesse diretório serão importados como parte da execução da transformação.

Conta de origem

Escolha uma conta de documentos do PlaidCloud à qual tenha acesso. Isto permite-lhe selecionar um diretório ou ficheiro na seleção seguinte.

Dentro de um projeto, a lista oferece também Project Default no topo, que substitui a conta que o projeto tem atualmente definida como predefinida. Um novo passo pré-seleciona Project Default quando o projeto tem uma; um passo existente mantém a conta com que já tinha sido guardado até que a altere. Um passo deixado em Project Default é executado com a conta que for a predefinida do projeto nesse momento; se não existir nenhuma, a execução falha e indica o projeto, em vez de recorrer a outra conta.

Opção Pesquisar

A opção Pesquisar permite encontrar todos os ficheiros correspondentes abaixo de um caminho de diretório especificado para importar. Pode ser particularmente útil se for necessário incluir muitos ficheiros, mas estes estiverem guardados em diretórios aninhados ou misturados com outros ficheiros no mesmo diretório que não pretende importar.

O caminho de pesquisa selecionado é o diretório inicial onde a pesquisa é feita. O processo de pesquisa procura todos os ficheiros nesse diretório, bem como nos subdiretórios, que correspondam às condições de pesquisa especificadas. Certifique-se de que os critérios de pesquisa também se aplicam aos ficheiros nos subdiretórios.

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

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

Um assistente de IA ou a API REST também podem definir a pesquisa como glob, um padrão com carateres universais como CO Store*.yxdb comparado com o nome completo do ficheiro sem distinguir maiúsculas de minúsculas, ou como regex, uma expressão regular com a qual o nome completo do ficheiro tem de corresponder. Uma expressão regular distingue maiúsculas de minúsculas, a menos que comece por (?i).

Caminho do ficheiro de origem

Quando é necessário importar um ficheiro ou um diretório de ficheiros específico, escolher o ficheiro ou o diretório é melhor opção do que utilizar a pesquisa.

Para selecionar o ficheiro ou o diretório, basta utilizar o botão de procura para escolher o caminho da conta de documentos selecionada acima.

Substituição de variáveis

Tanto na opção de pesquisa como na opção de ficheiro/diretório específico, podem utilizar-se variáveis no caminho, no texto de pesquisa e nos nomes dos ficheiros.

Um exemplo que utiliza a variável current_month para apontar dinamicamente para o ficheiro correto:

legal_entity/inputs/{current_month}/ledger_values.csv

Tabela de destino

A seleção de destino das importações está limitada a tabelas, uma vez que as vistas não contêm dados subjacentes.

Opção dinâmica

A opção dinâmica permite especificar uma tabela através de texto, incluindo variáveis. É útil quando se utilizam fluxos de trabalho orientados por variáveis, em que as referências a tabelas e vistas são relativas às variáveis especificadas.

Um exemplo que utiliza 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 pretende uma tabela específica 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 na localização pretendida.

O Explorador de tabelas está sempre disponível com qualquer seleção de tabela. Clique no botão Explorador de tabelas à direita da seleção de tabela e abre-se uma janela do Explorador de tabelas.

Opção Remover carateres não ASCII

Ao selecionar esta opção, a importação remove todo o conteúdo que não seja ASCII. Embora o PlaidCloud suporte plenamente Unicode (UTF-8), os ficheiros do mundo real podem conter todo o tipo de codificações e carateres perdidos que dificultam o seu processamento.

Se se espera que o conteúdo do ficheiro seja apenas ASCII, selecionar esta caixa ajuda a garantir que o processo de importação decorre sem problemas.

Opção Eliminar ficheiros após a importação

Esta opção permite que o processo de importação elimine o ficheiro da conta de documentos do PlaidCloud depois de uma importação bem-sucedida.

Pode ser útil se os ficheiros de importação forem gerados e puderem ser recriados a partir de um sistema de registo, ou se não houver motivo para manter os ficheiros de entrada em bruto depois de processados.

Só são eliminados os ficheiros que foram importados. Um ficheiro que tenha sido ignorado ou que tenha produzido um aviso durante a importação permanece na pasta.

Opção Ignorar reimportação se os ficheiros de origem não tiverem sido alterados

Quando esta opção está ativada, uma execução do fluxo de trabalho deste passo ignora toda a importação (transferência, conversão e reconstrução da tabela) se os ficheiros de origem e as definições do passo não tiverem sido alterados desde a última execução bem-sucedida. Isto evita repetir o trabalho quando um fluxo de trabalho agendado é executado novamente sobre ficheiros de origem que não mudaram.

O passo compara cada ficheiro de origem pelo respetivo caminho, tamanho e hora da última modificação (e ainda por um hash do conteúdo, quando a origem o fornece). Se algum ficheiro for adicionado, removido ou alterado, ou se a configuração do passo mudar, a importação é executada normalmente. A opção está ativada por predefinição (desmarque-a para reimportar sempre) e as importações manuais e pontuais são sempre executadas.

Para ignorar a importação, é também necessário que a tabela de destino ainda contenha as linhas carregadas pela última importação. Se a tabela tiver sido entretanto esvaziada ou não for possível ler o respetivo número de linhas, a importação é executada novamente, em vez de ser ignorada e deixar os passos seguintes sem dados.

Algumas origens (por exemplo, SFTP) não fornecem um hash do conteúdo, pelo que, nesses casos, o sinal de alteração é apenas o tamanho e a hora da última modificação do ficheiro. Um ficheiro substituído no local com o mesmo tamanho e a mesma hora de modificação seria então tratado como inalterado e ignorado; desmarque esta opção num passo cuja origem possa ser atualizada dessa forma.

Inspecionar ficheiro de origem selecionado

Ao premir o botão Deduzir definições a partir do ficheiro de origem, o PlaidCloud abre o ficheiro e inspeciona-o para tentar determinar o formato dos dados. Verifique sempre as definições deduzidas para se certificar de que parecem corretas.

Um passo cujo ficheiro não produz colunas não pode ser guardado: a gravação é interrompida com Nenhuma coluna detetada. Quando o PlaidCloud não conseguiu ler o ficheiro, a mensagem indica o motivo, por exemplo uma extensão pouco habitual num ficheiro delimitado ou um caminho de ficheiro que utiliza uma variável de fluxo de trabalho que não está definida. Caso contrário, verifique se o delimitador e os carateres de aspas e de escape correspondem ao ficheiro, se este é um ficheiro de texto delimitado e se não está vazio.

Formato dos dados

Delimitador

Como referido acima, Inspect Source File tenta determinar o delimitador no ficheiro de origem. Se pretender outro delimitador, utilize esta secção para o especificar. Os utilizadores podem escolher numa lista de delimitadores padrão. Um passo sem delimitador definido utiliza uma vírgula.

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

Tipo de cabeçalho

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

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

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

Formato de data

Esta definição é útil se as datas contidas no ficheiro CSV não forem facilmente reconhecíveis como datas e horas. O processo de importação tenta converter as datas, mas ter um pouco mais de informação pode ajudar no processo de importação.

Um valor que o armazém não consiga ler com o formato indicado é guardado como vazio, em vez de interromper a importação, pelo que um formato que não corresponda ao ficheiro produz uma coluna de datas vazias e uma importação que, ainda assim, indica êxito. Depois de alterar esta definição, verifique a coluna importada antes de confiar no resultado.

Caracteres especiais

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

Carácter de aspas: o carácter utilizado para indicar um conjunto de texto delimitado que deve ser processado como um único campo. Quando não está definido, é uma aspa dupla (").
Carácter de escape: o carácter utilizado para indicar que o carácter seguinte deve ser processado tal como está e não interpretado como carácter especial. É útil quando um campo pode conter o delimitador. Quando não está definido, é uma barra invertida (\).
Carácter nulo: como os CSV não têm tipos de dados, este carácter permite indicar que o valor deve ser NULL em vez de uma cadeia vazia ou 0.
Campos vazios: um campo vazio é carregado como NULL em todos os lakehouses, tanto em colunas de texto como numéricas, pelo que um número em branco é NULL e não 0. Uma célula que contenha apenas espaços é carregada tal como está.
Negativos à direita: alguns sistemas de origem geram números negativos com o símbolo negativo no fim, em vez de o colocarem como prefixo. Esta definição processa-os como números negativos.

Seleção de linhas

Para ficheiros de entrada com registos estranhos, defina Ignorar linhas com o número de linhas a ignorar antes de processar os dados. É útil se os ficheiros contiverem blocos de cabeçalho que têm de ser ignorados antes de chegar aos dados tabulares.

As linhas ignoradas incluem as linhas em branco. Com um Tipo de cabeçalho Tem cabeçalho - usar cabeçalho e substituir lista de campos, o cabeçalho é lido a partir da primeira linha depois das linhas ignoradas, pelo que os dados são mapeados para as colunas de destino pelo nome do cabeçalho. Um ficheiro que contenha apenas as linhas ignoradas e um cabeçalho, sem linhas de dados, não importa nada e o passo conclui na mesma.

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, pelo que existem quatro linhas antes dele. Defina Ignorar linhas como 4 e Tipo de cabeçalho como Tem cabeçalho - usar cabeçalho e substituir lista de campos. A importação lê Company Code, Document Number, Posting Date e Amount como nomes das colunas, e a primeira linha de dados é a linha a seguir ao cabeçalho.

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

Definições adicionais

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

Codificação (encoding) — o codec de Python com que o ficheiro é lido, em vez de ser detetado. Os bytes que não descodificam 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 carateres. Selecione Vários delimitadores seguidos contam como um (combine_delimiters) para contar vários delimitadores seguidos como um.
Delimitador de linha (row_delimiter) — o texto que termina uma linha quando se encontra fora de aspas; uma quebra de linha noutro local passa então a fazer parte do valor. Se ficar em branco, qualquer quebra de linha termina 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 por e Termina com que são removidos onde quer que se encontrem fora de aspas; sem Termina com, um comentário prolonga-se até ao fim da linha.
Continuação de linha (line_continuation) — este texto antes de uma quebra de linha junta a linha à seguinte.
Aspa de fecho (quote_end) — a aspa que termina um valor entre aspas, quando difere do Carácter de aspas. Selecione Um valor entre aspas mantém as aspas (keep_quotes) para manter os carateres de 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

Table Data Mapper

O Data Mapper serve para mapear colunas dos dados de origem para a tabela de dados de destino.

Inspeção e preenchimento do mapeador

Utilizar 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. É o comportamento predefinido.
Preencher apenas a tabela de mapeamento de origem: mapeia apenas todos os valores da tabela de dados de origem. É útil ao modificar um fluxo de trabalho existente cuja estrutura de colunas de origem mudou.
Preencher apenas a tabela de mapeamento de destino: propaga todos os valores apenas para a tabela de dados de destino.

Se as opções de colunas de origem e de destino não forem suficientes, podem adicionar-se outras colunas à tabela de dados de destino de várias formas:

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

Eliminar colunas

Para eliminar colunas da tabela de dados de destino, selecione as colunas pretendidas, clique com o botão direito do rato e selecione Eliminar.

Colunas de origem que já não constam da lista

Uma linha de destino pode indicar uma Coluna de origem que a tabela de dados de origem já não lista, por exemplo depois de a origem ter sido inspecionada novamente. O passo nunca remove essa linha por si. Em vez disso, o nome da coluna é apresentado a vermelho, atrás de um sinal de aviso ⚠, e, ao passar o cursor por cima, é indicado que a coluna não consta das colunas de origem. Num passo com várias tabelas, como uma união, cada tabela é verificada em relação às suas próprias colunas de origem.

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

Ao guardar um passo que ainda tem linhas sinalizadas, uma caixa de diálogo Colunas obsoletas encontradas lista-as sob o separador ou a tabela em que se encontram e oferece três opções:

Remover todas e guardar: remove as linhas sinalizadas e depois guarda.
Guardar mesmo assim: guarda o passo tal como está.
Cancelar: volta ao passo sem guardar.

Para manter uma linha e eliminar o respetivo aviso, 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

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

Um passo guardado com uma coluna sem qualquer tipo é, mesmo assim, executado. O tipo é determinado quando o passo é iniciado, a partir da coluna de origem que essa coluna lê. Quando não há nada de onde o ler, é tratado como texto: as colunas de um passo Extrair SQL vêm da consulta que escreveu e não de uma origem mapeada e, quando várias origens têm o mesmo nome de coluna com tipos discordantes, é utilizado texto em vez de adivinhar um deles, porque um palpite errado produz uma conversão que o armazém pode rejeitar, e tudo se converte em texto.

Definir o Tipo manualmente continua a ser a forma de indicar o que uma coluna deve ser. Deixá-lo por definir significa aceitar o que a coluna de origem for.

Alterar a ordem das colunas

Para reordenar as colunas na tabela de dados de destino, selecione as colunas pretendidas. Pode utilizar:

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

Reduzir o resultado apenas a registos distintos

Para devolver apenas opções distintas, selecione a opção de menu Distinto. Isto apresenta um conjunto de caixas de verificação para cada coluna da origem. Basta marcar a caixa junto da coluna correspondente para devolver apenas resultados distintos.

Consoante a situação, pode ser preferível considerar a utilização da sumarização.

O processo de distinção mantém o primeiro registo único encontrado e descarta os restantes. Pode querer aplicar uma ordenação aos dados, se for importante para a consistência entre execuções.

Agregação e agrupamento

Para agregar resultados, selecione a opção de menu Resumir. Isto apresenta um conjunto de caixas de seleção para cada coluna da tabela de dados de destino. Escolha um método de sumarização 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 se assemelhar a um identificador, como id, customer_id, Order No ou CustomerKey, se a respetiva tabela a definir como chave ou se a junção a utilizar como chave.

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

Para uma utilização avançada do Data Mapper, como expressões, limpeza e constantes, consulte Utilização avançada do Data Mapper

Filtros de dados

Table Data Filters

Para permitir a máxima flexibilidade, existem filtros de dados disponíveis nos dados de origem e nos dados de destino. Em conjuntos de dados maiores, pode ser especialmente vantajoso filtrar linhas na origem, para que as restantes operações sejam executadas sobre um conjunto de dados mais pequeno.

Selecionar subconjunto de dados

Este tipo de filtro permite filtrar os dados de origem recebidos 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 depois de transformados, com base nas condições especificadas. A possibilidade de aplicar um filtro ao resultado transformado permite exclusões com base nos resultados de cálculos complexos, sumarizações ou funções de janela.

Divisão final da tabela de dados (limite)

A capacidade de divisão de linhas permite limitar as linhas do conjunto de resultados com base num intervalo e num ponto de partida.

Sintaxe de filtros

A sintaxe de filtros utiliza o Python SQLAlchemy, que é a mesma sintaxe das outras expressões.

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