> 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 do Motorista baseada em regras registra violações de Condução como registros de eventos individuais, avaliadas em relação às 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, que tipo era, quando e onde ocorreu e a que velocidade o veículo estava Em movimento no momento.

Ao contrário da transformação baseada em gatilho que ela substitui, esta é executada em um cronograma fixo. Uma função de atualização reavalia uma janela de dados recentes a cada 15 minutos, de modo que uma nova linha pode ficar até 15 minutos atrás do evento no dispositivo.

{% hint style="info" %}

* Os limites para excesso de velocidade e Motor ocioso vêm de suas próprias regras de alerta, não de padrões em toda a plataforma. Dois dispositivos podem produzir eventos diferentes a partir de Condução idêntica se regras diferentes se aplicarem a eles.
* Eventos de hardware repetidos do mesmo tipo, do mesmo dispositivo, dentro de 10 segundos são combinados em uma única linha, já que um dispositivo pode enviar vários sinais para um único incidente.
* Eventos baseados em Acelerômetro são ignorados enquanto o veículo estiver Em movimento abaixo de 3 km/h. Isso evita sinalizar vibração de carregamento ou estacionamento como uma violação.
* Todos os carimbos 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 violação detectada. A tabela tem como chave `device_id`, `device_time`, `rule_id`, e `hw_event_id`.

Várias colunas são cópias desnormalizadas de valores mantidos em outro lugar, então as consultas de painel mais comuns não precisam de junções nenhuma: `rótulo_do_objeto` vem do registro do Objeto, e `speed_limit`, `event_comment1`, e `event_comment2` vêm da regra que produziu 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>Objeto_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>rótulo_do_objeto</code></td><td>texto</td><td>Nome do Objeto legível para humanos. Já desnormalizado nesta tabela, então não é necessário fazer junção com <code>raw_business_data.objects</code> é necessário.</td></tr><tr><td><code>device_time</code></td><td>carimbo de data e hora</td><td>Carimbo de 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>. Defina como <code>0</code> para <code>rpm_exceeded</code> eventos, que não são orientados por regras. Veja <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>texto</td><td>Categoria de violação. Um dos quatro valores. Veja <a href="#violation-types">Tipos de violação</a> abaixo.</td></tr><tr><td><code>hw_event_id</code></td><td>integer</td><td>Código de evento de hardware para Acelerômetro e violações detectadas pelo sensor. <code>0</code> para <code>aceleração</code> e <code>Motor ocioso_soft</code>, que são derivadas em vez de relatadas pelo dispositivo.</td></tr><tr><td><code>event_comment1</code></td><td>texto</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>texto</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>aceleração</code> regras, este é o limite de velocidade em km/h; para <code>Motor ocioso_soft</code> regras, é a tolerância de marcha lenta em minutos.</td></tr><tr><td><code>speed_kmh</code></td><td>numeric</td><td>A 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 na qual o evento ocorreu, quando a regra está limitada a zonas específicas. Nulo quando a regra não tem zonas associadas e também quando a regra está configurada para disparar fora de suas zonas. Veja <a href="#zone-scoping">Escopo de zonas</a>.</td></tr><tr><td><code>zone_label</code></td><td>texto</td><td>Nome da Geocerca legível por humanos, 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>numeric</td><td>Medição dependente do contexto, definida para tipos de evento que registram uma leitura diferente de 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>carimbo de data e hora</td><td>Quando a linha foi gravada pela função de atualização. Até <code>device_time</code> com atraso de até a duração de um ciclo de atualização.</td></tr></tbody></table>

### Tipos de violação

A tabela abaixo lista cada tipo de violação que a transformação registra, o valor exato `event_type` 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>aceleração</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>condução agressiva</code></td><td>Acelerômetro ou evento de hardware relatado pelo dispositivo: aceleração brusca, frenagem, curvas, trocas de faixa e violações 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_soft</code></td><td>Veículo parado com a Ignição ligada por mais tempo do que a regra permite</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 a `hw_event_id` numeração, diferem da tabela de eventos de desempenho do Motorista que esta transformação substitui. As consultas escritas na tabela antiga precisam ter seus valores de filtro atualizados, não apenas o nome da tabela. Em particular, as violações de cinto de segurança já não têm seu próprio tipo de evento: elas chegam como `condução agressiva` 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 tempo. A segunda adiciona a definição da regra por trás de cada evento. A terceira filtra apenas a Condução agressiva detectada por hardware.

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

```sql
SELECT
    device_id,
    Objeto_label,
    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 um `LEFT JOIN` em vez de uma junção interna. `rpm_exceeded` os eventos contêm `rule_id = 0` e não têm nenhuma linha correspondente em `raw_business_data.rules`, então um inner join os descarta silenciosamente.
{% endtab %}

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

```sql
SELECT
    device_id,
    Objeto_label,
    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 %}

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

## Como as regras moldam a saída

As linhas desta tabela não são produzidas pela lógica de detecção em toda a plataforma. Com exceção de `rpm_exceeded`, cada evento é 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 o seu limite em `raw_business_data.rules.maximum`: uma velocidade em km/h para `aceleração` regras, uma duração em minutos para `Motor ocioso_soft` A transformação copia esse valor para `speed_limit` em cada linha que escreve, para que você veja com base em quê o veículo foi medido sem fazer join de volta 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 fora da lista de objetos da regra não gera eventos para essa regra, independentemente de como seja conduzido.
{% endstep %}

{% step %}

#### A regra fornece seus 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 para que os painéis possam exibir 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_Motorista_events` reexamina uma janela de 40 minutos de dados recentes e grava quaisquer eventos que se qualifiquem. A janela é deliberadamente maior que o intervalo, para que registros que chegam à plataforma com atraso ainda sejam capturados em uma passagem 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, carregam `rule_id = 0`, e não têm `event_comment1` ou `event_comment2` valores.
{% endstep %}
{% endstepper %}

### Escopo de zonas

Quando uma regra tiver geocercas anexadas por meio de `rules2zones`, essas zonas determinam tanto se um evento é registrado quanto se `zone_id` está preenchido. A geometria da zona é lida de `processed_common_data.zones_geom`, materializado 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>Sem zonas anexadas</td><td>Em todos os lugares</td><td>Nulo</td></tr><tr><td>Zonas anexadas, <code>zone_inverted = false</code></td><td>Apenas dentro das zonas</td><td>A zona em que o evento ocorreu</td></tr><tr><td>Zonas anexadas, <code>zone_inverted = true</code></td><td>Apenas fora das zonas</td><td>Nulo</td></tr></tbody></table>

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

<details>

<summary>Constantes fixas da plataforma</summary>

Esses valores são os mesmos para todas as contas e não são configuráveis por meio de uma regra. Os limiares definidos pela regra são tratados em [Como as regras moldam a 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>As violações baseadas no Acelerômetro abaixo dessa velocidade são ignoradas, para evitar marcar vibração enquanto estacionado ou carregando.</td></tr><tr><td>Limite de RPM</td><td>5,000 RPM</td><td>O RPM do motor deve exceder esse valor para que um <code>rpm_exceeded</code> evento seja registrado.</td></tr><tr><td>Janela de desduplicação de hardware</td><td>10 segundos</td><td>Eventos de hardware repetidos do mesmo tipo, do mesmo dispositivo, dentro dessa janela, são mesclados 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>Janela de retrospectiva da atualização</td><td>40 minutos</td><td>Até onde cada execução reexamina os dados, para que registros que cheguem atrasados não sejam perdidos.</td></tr></tbody></table>

</details>

## Personalizando a transformação

Para `aceleração` e `Motor ocioso_soft`, a personalização não requer um fluxo de trabalho nenhum. Ambos os limiares são lidos da Regra de alerta, então alterar a regra altera o que a transformação registra a partir da próxima atualização. O mesmo se aplica ao escopo: ajuste os objetos ou geocercas anexados à 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 editada diretamente. Limiares que não são definidos pela regra, como o limite mínimo do Acelerômetro de 3 km/h ou o limite de 5.000 RPM, só podem ser alterados criando um fluxo de trabalho paralelo no Construtor de transformações 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 precisar de limiares 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 [Transformation Builder](/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**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations.md): Voltar ao índice de transformações.
* [**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.
* [**Agregação de dados de sensores**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/common-transformations/sensor-data-aggregation.md): Uma transformação irmã que agrega leituras de sensores em intervalos de tempo.
* [**Camada de dados brutos**](/docs/analytics/pt-br/iot-query/schema-overview/bronze-layer.md): Explorar `tracking_data_core`, `estados`, e `entradas`, as tabelas de origem que alimentam eventos de Motorista baseados em regras.
* [**Transformation Builder**](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md): Aprenda como criar uma versão personalizada desta 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 pontuação de 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 rastrear 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 geocerca e trajeto.
* [**Painel de Leasing**](https://github.com/Navixy/navixy-iot-query-dashboard/blob/main/schemas/06-leasing-dashboard.md): Usa consultas de detecção de condução agressiva e 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.