> 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/common-transformations/sensor-data-aggregation.md). # Agregação de dados de sensores Processe leituras brutas de sensores IoT em registros agrupados por hora com calibração decodificada, cálculos de Volume de combustível e agregação no nível do dispositivo A transformação de agregação de dados de sensores reamostra leituras brutas de sensores em registros de resumo agrupados por período. Cada linha em `processed_common_data.sensors_data_by_hours` representa um sensor em um dispositivo para um bucket: o valor decodificado médio, mínimo e máximo e, para sensores de Combustível, o volume calibrado em cada um desses pontos. A transformação integrada é executada a cada hora e agrega a última hora de dados brutos de sensores de `raw_telematics_data.inputs` em intervalos de uma hora. Cada execução adiciona um novo conjunto de registros horários à tabela. {% hint style="info" %} Os dados nesta tabela podem estar com até 1 hora de atraso, refletindo a execução concluída mais recentemente.\ Todos os carimbos de data e hora são armazenados em UTC.\ Somente valores numéricos de sensores participam da agregação. Estados textuais, números negativos e notação científica são filtrados na origem. {% endhint %} ### Tabela de saída: processed\_common\_data.sensors\_data\_by\_hours Cada linha representa um intervalo de leituras agregadas para um sensor em um dispositivo. Na transformação integrada, cada intervalo abrange uma hora. A chave natural é `hour_bucket`, `device_id`, `sensor_name`, e `event_id`.
CampoTipoDescrição
hour_bucketcarimbo de data e horaInício do intervalo de tempo que a linha agrega. Na transformação nativa, sempre alinhado ao limite da hora em UTC. Em transformações personalizadas com um tamanho de intervalo diferente, este é o início do intervalo na granularidade escolhida (por exemplo, o início de uma janela de 5 minutos).
device_idintegerIdentificador do dispositivo. Para obter o rótulo do Objeto sem multiplicação de linhas, junte a raw_business_data.objects em device_id where is_deleted = false.
sensor_nametextoIdentificador da entrada bruta de raw_telematics_data.inputs. Corresponde a sensor_description.input_label quando um sensor está configurado.
event_idintegerIdentificador do tipo de evento para a leitura do sensor.
sensor_idintegerIdentificador da entidade do sensor de raw_business_data.sensor_description. Nulo se o sensor não estiver configurado.
input_labeltextoRótulo de entrada configurado de sensor_description. Corresponde a sensor_name quando presente.
sensor_labeltextoNome de sensor legível por humanos definido pelo usuário.
sensor_typetextoTipo de sensor, por exemplo nível_de_Combustível, temperatura, ignição.
sensor_unitstextoString de unidade inserida pelo usuário quando units_type está definido como personalizado. Vazio caso contrário.
units_typeintegerCódigo numérico para a categoria da unidade. Resolvido para uma string legível por humanos em sensor_description_units_type.
tipo_do_GrupointegerCódigo da regra de agregação para sensores agrupados: 0 para soma, 1 para média. Resolvido em sensor_description_tipo_de_Grupo.
value_avgfloatMédia do valor do sensor decodificado em todas as leituras no bucket.
value_minfloatValor decodificado mínimo no bucket.
value_maxfloatValor decodificado máximo no bucket.
val_low_avg, val_high_avg, vol_low_avg, vol_high_avgnumericPontos de calibração usados ao interpolar calibrated_volume_avg. Apenas sensores de Combustível; nulo caso contrário.
calibrated_volume_avgnumericVolume calibrado correspondente a value_avg, calculado por interpolação linear entre os pontos de calibração. Para sensores não relacionados a Combustível, isso é igual a value_avg.
val_low_min, val_high_min, vol_low_min, vol_high_min, calibrated_volume_minnumericPontos de calibração e volume interpolado para value_min.
val_low_max, val_high_max, vol_low_max, vol_high_max, calibrated_volume_maxnumericPontos de calibração e volume interpolado para value_max.
rótulo_do_objetotextoRótulo do Objeto de raw_business_data.objects. Pode aparecer várias vezes para o mesmo bucket se um dispositivo tiver sido atribuído a objetos historicamente.
sensor_description_units_typetextoCategoria de unidade legível para humanos resolvida a partir de units_type.
sensor_description_tipo_de_GrupotextoRegra de agrupamento legível para humanos resolvida a partir de tipo_do_Grupo.
sensor_units_finaltextoA string da unidade a ser exibida. É igual a sensor_units quando definido, caso contrário recorre a sensor_description_units_type.
value_titletextoRótulo legível para humanos para sensores discretos, consultado em parameters.value_titles usando value_max como chave. Nulo para Sensores de medida.
Os exemplos abaixo mostram padrões de consulta comuns. A primeira retorna agregados por hora dos últimos 7 dias. A segunda faz junção com `raw_business_data.objects` para incluir o rótulo do Objeto sem multiplicação de linhas. A terceira se concentra em sensores de Combustível e usa as colunas de volume calibrado. {% tabs %} {% tab title="Consulta horária básica" %} {% code overflow="wrap" expandable="true" %} ```sql SELECT device_id, hour_bucket, sensor_label, sensor_type, value_avg, value_min, value_max, sensor_units_final FROM processed_common_data.sensors_data_by_hours WHERE hour_bucket >= CURRENT_DATE - INTERVAL '7 days' ORDER BY device_id, hour_bucket, sensor_label; ``` {% endcode %} {% endtab %} {% tab title="Com rótulo de Objeto" %} {% code overflow="wrap" expandable="true" %} ```sql SELECT s.device_id, o.object_label, s.hour_bucket, s.sensor_label, s.value_avg, s.sensor_units_final FROM processed_common_data.sensors_data_by_hours s LEFT JOIN raw_business_data.objects o ON o.device_id = s.device_id AND o.is_deleted = false WHERE s.hour_bucket >= CURRENT_DATE - INTERVAL '7 days' ORDER BY s.device_id, s.hour_bucket, s.sensor_label; ``` {% endcode %} {% endtab %} {% tab title="Sensores de combustível com volume calibrado" %} {% code overflow="wrap" expandable="true" %} ```sql SELECT device_id, hour_bucket, sensor_label, value_avg AS raw_avg, calibrated_volume_avg AS volume_avg_litres, calibrated_volume_min AS volume_min_litres, calibrated_volume_max AS volume_max_litres FROM processed_common_data.sensors_data_by_hours ONDE sensor_type = 'fuel_level' AND hour_bucket >= CURRENT_DATE - INTERVAL '24 hours' ORDER BY device_id, hour_bucket; ``` {% endcode %} {% endtab %} {% endtabs %} ### Como os agregados de sensores são construídos Uma linha nesta tabela não é uma leitura bruta do dispositivo; ela é uma entidade derivada montada a partir de muitas leituras individuais de sensores. A transformação funciona sobre os dados brutos em etapas: decidir quais leituras são utilizáveis, juntar a configuração do sensor, decodificar o valor, agrupar em janelas de tempo, agregar, aplicar a calibração de Combustível e, por fim, enriquecer com rótulos legíveis por humanos. Entender esse processo ajuda você a interpretar os resultados corretamente e reconhecer quando o comportamento padrão precisa de ajustes para o seu caso de uso. Aqui estão as etapas do algoritmo que forma uma linha agregada de sensor: {% stepper %} {% step %} #### **Leitura e filtragem das entradas brutas** A transformação lê a fatia mais recente de dados de `raw_telematics_data.inputs`. O comprimento da fatia corresponde ao intervalo configurado: a execução integrada lê a última hora; uma execução personalizada com intervalo de 5 minutos lê os últimos 5 minutos. As leituras são filtradas antes de qualquer processamento adicional: * Apenas valores que correspondem à expressão regular `^[0-9]+\.?[0-9]*$` passam. Isso aceita inteiros e decimais não negativos. * Valores de texto, números negativos, notação científica e valores nulos são excluídos. * Sensores que emitem apenas dados não numéricos não aparecem na tabela de saída. O filtro atua sobre os dados brutos `valor` coluna em `entradas`, antes que qualquer decodificação seja aplicada. {% endstep %} {% step %} #### **Unindo a configuração do sensor** Cada leitura restante é comparada com `raw_business_data.sensor_description` usando um `LEFT JOIN` em `device_id` e `input_label = sensor_name`. A junção traz `sensor_id`, `sensor_label`, `sensor_type`, `units_type`, `tipo_do_Grupo`, `divider`, `multiplier`, `calibration_data`, e `parâmetros`. Como a junção é à esquerda, as leituras de sensores não configurados ainda passam com os metadados do sensor como null. {% endstep %} {% step %} #### **Decodificando o valor bruto** Cada leitura é convertida da sua representação armazenada para um valor numérico utilizável. A regra de decodificação vem de `sensor_description.parameters.calc_method`: * `bit_index` extrai um único bit do valor inteiro usando deslocamento de bits e máscara: `((raw_value::bigint >> bit_index) & 1)`. Usado para flags de status empacotadas em inteiros. * `identidade` usa o valor numérico bruto sem alterações. * Caso contrário, a função aplica `(raw_value / divider) * multiplier`, que é a fórmula padrão para Sensores de medida. Um divisor nulo aciona uma `COALESCE` alternativa ao valor bruto. {% endstep %} {% step %} #### **Agrupando e agregando** Os valores decodificados são agrupados em intervalos de tempo truncando `device_time` até o limite do intervalo. Dentro de cada intervalo, a função calcula `AVG`, `MIN`, e `MAX` do valor decodificado. O agrupamento também inclui colunas de metadados do sensor, então os agregados são calculados por sensor, por dispositivo e por intervalo. Na transformação integrada, o intervalo é de uma hora. Transformações personalizadas podem usar qualquer intervalo positivo. Veja [Personalizando a transformação](https://claude.ai/chat/32cacafe-fe34-476d-b7d0-c93b4ce82da6#customizing-the-transformation) abaixo. {% endstep %} {% step %} #### **Calibração para sensores de combustível** Sensores com uma `calibration_data` array preenchido (normalmente sensores de nível de Combustível) recebem interpolação linear aplicada a cada agregado. Para `value_avg`, `value_min`, e `value_max` separadamente, a função encontra os pontos de calibração imediatamente abaixo e acima do valor e, então, interpola linearmente para produzir `calibrated_volume_avg`, `calibrated_volume_min`, e `calibrated_volume_max`. Para sensores sem dados de calibração, os volumes calibrados são iguais aos agregados brutos. As colunas de ponto de quebra (`val_low_*`, `val_high_*`, `vol_low_*`, `vol_high_*`) são preservadas na saída para fins de transparência. {% endstep %} {% step %} #### **Enriquecimento com rótulos** As linhas agregadas são unidas com `raw_business_data.objects` em `device_id` para adicionar `rótulo_do_objeto`, e com `raw_business_data.description_parameters` duas vezes para resolver `units_type` e `tipo_do_Grupo` em strings descritivas legíveis por humanos. A função também calcula `sensor_units_final`, que prioriza o `sensor_units` e recorre à string de descrição. Para sensores discretos com um `parameters.value_titles` mapeamento, a função localiza o título legível por humanos correspondente a `value_max` e o retorna como `value_title`. Sensores de medida têm `value_title` definido como null. {% endstep %} {% endstepper %} As duas seções de referência a seguir contêm o parâmetro de intervalo configurável e as regras de decodificação que a transformação aplica internamente.
Parâmetro de intervalo A transformação é controlada por um único parâmetro, `p_interval`, que controla tanto o tamanho do intervalo quanto a janela de retrocesso. Os dois são sempre iguais: uma execução com `p_interval = '5 minutes'` lê os últimos 5 minutos de dados brutos e produz intervalos de 5 minutos. | Configuração | Transformação integrada | Transformação personalizada | | ----------------------- | ------------------------------------------------- | ------------------------------------------------------------------------------- | | Tamanho do bucket | 1 hora | Qualquer intervalo positivo definido no nó Custom SQL | | Janela de retrospectiva | 1 hora | Igual ao tamanho do bucket | | Cadência do agendamento | A cada hora (correspondendo ao tamanho do bucket) | Corresponda ao tamanho do bucket escolhido para cobertura contínua, sem lacunas | Veja [Personalizando a transformação](#customizing-the-transformation) para instruções sobre como alterar o intervalo.
Regras de decodificação de valores Os valores brutos do sensor chegam como texto em `raw_telematics_data.inputs.value`. A transformação aplica uma regra de decodificação com base na configuração de cada sensor antes de agregar. | `calc_method` | Comportamento de decodificação | | ----------------- | -------------------------------------------------------------------------------------------------------------- | | `bit_index` | Extrai um único bit: `((value::bigint >> bit_index) & 1)`. O `bit_index` é lido de `parâmetros`. | | `identidade` | Usa o valor bruto como um float, sem alterações. | | (padrão / nenhum) | Aplica `(raw_value / divider) * multiplier`. Um divisor nulo aciona uma `COALESCE` alternativa ao valor bruto. | A interpolação de calibração, aplicada após a agregação para sensores com dados de calibração, funciona encontrando os pontos de ruptura em `calibration_data` (um array JSONB de `{in, out}` entradas) mais próximas do valor agregado e interpolando linearmente entre elas. O resultado é armazenado nas `calibrated_volume_*` colunas.
### Personalizando a transformação A agregação padrão dos dados de sensor reflete a agregação horária de uso geral do Navixy. Se o seu cenário operacional exigir granularidade diferente, como resolução mais fina para painéis de diagnóstico ou intervalos mais grossos para relatórios de longo prazo, você pode criar uma transformação personalizada que chame `select_timeperiod_sensor_data` com um intervalo diferente e grave o resultado em sua própria tabela em `processed_custom_data`. A personalização é uma alteração de uma linha dentro de um nó Custom SQL: ```sql SELECT * FROM processed_common_data.select_timeperiod_sensor_data('5 minutes') ``` Altere o literal de intervalo para controlar tanto o tamanho do bucket quanto a janela de retrospectiva. A função retorna a mesma estrutura de colunas independentemente do intervalo, então a configuração do nó Output a jusante permanece simples. {% hint style="warning" %} O valor do intervalo controla o tamanho do bucket e a janela de retrospectiva juntos. Eles não podem ser definidos independentemente. O agendamento do fluxo de trabalho deve ser executado pelo menos com a mesma frequência que o intervalo; caso contrário, algumas leituras não serão agregadas. {% endhint %} #### Estrutura do fluxo de trabalho O fluxo de trabalho mínimo tem dois nós:
Nenhum `Dados brutos: telemetria` nó de origem é necessário. A função lê de `raw_telematics_data.inputs` e `raw_business_data` tabelas internamente. O nó Custom SQL contém todo o pipeline, e o nó Output materializa o resultado em sua tabela de destino. #### Exemplos de personalização Expanda as seções abaixo para ver exemplos de personalização baseados em casos.
Alterando o tamanho do bucket Use isto quando a granularidade horária for grossa demais para suas necessidades de relatório. Casos comuns incluem painéis que mostram tendências de Combustível com resolução de 5 minutos, diagnósticos segundo a segundo para trajetos curtos de teste e consolidações diárias para relatórios de longo prazo. Para alterar o tamanho do bucket, edite o literal de intervalo no nó Custom SQL e atualize o agendamento para corresponder. * **buckets de 5 minutos**, com agendamento `*/5 * * * *` (a cada 5 minutos): ```sql SELECT * FROM processed_common_data.select_timeperiod_sensor_data('5 minutes') ``` * **Intervalos de 15 minutos**, com agendamento `*/15 * * * *` (a cada 15 minutos): ```sql SELECT * FROM processed_common_data.select_timeperiod_sensor_data('15 minutes') ``` * **Intervalos diários**, com agendamento `5 0 * * *` (todos os dias às 00:05 UTC): ```sql SELECT * FROM processed_common_data.select_timeperiod_sensor_data('1 day') ``` A coluna de saída ainda se chama `hour_bucket` independentemente do intervalo. Se você quiser um nome mais claro na sua tabela personalizada, defina um alias em Custom SQL: ```sql SELECT hour_bucket AS bucket_time, device_id, sensor_name, event_id, sensor_id, input_label, sensor_label, sensor_type, sensor_units, units_type, group_type, value_avg, value_min, value_max, rótulo do objeto, unidades finais do sensor FROM processed_common_data.select_timeperiod_sensor_data('5 minutes') ``` Defina o do Nó de saída **Coluna de tempo** para `bucket_time` se você criar um alias, ou para `hour_bucket` se você mantiver o nome original.
Restringir-se a sensores específicos Use isto quando você precisar apenas de agregados para um subconjunto de sensores, por exemplo apenas nível de Combustível e temperatura do motor, para reduzir o tamanho da tabela e o custo da consulta. Envolva a chamada da função em um filtro `SELECT` dentro do Nó Custom SQL: ```sql SELECT * FROM processed_common_data.select_timeperiod_sensor_data('15 minutes') WHERE sensor_type IN ('fuel_level', 'temperature') ``` Você pode filtrar em qualquer coluna que a função retorne, incluindo `sensor_label`, `sensor_name`, ou `sensor_id`. Para encontrar os valores disponíveis em seus dados, consulte a tabela de origem: ```sql SELECT DISTINCT sensor_name FROM raw_telematics_data.inputs LIMIT 100; ```
Reduzindo a saída para colunas essenciais Use isto quando você não precisar dos pontos de calibração ou do sensor discreto `value_title` coluna, e você quer uma tabela de saída mais enxuta. Isso é especialmente útil quando sua frota não tem sensores de combustível, caso em que as 15 colunas relacionadas à calibração são todas nulas ou duplicatas das agregações brutas. Projete apenas as colunas de que você precisa: ```sql SELECT hour_bucket, device_id, sensor_name, event_id, sensor_label, sensor_type, value_avg, value_min, value_max, Objeto_label, sensor_units_final FROM processed_common_data.select_timeperiod_sensor_data('15 minutes') ``` A configuração do Nó de saída permanece a mesma; a tabela de destino simplesmente terá menos colunas.
#### Configuração do Nó de saída Depois que o Nó de SQL personalizado estiver configurado, conecte-o a um Nó de saída e configure a tabela de destino.
ParâmetroValor
Nome da tabelaUm nome descritivo, por exemplo sensors_data_by_5min
Coluna de tempohour_bucket (ou seu alias, se você o renomeou)
Chave primáriadevice_id, hour_bucket, sensor_name, event_id
Particionar porDATE(hour_bucket)
Modo de gravaçãoappend
A chave primária deve incluir todas as quatro colunas da chave natural da função. Usar apenas `device_id` e `hour_bucket` causará violações de chave primária, porque cada dispositivo tem vários sensores emitindo no mesmo bucket. `append` é o modo de gravação correto quando o Agendamento corresponde ao tamanho do bucket, porque cada execução produz novos buckets que nunca foram gravados antes. Use `upsert` somente se suas execuções se sobrepuserem (por exemplo, um intervalo de 15 minutos agendado a cada 5 minutos). #### Agendamento A cadência do agendamento deve ser igual ao valor do intervalo. Cada execução então lê exatamente o equivalente a um bucket de dados, sem sobreposição e sem lacuna. | Tamanho do bucket | Expressão de agendamento | Significado | | ----------------- | ------------------------ | -------------------------- | | 1 minuto | `* * * * *` | A cada minuto | | 5 minutos | `*/5 * * * *` | A cada 5 minutos | | 15 minutos | `*/15 * * * *` | A cada 15 minutos | | 1 hora | `0 * * * *` | A cada hora no minuto 00 | | 1 dia | `5 0 * * *` | Todos os dias às 00:05 UTC | Os horários estão em UTC. Faça a cadência do cron corresponder ao seu intervalo; executar com menos frequência do que o intervalo deixará lacunas na tabela de saída, e executar com mais frequência causará conflitos de chave primária duplicados em `append` modo. #### Usando o modelo de fluxo de trabalho Navixy fornece um modelo de fluxo de trabalho pronto que você pode carregar no Transformation Builder como ponto de partida. O modelo vem com o nó Custom SQL pré-configurado para intervalos de 5 minutos. Veja a [Modelos](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md) página para o download, as instruções de importação e a configuração do nó de saída para esta transformação. ### Próximas etapas * [**Transformações comuns**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations.md): Voltar ao índice de transformações. * [**Modelos**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder/templates.md): Baixe o modelo de fluxo de trabalho de agregação de dados do sensor e importe-o para o Transformation Builder. * [**Transformation Builder**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md): Saiba como trabalhar com o editor visual de fluxo de trabalho, adicionar nós e visualizar os resultados. * [**Camada de dados brutos**](/docs/analytics/pt-br/iot-query/schema-overview/bronze-layer.md): Explore as tabelas de origem que alimentam a agregação de dados do sensor: `raw_telematics_data.inputs`, `raw_business_data.sensor_description`, e `raw_business_data.objects`. * [**Viagens**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations/trips.md): Uma transformação irmã que produz registros de Trajeto de Veículos a partir de dados brutos de telemetria. --- # 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/common-transformations/sensor-data-aggregation.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.