Uso avançado do Data Mapper

Revisão

Antes de passar aos recursos avançados do Data Mapper, vale uma breve revisão da funcionalidade básica.

Configuração do Data Mapper

O Data Mapper é usado para mapear 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. É ú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 colunas 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, mesmo que já existissem.
Propagar selecionadas insere somente 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.

Alteração da ordem das colunas

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

Setas de movimentação em lote: 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 apenas a registros distintos

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

Agregação e agrupamento

Para agregar resultados, selecione a opção de menu Resumir. Isso exibirá 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.

O mapeador liga cada coluna de origem a uma coluna de destino — renomeando e convertendo tipos pelo caminho. As colunas de origem sem mapeamento ficam fora do resultado.

Uso avançado

Opções de agregação

Para agregar resultados, selecione a opção de menu Resumir. Isso exibirá um conjunto de caixas de seleção para cada coluna da tabela de dados de destino. Estão disponíveis as seguintes opções de resumo:

Função	Descrição
Agrupar por	Agrupa os resultados pelo valor
Contagem	Número de observações não nulas no grupo
Contagem (incluindo nulos)	Número de observações no grupo
Soma	Soma dos valores no grupo
Média	Média dos valores no grupo
Mediana	Mediana dos valores no grupo
Moda	Moda dos valores no grupo
Mín	Mínimo dos valores no grupo
Máx	Máximo dos valores no grupo
Primeiro	Primeiro valor do grupo, segundo a ordem de classificação
Último	Último valor do grupo, segundo a ordem de classificação
Desvio padrão	Desvio padrão não viesado no grupo
Desvio padrão amostral	Desvio padrão amostral no grupo
Desvio padrão populacional	Desvio padrão populacional no grupo
Variância	Variância não viesada no grupo
Variância amostral	Variância amostral no grupo
Variância populacional	Variância populacional no grupo
Avançado, sem agrupamento	Seleção especial de agregação ao usar funções de janela

Escolha o método de resumo adequado para a coluna.

Chaves de agregação para REST e assistentes de IA

Ao configurar uma etapa pela API REST ou por um assistente de IA, cada coluna de destino carrega seu resumo em agg, e o aggregation_type da etapa seleciona as mesmas opções. Toda etapa com um data mapper aceita estes valores:

Chave	Resumo
`group`	Agrupar por
`dont_group`	Avançado, sem agrupamento: a coluna não é agrupada nem agregada, para expressões que agregam ou usam janela por conta própria
`count`	Contagem de observações não nulas no grupo
`count_null`	Contagem incluindo nulos
`count_distinct`	Contagem de valores distintos no grupo
`sum`	Soma
`avg`	Média
`median`	Mediana
`min`	Mínimo
`max`	Máximo
`stddev`	Desvio padrão
`stddev_samp`	Desvio padrão amostral
`stddev_pop`	Desvio padrão populacional
`variance`	Variância
`var_samp`	Variância amostral

Ordenação de linhas

Cada coluna de destino pode ter um sort: asc, desc ou none, ou um objeto {ascending, order}. ascending é true ou false. order é um inteiro que define a prioridade da chave: as colunas com order são ordenadas primeiro, começando pelo menor número, e depois as demais colunas ordenadas seguem pela posição da coluna.

Ao usar uma função de janela, selecione Avançado, sem agrupamento como método de agregação. Essa seleção especial é necessária porque a função de janela já traz uma agregação inerente.

Constantes

Especificar um valor na coluna Constante substitui o valor da coluna de origem, se houver, e preenche a coluna com o valor constante especificado.

Origem, constante e expressão em conjunto

Uma coluna de destino obtém seu valor de qualquer um destes que você preencher, nesta ordem: uma Constante tem precedência, depois uma Expressão e, por último, a coluna de Origem.

Assim, uma coluna que calcula seu valor não precisa de Origem. Deixe-a em branco em uma constante ou em uma expressão — a constante ou a expressão já define qual é o valor, e uma Origem ao lado delas é ignorada. Preencha Origem quando estiver mapeando uma coluna diretamente dos dados de entrada, renomeando-a ou convertendo seu tipo pelo caminho.

Uma expressão lê as colunas de entrada pelo nome, com get_column(table, 'Column Name'), e não pela célula Origem.

Limpadores

O Data Mapper oferece um recurso prático de limpeza por apontar e clicar para aplicar conversões aos dados de uma coluna.

As operações de limpeza incluem as seguintes categorias:

Remoção de espaços do texto
Formatação de texto
Transformações de texto
Conversão de e para valores NULL
Formatação de números
Análise de datas

O resultado das seleções de limpeza é convertido em uma expressão consolidada, que pode ser vista nas informações da expressão.

Expressões

As expressões no Data Mapper estão entre os conceitos mais poderosos e flexíveis do PlaidCloud. Elas oferecem flexibilidade praticamente ilimitada e, ao mesmo tempo, desempenho excepcional, mesmo com volumes de dados extremamente grandes.

As expressões são escritas com a sintaxe do Python SQLAlchemy, junto com algumas funções auxiliares adicionais disponíveis no PlaidCloud. Isso permite que o PlaidCloud exponha diretamente o conjunto completo de recursos do data warehouse subjacente (por exemplo, Greenplum, SAP HANA, Redshift etc.). Além disso, há muitos recursos públicos que oferecem referências rápidas para o uso das operações do SQLAlchemy. Ao usar a sintaxe padrão do SQLAlchemy, o PlaidCloud evita a armadilha comum de criar mais uma sintaxe específica de domínio.

O editor de expressões é aberto com um clique duplo na célula de expressão da coluna. Depois de aberto, a lista de colunas é exibida à esquerda, enquanto uma extensa biblioteca de funções aparece à direita.

Embora seja perfeitamente possível digitar a expressão diretamente no editor, normalmente é mais fácil começar usando a seleção de funções e colunas por apontar e clicar. A biblioteca de funções inclui os seguintes grupos:

Condições
Condições específicas de coluna
Conversões
Datas
Matemática
Texto
Resumos
Operações de função de janela
Matrizes
JSON
PostGIS (geoespacial)
Trigonometria

Depois de concluir a expressão, salve-a para que seja aplicada à coluna.

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

Conversão para Float

cast(x, Float) retorna um número de precisão dupla de 64 bits em todos os data warehouses, de modo que um valor como 1225541207.71 mantém todos os dígitos. No StarRocks, a conversão para Float passa a ser aplicada, quando antes era ignorada, e no Databend a precisão passa a ser dupla em vez de simples. Uma coluna Float que o PlaidCloud cria a partir de dados de ponto flutuante também tem precisão dupla. Uma tabela que já tenha uma coluna de precisão simples passa a ter precisão dupla na próxima vez que uma etapa a recriar com Sobrescrever.

No StarRocks:

Uma conversão para inteiro grande comporta valores acima de cerca de 2,1 bilhões.
Uma conversão para Numeric sem precisão mantém as casas decimais, até 10 casas, em vez de arredondar para um número inteiro.
Uma conversão para JSON é aplicada.

Em todos os data warehouses, um valor que não pode ser convertido, como texto não numérico convertido para número, torna-se nulo em vez de interromper a etapa.

Leitura de outra tabela a partir de uma expressão

sqlalchemy.literal_column repassa um fragmento de SQL ao data warehouse sem alterações e aceita um único valor — uma coluna, um cálculo, um CASE, uma chamada de função, uma conversão, uma função de janela. Um literal_column que contenha uma subconsulta ((SELECT ... FROM ...)) é recusado, porque uma subconsulta alcança uma tabela que a etapa nunca declarou.

As regras desta seção valem onde quer que a expressão seja escrita — aqui no mapeador, no filtro de uma etapa e em uma consulta montada em outro lugar e enviada à plataforma. Elas são verificadas quando a etapa é salva e novamente quando a expressão é convertida em SQL.

Em vez disso, construa a subconsulta com sqlalchemy.select(...) — .scalar_subquery() quando precisar de um único valor em uma coluna, ou .subquery() quando for selecionar a partir dela:

# Refused
sqlalchemy.literal_column('(SELECT rate FROM fx WHERE fx.cc = t.cc)')

# Supported — a single value in a column
sqlalchemy.select(fx.c.rate).where(fx.c.cc == t.c.cc).scalar_subquery()

# Supported — a table to select from
sqlalchemy.select(fx.c.rate).subquery()

Coloque entre parênteses um OR de nível superior

Um literal_column cujo operador mais externo é OR também é recusado. O PlaidCloud repassa o texto sem alterações, de modo que uma condição adicionada depois dele se aplicaria a apenas metade — a OR b seguido de AND region = 'East' é lido como a OR (b AND region = 'East'), e as linhas que você pretendia excluir voltam no resultado.

Adicione parênteses e ele funciona como antes:

# Refused
sqlalchemy.literal_column("status = 'open' OR status = 'pending'")

# Supported
sqlalchemy.literal_column("(status = 'open' OR status = 'pending')")

Uma disjunção em qualquer ponto dentro da expressão — em um CASE, ou já entre parênteses — não é afetada.

XOR é recusado onde quer que apareça, com ou sem parênteses: os data warehouses divergem quanto à precedência dele, portanto não existe uma leitura segura em todos. Escreva-o por extenso, como (a AND NOT b) OR (NOT a AND b).

Um literal_column que contenha um comentário é recusado pelo mesmo motivo: um comentário vai até o fim da instrução, portanto apaga tudo o que o PlaidCloud adiciona depois da sua expressão, e não apenas o que você escreveu.

-- é recusado onde alcançaria o restante da instrução. # é recusado em qualquer ponto do texto, sem exceção — inclusive dentro de uma string entre aspas e inclusive os operadores de caminho JSON #> e #>> do Postgres:

# Refused
sqlalchemy.literal_column("attrs #> '{a,b}'")
sqlalchemy.literal_column("code || '#'")

O # abre um comentário em data warehouses compatíveis com MySQL, como o StarRocks, e o PlaidCloud não sabe qual data warehouse executará a expressão no momento em que você a escreve — portanto não existe posição no texto em que ele seja seguro de forma confiável, e um # que parece estar entre aspas para um mecanismo é o início de um comentário para outro. Se você precisa do caractere como dado, passe-o como valor:

# Supported
sqlalchemy.func.concat(table.code, sqlalchemy.literal('#'))

As mesmas duas grafias são recusadas em .op('...').

Todo o resto para o qual literal_column costuma ser usado não é afetado — literal_column('current_date'), literal_column("CASE WHEN amount > 0 THEN 'p' ELSE 'n' END") e func.count() funcionam como antes. Nomes de coluna que contêm espaços, pontos ou aspas também não são afetados; o data warehouse cuida das aspas para você.