> 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/rule-based-driver-events.md).

# Eventos de Motorista baseados em regras

Como a tabela de eventos do motorista baseada em regras transforma suas regras de alerta em registros de infração de condução e como consultá-la.

A transformação de eventos de motorista baseada em regras registra violações de condução como registros de eventos individuais, avaliados de acordo com as regras de alerta configuradas na sua conta. Cada linha em `processed_common_data.rule_based_driver_events` representa uma violação: qual regra a detectou, de que tipo ela era, quando e onde ocorreu e a que velocidade o veículo estava em movimento naquele momento.

Diferentemente da transformação baseada em gatilhos que ela substitui, esta é executada em uma programação fixa. Uma função de atualização reavalia uma janela de dados recentes a cada 15 minutos, então uma nova linha pode ter um atraso de até 15 minutos em relação ao evento no dispositivo.

{% hint style="info" %}

* Os limites de excesso de velocidade e de motor ocioso vêm das suas próprias regras de alerta, não dos padrões definidos para toda a plataforma. Dois dispositivos podem gerar eventos diferentes durante uma condução idêntica se regras diferentes forem aplicadas a eles.
* Eventos de hardware repetidos do mesmo tipo e do mesmo dispositivo em um intervalo de 10 segundos são agrupados em uma única linha, pois um dispositivo pode enviar vários sinais para um mesmo incidente.
* Os eventos baseados no Acelerômetro são ignorados enquanto o veículo está em movimento a menos de 3 km/h. Isso evita sinalizar vibrações causadas por carga ou estacionamento como uma violação.
* Todos os registros de data e hora são armazenados em UTC.
  {% endhint %}

## Tabela de saída: processed\_common\_data.rule\_based\_driver\_events

Cada linha representa uma infração detectada. A tabela é indexada por `device_id`, `device_time`, `rule_id`, e `hw_event_id`.

Várias colunas são cópias desnormalizadas de valores armazenados em outros lugares, portanto, as consultas mais comuns dos painéis não precisam de nenhuma junção: `object_label` vem do registro do objeto e `speed_limit`, `event_comment1` e `event_comment2` vêm da regra que gerou o evento.

<table><thead><tr><th width="180">Campo</th><th width="100">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>device_id</code></td><td>integer</td><td>Identificador do dispositivo.</td></tr><tr><td><code>object_id</code></td><td>integer</td><td>Identificador do Objeto (veículo ou ativo) associado ao dispositivo no momento do evento.</td></tr><tr><td><code>object_label</code></td><td>text</td><td>Nome legível do objeto. Já desnormalizado nesta tabela, portanto não é necessário fazer join com <code>raw_business_data.objects</code> é necessário.</td></tr><tr><td><code>device_time</code></td><td>timestamp</td><td>Data e hora do evento, em UTC.</td></tr><tr><td><code>rule_id</code></td><td>integer</td><td>A regra de alerta que gerou o evento. Faz referência a <code>raw_business_data.rules</code>. Definido como <code>0</code> para eventos <code>rpm_exceeded</code> , que não são acionados por regras. Consulte <a href="#how-rules-shape-the-output">Como as regras moldam a saída</a>.</td></tr><tr><td><code>event_type</code></td><td>text</td><td>Categoria da violação. Um de quatro valores. Consulte <a href="#violation-types">Tipos de violações</a> abaixo.</td></tr><tr><td><code>hw_event_id</code></td><td>integer</td><td>Código de evento de hardware para violações detectadas pelo Acelerômetro e pelo sensor. <code>0</code> para <code>speedup</code> e <code>idling_soft</code>, que são derivados, e não informados pelo dispositivo.</td></tr><tr><td><code>event_comment1</code></td><td>text</td><td>Rótulo de texto livre copiado da regra. Definido quando a regra foi configurada e útil para agrupar eventos por suas próprias categorias. Nulo para <code>rpm_exceeded</code>.</td></tr><tr><td><code>event_comment2</code></td><td>text</td><td>Segundo rótulo de texto livre copiado da regra. Nulo para <code>rpm_exceeded</code>.</td></tr><tr><td><code>speed_limit</code></td><td>integer</td><td>O limite configurado na regra, desnormalizado de <code>raw_business_data.rules</code>. Para <code>speedup</code> regras, este é o limite de velocidade em km/h; para <code>idling_soft</code> regras, é a tolerância de marcha lenta em minutos.</td></tr><tr><td><code>speed_kmh</code></td><td>numérico</td><td>Velocidade do veículo no momento do evento, em km/h.</td></tr><tr><td><code>duration_sec</code></td><td>integer</td><td>Duração da violação em segundos, para tipos de evento que abrangem um período de tempo, em vez de ocorrerem instantaneamente.</td></tr><tr><td><code>zone_id</code></td><td>integer</td><td>Geocerca em que o evento ocorreu, quando a regra se aplica a zonas específicas. Null quando a regra não tem zonas associadas e também quando está configurada para ser acionada fora dessas zonas. Consulte <a href="#zone-scoping">Escopo da zona</a>.</td></tr><tr><td><code>zone_label</code></td><td>text</td><td>Nome legível da geocerca, desnormalizado junto com <code>zone_id</code>.</td></tr><tr><td><code>latitude</code></td><td>double precision</td><td>Latitude em graus.</td></tr><tr><td><code>longitude</code></td><td>double precision</td><td>Longitude em graus.</td></tr><tr><td><code>extra_value</code></td><td>numérico</td><td>Medição dependente do contexto, definida para tipos de evento que registram uma leitura diferente da velocidade. Para <code>rpm_exceeded</code> eventos, a leitura de RPM que acionou o evento.</td></tr><tr><td><code>created_at</code></td><td>timestamp</td><td>Quando a linha foi gravada pela função de atualização. Posterior a <code>device_time</code> em até a duração de um ciclo de atualização.</td></tr></tbody></table>

### Tipos de violação

A tabela abaixo lista todos os tipos de violação registrados pela transformação, o valor exato de `event_type` valor armazenado para ele e de onde vem seu limite. Use o `event_type` valor da coluna diretamente ao filtrar ou agrupar consultas.

<table><thead><tr><th width="150">valor de event_type</th><th width="230">O que significa</th><th width="150">hw_event_id</th><th>Limite</th></tr></thead><tbody><tr><td><code>speedup</code></td><td>O veículo excedeu o limite de velocidade definido na regra</td><td><code>0</code></td><td>Por regra, em km/h</td></tr><tr><td><code>harsh_driving</code></td><td>Acelerômetro ou evento de hardware informado pelo dispositivo: aceleração brusca, frenagens, curvas, mudanças de faixa e violações do uso do cinto de segurança</td><td><code>900</code>, <code>931</code>, <code>987</code>–<code>991</code>, <code>996</code></td><td>Detectado pelo dispositivo. Ignorado abaixo de 3 km/h</td></tr><tr><td><code>Motor ocioso</code></td><td>Veículo parado com a ignição ligada por mais tempo do que o permitido pela regra</td><td><code>0</code></td><td>Por regra, em minutos</td></tr><tr><td><code>rpm_exceeded</code></td><td>RPM do motor acima do limite da plataforma</td><td><code>9002</code></td><td>Fixado em 5,000 RPM</td></tr></tbody></table>

{% hint style="warning" %}
O `event_type` valores e o `hw_event_id` numeração, diferem dos da tabela de eventos de desempenho do Motorista que esta transformação substitui. As consultas escritas para a tabela antiga precisam ter seus valores de filtro atualizados, não apenas o nome da tabela. Em particular, as violações de uso do cinto de segurança não têm mais um tipo de evento próprio: elas chegam como `harsh_driving` com `hw_event_id = 931`.
{% endhint %}

Os exemplos abaixo mostram padrões comuns de consulta. A consulta básica retorna violações recentes ordenadas por dispositivo e horário. A segunda adiciona a definição da regra por trás de cada evento. A terceira filtra apenas a condução agressiva detectada pelo hardware.

{% tabs %}
{% tab title="Consulta básica" %}
{% code overflow="wrap" expandable="true" %}

```sql
SELECT
    device_id,
    rótulo do objeto,
    device_time,
    event_type,
    speed_kmh,
    speed_limit,
    latitude,
    longitude
FROM processed_common_data.rule_based_driver_events
WHERE device_time >= CURRENT_DATE - INTERVAL '7 days'
ORDER BY device_id, device_time;
```

{% endcode %}
{% endtab %}

{% tab title="Com detalhes da regra" %}
{% code overflow="wrap" expandable="true" %}

```sql
SELECT
    e.device_id,
    e.object_label,
    e.device_time,
    e.event_type,
    e.speed_kmh,
    e.speed_limit,
    e.event_comment1,
    r.maximum AS rule_threshold
FROM processed_common_data.rule_based_driver_events e
LEFT JOIN raw_business_data.rules r
    ON r.rule_id = e.rule_id
WHERE e.device_time >= CURRENT_DATE - INTERVAL '7 days'
ORDER BY e.device_id, e.device_time;
```

{% endcode %}

Use a `LEFT JOIN` em vez de uma junção interna. `rpm_exceeded` eventos carregam `rule_id = 0` e não têm uma linha correspondente em `raw_business_data.rules`, então uma junção interna os descarta silenciosamente.
{% endtab %}

{% tab title="Somente Condução agressiva" %}
{% code overflow="wrap" expandable="true" %}

```sql
SELECT
    device_id,
    rótulo do objeto,
    device_time,
    hw_event_id,
    speed_kmh
FROM processed_common_data.rule_based_driver_events
WHERE event_type = 'harsh_driving'
  AND device_time >= CURRENT_DATE - INTERVAL '7 days'
ORDER BY device_id, device_time;
```

{% endcode %}

Filtragem em um único `event_type` o valor substitui o longo `IN` liste a tabela anterior necessária, já que todas as violações de acelerômetro e hardware agora compartilham uma categoria. Separe-as com `hw_event_id` quando você precisar da manobra individual.
{% endtab %}
{% endtabs %}

## Como as regras moldam os resultados

As linhas desta tabela não são geradas pela lógica de detecção de toda a plataforma. Com exceção de `rpm_exceeded`, todos os eventos são resultado de uma regra de alerta configurada na sua conta, e a regra determina tanto o limite quanto o escopo.

{% stepper %}
{% step %}

#### A regra define o limite

Cada regra armazena seu limite em `raw_business_data.rules.maximum`: uma velocidade em km/h para `speedup` regras, uma duração em minutos para `idling_soft` regras. A transformação copia esse valor para `speed_limit` em cada linha que ele grava, para que você possa ver com o que o veículo foi comparado sem precisar fazer uma junção com a regra.
{% endstep %}

{% step %}

#### A regra define o escopo

Uma regra se aplica aos objetos vinculados a ela por meio de `rules2objects`, e, opcionalmente, às geocercas vinculadas por meio de `rules2zones`. Um dispositivo que não esteja na lista de objetos de uma regra não gera eventos para essa regra, independentemente de como seja conduzido.
{% endstep %}

{% step %}

#### A regra fornece os próprios rótulos

`event_comment1` e `event_comment2` são campos de texto livre preenchidos quando a regra é configurada. Eles são copiados para cada evento, permitindo que os painéis exibam sua própria terminologia sem uma junção.
{% endstep %}

{% step %}

#### A função de atualização avalia a janela

A cada 15 minutos, `refresh_rule_based_driver_events` reexamina uma janela de 40 minutos de dados recentes e registra todos os eventos que atendem aos critérios. A janela é intencionalmente mais longa que o intervalo, para que os registros que chegam atrasados à plataforma ainda sejam capturados em uma execução posterior.
{% endstep %}

{% step %}

#### RPM é a exceção

`rpm_exceeded` os eventos não são orientados por regras. Eles usam um limite fixo de 5,000 RPM da plataforma, têm `rule_id = 0`, e não têm `event_comment1` ou `event_comment2` valores.
{% endstep %}
{% endstepper %}

### Escopo da zona

Quando uma regra tem geocercas associadas por meio de `rules2zones`, essas zonas determinam tanto se um evento é registrado quanto se `zone_id` é preenchido. A geometria das zonas é lida de `processed_common_data.zones_geom`, materializada a partir de `raw_business_data.zones`.

<table><thead><tr><th width="260">Configuração da regra</th><th width="200">Eventos registrados</th><th>Valor de zone_id</th></tr></thead><tbody><tr><td>Nenhuma zona associada</td><td>Em todos os lugares</td><td>Nulo</td></tr><tr><td>Zonas associadas, <code>zone_inverted = false</code></td><td>Somente dentro das zonas</td><td>A zona em que o evento ocorreu</td></tr><tr><td>Zonas associadas, <code>zone_inverted = true</code></td><td>Somente fora das zonas</td><td>Nulo</td></tr></tbody></table>

{% hint style="warning" %}
Um valor nulo de `zone_id` é ambíguo por si só: significa que a regra não tinha zonas ou que ela é acionada fora das zonas. Filtrar com `WHERE zone_id IS NULL` vai misturar os dois casos. Faça uma junção com `rules2zones` quando precisar distingui-los.
{% endhint %}

<details>

<summary>Constantes fixas da plataforma</summary>

Esses valores são iguais para todas as contas e não podem ser configurados por uma regra. Os limites definidos pelas regras são abordados em [Como as regras moldam os dados de saída](#how-rules-shape-the-output).

<table><thead><tr><th width="220">Constante</th><th width="160">Valor</th><th>Descrição</th></tr></thead><tbody><tr><td>Velocidade mínima para eventos do Acelerômetro</td><td>3 km/h</td><td>Violações baseadas no Acelerômetro abaixo dessa velocidade são ignoradas para evitar sinalizar vibrações quando o veículo está Estacionado ou sendo carregado.</td></tr><tr><td>Limite de RPM</td><td>5,000 RPM</td><td>A RPM do motor deve exceder esse valor para que um evento <code>rpm_exceeded</code> seja registrado.</td></tr><tr><td>Janela de deduplicação de hardware</td><td>10 segundos</td><td>Eventos de hardware repetidos do mesmo tipo e do mesmo dispositivo dentro dessa janela são agrupados em um só.</td></tr><tr><td>Intervalo de atualização</td><td>15 minutos</td><td>Com que frequência a função de atualização é executada.</td></tr><tr><td>Período retroativo da atualização</td><td>40 minutos</td><td>Até quanto tempo atrás cada execução reexamina os dados, para que registros recebidos com atraso não sejam ignorados.</td></tr></tbody></table>

</details>

## Personalizar a transformação

Para `speedup` e `idling_soft`, a personalização não exige nenhum fluxo de trabalho. Os dois limites são lidos da regra de alerta, portanto, ao alterar a regra, você altera o que a transformação registra a partir da próxima atualização. O mesmo se aplica ao escopo: ajuste os objetos ou as geocercas vinculados à regra para alterar quais veículos e áreas geram eventos.

{% hint style="warning" %}
A função de atualização que preenche `processed_common_data.rule_based_driver_events` não pode ser editado diretamente. Os limites que não são acionados por regras, como o limite inferior de 3 km/h do Acelerômetro ou o limite de 5,000 RPM, só podem ser alterados criando um fluxo de trabalho paralelo no Transformation Builder e agendando-o como uma transformação separada em `processed_custom_data`. Isso não altera a tabela descrita nesta página.
{% endhint %}

Se o seu cenário operacional exigir limites fixos diferentes, entre em contato com **<iotquery@navixy.com>** para solicitar o modelo de fluxo de trabalho correspondente. Depois de obtê-lo, carregue-o em [Criador de transformações](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md), ajuste os valores relevantes e agende o fluxo de trabalho modificado como uma transformação personalizada.

## Próximas etapas

* [**Transformações comuns**](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations.md): voltar ao índice de transformações.
* [**Viagens**](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations/trips.md): uma transformação relacionada que produz registros de trajetos de veículos a partir de dados telemáticos brutos.
* [**Agregação de dados do sensor**](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations/sensor-data-aggregation.md): Uma transformação irmã que agrega leituras do sensor em intervalos de tempo.
* [**Camada de dados brutos**](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/bronze-layer.md): Explorar `tracking_data_core`, `states`, e `inputs`, as tabelas de origem que alimentam os eventos de motorista baseados em regras.
* [**Criador de transformações**](https://navixy.com/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md): saiba como criar uma versão personalizada dessa transformação.
* [**Painel de Ranking de direção**](https://github.com/Navixy/navixy-iot-query-dashboard/blob/main/schemas/12-driver-performance-dashboard.md): usa eventos de motorista baseados em regras para avaliar a segurança na condução em toda a frota.
* [**Painel de impacto do comportamento**](https://github.com/Navixy/navixy-iot-query-dashboard/blob/main/schemas/13-behavior-impact-dashboard.md): usa eventos de motorista baseados em regras para acompanhar as tendências de comportamento ao longo do tempo.
* [**Painel de Segurança e segurança**](https://github.com/Navixy/navixy-iot-query-dashboard/blob/main/schemas/10-premium-safety-security-dashboard.md): usa eventos de motorista baseados em regras junto com dados de geocercas e trajetos.
* [**Painel de leasing**](https://github.com/Navixy/navixy-iot-query-dashboard/blob/main/schemas/06-leasing-dashboard.md): Usa consultas de Condução agressiva e detecção de marcha lenta de Eventos de motorista baseados em regras.


---

# 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/rule-based-driver-events.md?ask=<question>&goal=<user_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.
