> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md). # Construtor de transformações Crie transformações personalizadas do IoT Query com um editor visual de fluxo de trabalho. Configure nós SQL, visualize resultados, valide fluxos de trabalho e agende execuções {% hint style="info" %} #### Em breve! O Transformation Builder está atualmente em desenvolvimento. A descrição do recurso nesta página reflete a funcionalidade planejada. Os detalhes de implementação podem evoluir antes do lançamento final. Se você estiver interessado em acesso antecipado ou tiver dúvidas, entre em contato com . {% endhint %} ## O que é o Transformation Builder **Transformation Builder** é uma ferramenta visual para projetar fluxos de trabalho de transformação de dados sem a necessidade de desenvolver e manter pipelines de dados complexos. Você monta a lógica de processamento como um grafo em que cada etapa é representada por um bloco separado (Nó), e a ferramenta compila seu grafo em SQL executável. O Transformation Builder foi projetado para analistas, especialistas em BI e qualquer pessoa com conhecimento básico de SQL que queira controlar a lógica de preparação de dados de forma independente. Ele ajuda você a responder às principais perguntas da preparação de dados: de onde os dados vêm, como eles são combinados, quais filtros e transformações são aplicados, como as séries temporais são agregadas e em que formato os dados devem aparecer na [Camada de transformação](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer.md). O Transformation Builder não é um orquestrador de ETL completo nem uma plataforma de dados. É um designer de fluxo de trabalho focado que compila seu grafo de Nós em uma consulta SQL e uma função agendada do banco de dados. Modelos de fluxo de trabalho pré-criados para transformações comuns do Navixy estão disponíveis na [Modelos](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md) página. ## Como funciona Um fluxo de trabalho no Transformation Builder é um grafo direcionado de Nós organizado das fontes de dados até a saída:
workflow graph example showing sources, transformations, and output

Fontes de dados brutos → Nós de transformação → Saída

Cada Nó corresponde a uma etapa lógica de processamento. Você pode combinar várias fontes em um nó de transformação, e o resultado de um nó pode alimentar vários nós a jusante. O grafo fornece uma representação visual clara de todo o caminho dos dados, das tabelas de origem até a entidade analítica de destino. O Builder compila seu grafo em uma única consulta SQL usando Common Table Expressions (CTEs). Cada Nó se torna uma CTE na consulta final. Essa abordagem de compilação significa que o Builder não grava dados diretamente no banco de dados. Em vez disso, ele gera uma configuração que executa o processamento real de dados com base em uma agenda. {% hint style="warning" %} Os dados no grafo devem fluir em apenas uma direção. Ciclos não são permitidos. Se o Builder detectar um ciclo, ele retornará um erro de validação. {% endhint %} ### Conectando-se ao banco de dados Antes de começar a criar um fluxo de trabalho, você precisa se conectar ao seu banco de dados PostgreSQL. Sem uma conexão ativa, a prévia de dados e a descoberta de tabelas não estão disponíveis. O painel de conexão permite que você especifique seu [URL de conexão](/docs/analytics/pt-br/iot-query/connection-setup.md#connection-string-format), conecte ou desconecte e veja a quantidade de tabelas encontradas em cada categoria. O Builder usa dois esquemas no seu banco de dados: * `raw_telematics_data` para telemetria e dados de sensores do dispositivo * `raw_business_data` para dados de referência de negócios (Veículos, funcionários, geocercas e entidades semelhantes) Depois de conectado, o Builder descobre automaticamente as tabelas e colunas disponíveis, que você pode então selecionar ao configurar nós de fonte de dados.
connection panel showing URL input and discovered table counts
### Nós de fonte de dados Nós de fonte de dados definem de onde seu fluxo de trabalho lê os dados. Cada Nó de origem corresponde a uma tabela na camada de dados brutos.
Dados brutos: telemetria Este Nó carrega dados de séries temporais do `raw_telematics_data` esquema. | Parâmetro | Descrição | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | **Nome da tabela** | Selecione na lista de tabelas descobertas quando você se conectou ao banco de dados. | | **Coluna de tempo** | A coluna de timestamp usada para ordenação e filtros baseados em tempo. O padrão é `device_time`. | | **Colunas** | Lista de colunas específicas a incluir, ou `*` para selecionar todas as colunas. | | **Condição de filtro** | SQL opcional `WHERE` aplicada diretamente à consulta de origem. | | **Minutos da janela de tempo** | Limite de tempo opcional (em minutos) para restringir a janela de dados no SQL. Deixe em branco para não limitar. | Cada Nó de Dados brutos: telemetria lê exatamente de uma tabela. Para usar dados de várias tabelas, adicione um Nó separado para cada tabela.
Dados brutos: negócios Este Nó carrega dados de referência do `raw_business_data` schema. As tabelas típicas incluem `objetos`, `Veículos`, `dispositivos`, e `sensor_description`. | Parâmetro | Descrição | | ------------------ | -------------------------------------------------------------------------------- | | **Nome da tabela** | Selecione na lista de tabelas de negócio descobertas. | | **Coluna-chave** | A coluna-chave para esta tabela (por exemplo, `Objeto_id` ou `sensor_id`). | | **Colunas** | Lista de colunas específicas a incluir, ou `*` para selecionar todas as colunas. | Dados brutos: Os nós de negócio são usados principalmente como a segunda entrada para o Nó SQL Transform, permitindo que você associe dados de referência com séries temporais de telemetria.
### Nós de transformação Nós de transformação definem o que acontece com seus dados depois que eles são carregados das fontes. Cada tipo de transformação lida com um padrão específico de processamento.
Transformação SQL Combina dados de exatamente dois nós de origem usando SQL `JOIN` operação. | Parâmetro | Descrição | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Tipo de junção** | O tipo de junção: `INNER`, `LEFT`, `RIGHT`, ou `FULL` (full outer join). | | **Condição de junção** | A condição para corresponder linhas entre as duas entradas (por exemplo, correspondendo em `device_id`). | | **Selecionar colunas** | Lista de colunas a incluir na saída. Suporta notação de prefixo como `source.*` para selecionar todas as colunas de uma entrada específica. | SQL Transform requer exatamente duas entradas. As entradas podem ser qualquer combinação de nós de Fonte de Dados ou saídas de outros nós de transformação.
Filtro Filtra os dados por intervalo de tempo e condições personalizadas. Todas as condições são executadas no banco de dados como parte da `WHERE` cláusula (filtragem por pushdown). | Parâmetro | Descrição | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | **Coluna de tempo** | A coluna timestamp a ser usada para filtragem baseada em tempo. O padrão é `device_time`. | | **Início / fim do intervalo de tempo** | Limites inicial e final para o filtro de tempo. | | **Condições dinâmicas** | Uma lista de condições SQL combinadas com `AND`. Use estas para filtragem adicional além do intervalo de tempo. |
Reamostragem Agrega dados de séries temporais em intervalos de tempo fixos. Isso é útil para converter pontos de dados de alta frequência em estatísticas resumidas ao longo de períodos regulares. | Parâmetro | Descrição | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Coluna de tempo** | A coluna de timestamp a ser usada para agrupamento por intervalo. O padrão é `device_time`. | | **Interval** | O intervalo de agregação: `1min`, `5min`, `15min`, `1hour`, ou `1day`. | | **Grupo por** | Colunas adicionais para Grupo por (além do intervalo de tempo). | | **Agregações** | Uma lista de pares coluna-método que define como cada coluna é agregada. Métodos disponíveis: `média`, `soma`, `mín`, `máx`, `primeiro`, `último`, `contagem`. |
Aritmética Adiciona ou substitui colunas usando expressões SQL. Use este Nó para criar colunas calculadas com base nos dados existentes. | Parâmetro | Descrição | | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | **Expressões** | Uma lista de definições de expressão. Cada entrada inclui uma coluna de origem opcional, uma expressão SQL e um alias de saída obrigatório. | Por exemplo, para converter um valor de velocidade, você poderia definir a coluna de origem como `velocidade`, a expressão como `speed * 1.2`, e o alias como `speed_adjusted`. O alias é obrigatório para cada expressão.
SQL personalizado Oferece uma entrada SQL de forma livre para lógica complexa que os outros tipos de Nó não conseguem expressar. Use isto quando você precisar de controle total sobre a consulta. | Parâmetro | Descrição | | --------------------- | ------------------------------------------------------------------------------------ | | **SQL personalizado** | A `SELECT` consulta em que os nós anteriores são acessíveis por seus aliases de CTE. | Os aliases do Nó de origem seguem o padrão `a_` (por exemplo, `um_node_1`, `a_filter_1`"). Os identificadores de Nó são normalizados para identificadores SQL válidos, com espaços e caracteres especiais substituídos por sublinhados. Nós SQL personalizados aceitam uma ou duas entradas. Sua consulta pode referenciar os CTEs correspondentes por seus aliases.
### Configuração de saída
Saída O **Saída** O Nó define como os resultados da sua transformação devem ser gravados na camada Transformation. Ele especifica os metadados da tabela de destino que o runtime externo usa para armazenar os dados processados. | Parâmetro | Descrição | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Nome da tabela** | O nome da tabela de destino no `processed_custom_data` esquema. | | **Coluna de tempo** | A coluna de timestamp nos dados de saída (por exemplo, `device_time`). | | **Particionar por** | Uma expressão de particionamento para organizar os dados armazenados (por exemplo, `DATE(device_time)`). | | **Chave primária** | Uma lista de colunas que identificam exclusivamente cada linha (por exemplo, `[device_id, device_time]`). | | **Modo de gravação** | Como os dados são gravados na tabela de destino: `append` (adicionar novas linhas), `overwrite` (substituir os dados existentes), ou `upsert` (atualizar linhas existentes, inserir novas). |
## Criando um fluxo de trabalho Um fluxo de trabalho típico segue estas etapas: {% stepper %} {% step %} **Abrir o Transformation Builder** Abra a interface do Transformation Builder. {% endstep %} {% step %} **Conectar-se ao seu banco de dados** Insira a URL de conexão do PostgreSQL e estabeleça a conexão. O Builder descobre automaticamente as tabelas e colunas disponíveis. {% endstep %} {% step %} **Adicionar nós de Fonte de Dados** Adicione um [**Dados brutos: telemetria**](#raw-data-telematics) Nó e selecione a tabela e as colunas com as quais você quer trabalhar. Se precisar de dados de referência (por exemplo, detalhes do veículo ou descrições do sensor), adicione um [**Dados brutos: negócios**](#raw-data-business) Nó também. {% endstep %} {% step %} **Adicionar nós de transformação** Insira os nós de transformação que o seu fluxo de trabalho requer: * [**Transformação SQL**](#sql-transform) para unir dados * [**Filtro**](#filter) para restringir os resultados * [**Reamostragem**](#resampling) para agregar séries temporais * [**Aritmética**](#arithmetic) para adicionar colunas calculadas * [**SQL personalizado**](#custom-sql) para lógica complexa. {% endstep %} {% step %} **Configurar o Nó de saída** Adicione [Saída](#output) Nó e defina o nome da tabela de destino, as colunas da chave primária e o modo de gravação da sua entidade analítica. {% endstep %} {% step %} **Conectar nós** Desenhe arestas entre os nós para definir o fluxo de dados. Conecte os nós de origem aos nós de transformação, e os nós de transformação ao Nó de saída. Os dados fluem da esquerda para a direita, das fontes para a saída. {% endstep %} {% step %} **Revisar e corrigir erros** Verifique as dicas de validação para quaisquer problemas de configuração. Corrija erros nos parâmetros do Nó ou na estrutura do grafo conforme necessário. {% endstep %} {% step %} **Visualizar resultados** Clique em **Execute** para executar uma pré-visualização do seu fluxo de trabalho. O Builder compila o grafo em SQL e o executa no seu banco de dados, retornando até 100 linhas para que você possa verificar a saída. {% hint style="info" %} **Exportar** Você pode exportar seu fluxo de trabalho concluído como um arquivo YAML para execução em tempo de execução ou compartilhamento com colegas. Veja [Referência de YAML do fluxo de trabalho](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md) para detalhes do formato. {% endhint %} {% endstep %} {% step %} #### Agendar execução Clique em **Schedule** para abrir a caixa de diálogo de configuração, onde você pode definir o horário exato e a frequência da execução do fluxo de trabalho. No horário definido, uma função no banco de dados acionará o fluxo de trabalho e salvará seu resultado na camada de transformação. {% endstep %} {% endstepper %}
completed workflow graph with all node types connected

Exemplo completo do fluxo de transformação

### Pré-visualização dos resultados Depois que você clicar **Execute** na barra de ferramentas, o Builder compila o grafo do seu fluxo de trabalho em uma única consulta SQL com CTEs e a executa no banco de dados PostgreSQL conectado. Os resultados aparecem no painel inferior. **Em caso de execução bem-sucedida**, o painel exibe: * Uma tabela de resultados mostrando até 100 linhas de dados de saída * A consulta SQL executada (a consulta CTE completa gerada pelo compilador) * Contagem de linhas, contagem de colunas e tempo de execução * Opção para exportar o resultado para CSV **Em caso de erro de execução**, o painel exibe: * Uma mensagem de erro descrevendo o que deu errado * A consulta SQL executada (se a compilação tiver sido bem-sucedida) * Detalhes do erro do banco de dados (se o erro tiver ocorrido durante a execução da consulta) {% hint style="warning" %} A pré-visualização de resultados requer uma conexão PostgreSQL ativa. Sem uma conexão, a pré-visualização retorna um resultado vazio, sem executar SQL. A pré-visualização sempre usa dados reais do seu banco de dados, não dados simulados. {% endhint %}
Results preview panel showing successful execution with result table and SQL

Resultado do fluxo executado

## Validação e compilação O Builder valida seu fluxo de trabalho em dois níveis. 1. **Validação do grafo** verifica a estrutura geral do seu fluxo de trabalho. O grafo deve ser um grafo acíclico direcionado (DAG) válido, o que significa que os dados fluem em uma direção, sem ciclos. Se o Builder detectar um ciclo, ele retorna um erro e destaca os nós afetados. 2. **Validação do nó** verifica a configuração de cada nó individualmente. O Builder verifica se os campos obrigatórios estão preenchidos, se as colunas referenciadas existem na saída do nó anterior e se os parâmetros do nó são consistentes com seu tipo (por exemplo, SQL Transform deve ter exatamente duas entradas). Durante a compilação, o Builder converte seu grafo em uma única consulta SQL. Cada nó se torna uma CTE com o alias `a_`. Os nós são organizados em ordem topológica para que cada CTE possa referenciar as saídas de seus nós predecessores. Se a compilação falhar devido a um erro de configuração ou a uma estrutura de grafo inválida, o Builder retorna os detalhes do erro junto com qualquer SQL parcial que tenha conseguido gerar. ## Exportação ### Exportação e importação YAML Você pode exportar um fluxo de trabalho concluído como um arquivo YAML usando o **Exportar** botão na barra de ferramentas. O arquivo exportado contém a definição completa do fluxo de trabalho no formato da versão 2, incluindo todas as configurações dos nós, as arestas do grafo e as posições do layout. Para carregar um fluxo de trabalho salvo anteriormente, use a **Importar** função e selecione um arquivo `.yaml` ou `.yml` arquivo. Para a documentação completa do formato, consulte a [Referência de YAML do fluxo de trabalho](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md). ## Limitações atuais O Transformation Builder está atualmente em sua versão inicial, e várias restrições se aplicam: * **A pré-visualização requer uma conexão PostgreSQL ativa.** Sem uma conexão, você não pode visualizar resultados. A pré-visualização é limitada a 100 linhas. * **O grafo deve estar livre de ciclos.** Os dados fluem em apenas uma direção, das fontes para a saída. * **Sem mecanismo de execução embutido.** O Builder gera configuração e SQL para execução em runtime externa. Ele não processa nem armazena dados por conta própria. * **Apenas processamento em lotes.** O processamento de dados em streaming não é suportado. ## Próximas etapas * [**Modelos**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Configurações de fluxo de trabalho pré-criadas que você pode importar e adaptar no Transformation Builder. * [**Camada de transformação**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer.md): Aprenda como a camada Transformation organiza os dados processados em esquemas e como consultá-los. * [**Referência de YAML do fluxo de trabalho**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/workflow-yaml-reference.md): Revise a especificação completa para o formato de exportação e importação YAML. * [**Camada de dados brutos**](/docs/analytics/pt-br/iot-query/schema-overview/bronze-layer.md): Explore os esquemas de origem (`raw_telematics_data` e `raw_business_data`) que fornecem dados de entrada para seus fluxos de trabalho. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.