> 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/trips.md).

# Viagens

Registros de trajetos do veículo derivados de dados telemáticos brutos. Inclui horários de início e término, distância, estatísticas de velocidade e detecção de zona

A transformação Viagens processa dados telemáticos brutos em registros discretos de trajetos de veículos. Cada linha em `processed_common_data.Viagens` representa um Trajeto completo: onde começou e terminou, quanto tempo levou, quão longe o veículo percorreu e de quais zonas ele partiu ou em quais chegou.

A transformação integrada é executada a cada 8 horas e cobre uma janela deslizante de 12 horas de dados brutos. A cada execução, os registros calculados anteriormente para essa janela são substituídos por um novo cálculo, de modo que a tabela sempre reflita os dados mais recentes disponíveis.

{% hint style="info" %}

* Os dados nesta tabela podem ter até 8 horas de atraso, refletindo a execução concluída mais recentemente.
* Todos os carimbos de data e hora são armazenados em UTC.
  {% endhint %}

## Tabela de saída: processed\_common\_data.Viagens

Cada linha representa um Trajeto validado do veículo. A tabela é indexada por `device_id` e `Trajeto_start_time`.

<table><thead><tr><th width="215">Campo</th><th width="115">Tipo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>device_id</code></td><td>integer</td><td>Identificador do dispositivo. Para obter o rótulo do Objeto, faça join com <code>raw_business_data.objects</code> em <code>device_id</code> where <code>is_deleted = false</code> para evitar a multiplicação de linhas de atribuições históricas de dispositivos.</td></tr><tr><td><code>Trajeto_start_time</code></td><td>carimbo de data e hora</td><td>Momento em que o trajeto começou. Determinado pelo primeiro ponto de um novo segmento de Movimento após uma parada qualificada ou uma lacuna de dados.</td></tr><tr><td><code>Trajeto_hora_fim</code></td><td>carimbo de data e hora</td><td>Tempo em que o Trajeto terminou. Definido como o momento em que o dispositivo transitou de Em movimento para uma parada que durou pelo menos 5 minutos.</td></tr><tr><td><code>duração do Trajeto</code></td><td>texto</td><td>Duração do trajeto formatada como <code>HH:MI:SS</code>.</td></tr><tr><td><code>Trajeto_duration_seconds</code></td><td>numeric</td><td>Duração do Trajeto em segundos. Use este campo para cálculos aritméticos.</td></tr><tr><td><code>Trajeto_distancia_metros</code></td><td>numeric</td><td>Distância total do Trajeto em metros, calculada a partir da geometria de linha do PostGIS construída com todos os pontos do Trajeto.</td></tr><tr><td><code>avg_speed</code></td><td>numeric</td><td>Velocidade média em todos os pontos do Trajeto, em km/h.</td></tr><tr><td><code>max_speed</code></td><td>numeric</td><td>Velocidade máxima registrada durante o Trajeto, em km/h.</td></tr><tr><td><code>min_speed</code></td><td>numeric</td><td>Velocidade mínima registrada durante o Trajeto, em km/h.</td></tr><tr><td><code>latitude_start</code></td><td>numeric</td><td>Latitude do primeiro ponto do Trajeto, em graus.</td></tr><tr><td><code>longitude_start</code></td><td>numeric</td><td>Longitude do primeiro ponto do Trajeto, em graus.</td></tr><tr><td><code>altitude_start</code></td><td>numeric</td><td>Altitude no início do Trajeto, em metros acima do nível do mar.</td></tr><tr><td><code>latitude_end</code></td><td>numeric</td><td>Latitude do último ponto do Trajeto, em graus.</td></tr><tr><td><code>longitude_end</code></td><td>numeric</td><td>Longitude do último ponto do Trajeto, em graus.</td></tr><tr><td><code>altitude_end</code></td><td>numeric</td><td>Altitude ao final do Trajeto, em metros acima do nível do mar.</td></tr><tr><td><code>points_in_Trajeto</code></td><td>integer</td><td>Número de pontos brutos de telemetria incluídos no Trajeto. Mínimo 2 para um Trajeto válido.</td></tr><tr><td><code>start_zone</code></td><td>texto</td><td>Nome da zona de Geocerca que contém o ponto de início do Trajeto, se houver. Nulo se o ponto de início não estiver dentro de uma zona definida.</td></tr><tr><td><code>end_zone</code></td><td>texto</td><td>Nome da zona de Geocerca que contém o ponto final do Trajeto, se houver. Null se o ponto final não estiver dentro de uma zona definida.</td></tr></tbody></table>

Os exemplos abaixo mostram padrões comuns de consulta. A consulta básica retorna registros de Trajeto dos últimos 7 dias ordenados por dispositivo e horário de início. O segundo exemplo faz join com `raw_business_data.objects` para incluir o rótulo legível do Objeto ao lado de cada Trajeto.

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

```sql
SELECT
    device_id,
    Trajeto_start_time,
    Trajeto_end_time,
    duracao_do_trajeto,
    Trajeto_distancia_metros,
    avg_speed,
    start_zone,
    end_zone
FROM processed_common_data.Viagens
WHERE trip_start_time >= CURRENT_DATE - INTERVAL '7 days'
ORDER BY device_id, trip_start_time;
```

{% endcode %}
{% endtab %}

{% tab title="Com rótulo de Objeto" %}
{% code overflow="wrap" expandable="true" %}

```sql
SELECT
    t.device_id,
    o.object_label,
    t.trip_start_time,
    t.trip_end_time,
    t.trip_distance_meters,
    t.avg_speed,
    t.start_zone,
    t.end_zone
FROM processed_common_data.trips t
LEFT JOIN raw_business_data.objects o ON o.device_id = t.device_id
WHERE t.trip_start_time >= CURRENT_DATE - INTERVAL '7 days'
ORDER BY t.device_id, t.trip_start_time;
```

{% endcode %}
{% endtab %}
{% endtabs %}

## Como as Viagens são criadas

Um registro de Trajeto não é uma leitura bruta do dispositivo, ele é uma entidade derivada montada a partir de centenas\
de pontos telemáticos individuais. A transformação trabalha com os dados brutos em etapas:\
primeiro decidindo quais pontos vale a pena manter, depois classificando o status de Movimento de cada ponto,\
então agrupando pontos em segmentos de Trajeto e, por fim, calculando as métricas agregadas que\
aparecem na tabela de saída. Entender esse processo ajuda você a interpretar os resultados corretamente\
e reconhecer quando as configurações padrão precisam ser ajustadas para a sua Frota.

Aqui estão as etapas do algoritmo que forma um registro de Trajeto:

{% stepper %}
{% step %}

#### **Coletando e limpando a entrada**

A transformação lê as últimas 12 horas de dados de duas tabelas de origem:

* `tracking_data_core` para leituras de posição e movimento
* `estados` para o sinalizador de Movimento de hardware que cada rastreador envia

Os pontos são filtrados antes de qualquer processamento adicional:

* Registros com coordenadas zero são descartados.
* Pontos com menos de 3 satélites são excluídos do conjunto GNSS.
* Pontos LBS (`satellites = -1`) são a exceção: eles passam por tratamento separado na próxima etapa, pois as posições das torres de celular exigem verificações de validade diferentes antes de poderem participar da detecção de Trajeto.
  {% endstep %}

{% step %}

#### **Decidindo se cada ponto representa Movimento**

Cada ponto é classificado em um dos três status:

* `Em movimento`: a velocidade está igual ou acima de 3 km/h, e ou a distância do ponto anterior excede 50 metros ou a flag de Movimento do hardware do rastreador está ativa. Ambas as condições evitam falsos positivos: a verificação de distância filtra picos de velocidade, e a flag de hardware captura um Movimento genuíno em baixa velocidade que a distância sozinha não detectaria.
* `Parado`: a velocidade está abaixo do limite ou a distância é insuficiente.
* `Estacionado`: nenhuma leitura de velocidade está disponível para este ponto.

Os pontos LBS passam por uma verificação adicional antes de receber um status. Qualquer ponto LBS em que a velocidade calculada entre posições consecutivas exceda 200 km/h é descartado como um artefato de posicionamento. Um ponto LBS que passa por essa verificação e vem imediatamente após um ponto GNSS pode formar seu próprio segmento de trajeto de um único ponto, cobrindo casos em que um dispositivo faz a transição de posicionamento por satélite para posicionamento por torre de celular no meio do trajeto. Todos os outros pontos LBS inválidos são removidos.
{% endstep %}

{% step %}

#### Agrupando pontos em Viagens

Com cada ponto carregando um status de Movimento, a transformação identifica limites de Trajeto. Um novo Trajeto começa quando:

* O dispositivo produz seu primeiro ponto de dados na janela de processamento.
* Movimento é retomado após uma parada qualificada (duração mínima de Estacionado excedida).
* Movimento é retomado após uma lacuna de dados (tempo limite excedido).

Um Trajeto termina quando:

* O dispositivo esteve Parado continuamente pelo tempo mínimo de estacionamento.
* Uma lacuna de dados do tempo limite ocorre enquanto o dispositivo não está Em movimento.

Os limiares que controlam esses limites estão listados na [Parâmetros de configuração](#configuration-parameters) referência abaixo.
{% endstep %}

{% step %}

#### Calculando métricas de saída

Uma vez que os limites do Trajeto são estabelecidos, todos os pontos em cada Trajeto são agregados em uma única linha de saída:

* `Trajeto_distancia_metros`: derivado de uma geometria de linha do PostGIS construída a partir da sequência ordenada de pontos usando `ST_MakeLine`.
* `avg_speed`, `max_speed`, `min_speed`: calculado com base em todos os pontos do Trajeto.
* `latitude_start`, `longitude_start`, `latitude_end`, `longitude_end`: obtido a partir dos primeiros e últimos pontos na sequência.
* `start_zone`, `end_zone`: preenchido ao comparar as coordenadas inicial e final com `processed_common_data.zones_geom`. Uma correspondência exige que o ponto esteja exatamente dentro do limite da zona; nenhum buffer é aplicado.
  {% endstep %}

{% step %}

#### Filtrando ruído antes de gravar os resultados

Nem todo segmento do Trajeto que o algoritmo identifica vale a pena manter. Segmentos curtos causados por breve recuperação do GPS, dispositivos parados com desvio ocasional de posição ou dados incompletos no limite da janela são descartados. Um Trajeto só é gravado na tabela de saída quando atende simultaneamente a todas as seguintes condições:

| Condição                      | Limite                          |
| ----------------------------- | ------------------------------- |
| Pontos no Trajeto             | Pelo menos 2                    |
| Velocidade máxima registrada  | Pelo menos 3 km/h               |
| Distância total do Trajeto    | Pelo menos 100 metros           |
| Horário de início do Trajeto  | Deve ser determinado (não nulo) |
| Horário de término do Trajeto | Deve ser determinado (não nulo) |
| {% endstep %}                 |                                 |
| {% endstepper %}              |                                 |

As duas seções de referência a seguir contêm os parâmetros configuráveis e as regras de escala dos dados brutos\
que a transformação aplica internamente.

<details>

<summary>Parâmetros de configuração</summary>

Estes limites determinam como as Viagens são divididas e validadas. Eles são os alvos mais comuns de personalização. Consulte [Personalizando a transformação](#customizing-the-transformation) para obter instruções sobre como ajustá-los no modelo de fluxo de trabalho.

<table><thead><tr><th width="233">Parâmetro</th><th width="133">Valor padrão</th><th>Descrição</th></tr></thead><tbody><tr><td>Duração mínima de estacionamento</td><td>300 segundos (5 minutos)</td><td>Uma parada mais curta do que isso não encerra o Trajeto atual. Considera-se que o dispositivo ainda está na mesma jornada.</td></tr><tr><td>Tempo limite de lacuna de dados</td><td>1200 segundos (20 minutos)</td><td>Se nenhum dado chegar durante essa duração, o Trajeto atual termina e um novo começa quando os dados são retomados.</td></tr><tr><td>Distância mínima de Movimento</td><td>50 metros</td><td>Um ponto deve estar pelo menos a esta distância do ponto anterior para ser considerado Movimento.</td></tr><tr><td>Velocidade mínima de Movimento</td><td>3 km/h</td><td>Pontos abaixo desta velocidade não são classificados como Em movimento.</td></tr></tbody></table>

</details>

<details>

<summary>Escala de valores brutos</summary>

Dados telemáticos brutos de `tracking_data_core` armazena valores de coordenadas e velocidade como números inteiros para armazenamento eficiente. A transformação os converte em unidades padrão antes do processamento.

| Campo                   | Divisor          | Resultado                                   |
| ----------------------- | ---------------- | ------------------------------------------- |
| `latitude`, `longitude` | 10,000,000 (1e7) | Graus (por exemplo, 554567890 → 55.456789°) |
| `altitude`              | 10,000,000 (1e7) | Metros acima do nível do mar                |
| `velocidade`            | 100 (1e2)        | km/h (por exemplo, 6530 → 65.30 km/h)       |

</details>

## Personalizando a transformação

A transformação padrão de Viagens reflete a lógica de detecção de Trajeto de uso geral da Navixy. Se o seu cenário operacional exigir um comportamento diferente, você poderá carregar o modelo de fluxo de trabalho em [Transformation Builder](/docs/analytics/pt-br/iot-query/schema-overview/transformation-layer/transformation-builder.md), modificar os Nós relevantes e agendar o fluxo de trabalho ajustado como uma transformação personalizada em `processed_custom_data`.

{% hint style="warning" %}
Vários Nós no fluxo de trabalho de Viagens usam funções de geometria PostGIS e funções de janela (`LAG`, `FIRST_VALUE`, `LAST_VALUE`, `SUM OVER`). A modificação desses Nós exige conhecimento sólido de SQL. Sempre visualize o resultado usando o botão **Execute** no Transformation Builder antes de agendar um fluxo de trabalho modificado.
{% endhint %}

### Exemplos de personalização

Expanda as seções abaixo para ver alguns exemplos de personalização baseados em casos.

<details>

<summary>Ajustar limites de parada e lacuna</summary>

Use isto quando o limite padrão de estacionamento de 5 minutos divide o que deveria ser um Trajeto contínuo em vários registros — algo comum em rotas de entrega urbanas com paradas curtas frequentes. Esse ajuste também ajuda quando os dispositivos têm intervalos de reporte irregulares e o tempo limite de lacuna de 20 minutos encerra as Viagens prematuramente.

Os valores de limite são codificados como constantes inteiras em dois Nós Custom SQL:

1. Abra o **Sinalizadores de Trajeto** Nó (`custom_9`). Encontre a condição `parking_duration >= 300 * INTERVAL '1 second'`. Isso aparece duas vezes no nó. Substitua `300` pelo seu valor-alvo em segundos nos dois lugares. Por exemplo, para exigir uma parada de 10 minutos, use `600`.
2. No mesmo **Sinalizadores de Trajeto** Nó (`custom_9`), encontre `time_diff >= 1200`. Em seguida, abra o **Marcadores de estacionamento** Nó (`custom_6`) e encontre a mesma condição lá. Substitua `1200` pelo seu valor-alvo em segundos em ambos os nós. Por exemplo, para tolerar intervalos de 30 minutos, use `1800`.
3. Clique em **Execute** para visualizar o resultado e confirmar que os limites do trajeto correspondem às suas expectativas operacionais antes do agendamento.

</details>

<details>

<summary>Ativando a filtragem de LBS baseada em distância</summary>

Use isto quando a sua frota opera em áreas com cobertura ruim de GPS e pontos de LBS estão introduzindo grandes saltos de coordenadas — por exemplo, um dispositivo perdendo o sinal de satélite e saltando para uma torre de celular a vários quilômetros de distância. Excluir esses pontos produz uma geometria de trajeto mais limpa e cálculos de distância mais precisos.

O modelo de fluxo de trabalho inclui um espaço reservado para essa verificação no **LBS Processado** Nó (`custom_3`, mas ele está inativo por padrão. A `distance_status` coluna está codificada para sempre retornar `'VALID'` por meio da expressão provisória `CASE WHEN 1 != 1 THEN 'EXCLUDED_DISTANCE' ELSE 'VALID' END`. Para ativá-la:

1. Abra o **LBS Processado** nó de SQL personalizado (`custom_3`) no Transformation Builder.
2. Substitua a linha stub por uma condição real baseada em `distance_meters`. Por exemplo, para excluir pontos de LBS a mais de 500 metros do ponto anterior:

```sql
   CASE
       WHEN point_type = 'LBS' AND distance_meters > 500
       THEN 'EXCLUDED_DISTANCE'
       ELSE 'VALID'
   END AS distance_status,
```

Um limite entre 200 e 1000 metros é uma faixa inicial razoável — use um valor menor em áreas com cobertura densa de torres de celular, maior onde as torres são escassas.

3. Clique em **Execute** para visualizar o resultado. Verifique quantos pontos de LBS agora estão excluídos e se os trajetos restantes parecem corretos. Ajuste o limite, se necessário, antes do agendamento.

</details>

<details>

<summary>Excluindo pontos de LBS por completo</summary>

Use isto quando a sua frota usa dispositivos somente com GPS que nunca produzem leituras de LBS, ou quando você quer registros de trajeto construídos exclusivamente a partir de posições GNSS confirmadas.

1. Abra o **Dados principais** nó de origem (`telematics_1`, tipo: Dados brutos: Telemática). No **Condição de filtro** campo, remova `OR satellites = -1` da verificação de satélites, alterando:

```
   event_id IN (2, 802, 803, 804, 811) AND latitude <> 0 AND longitude <> 0
   AND (satellites >= 3 OR satellites = -1)
```

para:

```
   event_id IN (2, 802, 803, 804, 811) AND latitude <> 0 AND longitude <> 0
   AND satellites >= 3
```

2. Exclua o **LBS Processado** Nó (`custom_3`) e o **LBS filtrados** Nó (`custom_4`) do grafo, juntamente com todas as arestas conectadas a eles. Desenhe uma nova aresta a partir do **Com distância** Nó (`custom_2`) para o **Filtrar inválidos** Nó (`filter_1`) para restaurar o fluxo de dados.
3. Abra o **Filtrar inválidos** nó e substitua ambas as condições dinâmicas existentes por uma única condição direta: `calculated_speed_kmh <= 200`. As condições originais (`lbs_excluded_flag = 0` e `speed_status = 'VALID'`) referem-se a colunas produzidas pelos nós removidos e causarão um erro de execução se forem mantidas.
4. Clique em **Execute** para visualizar a saída. Verifique se as contagens de pontos e os limites do Trajeto parecem corretos para seus dados antes do Agendamento.

</details>

### Usando o modelo de fluxo de trabalho

Navixy fornece um modelo pronto de fluxo de trabalho de Viagens que você pode carregar no Transformation Builder como ponto de partida. O modelo abrange todas as etapas de processamento descritas nesta página, desde a ingestão de dados brutos até a correspondência de zonas e a agregação.

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 Viagens 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 transformação de Viagens: `tracking_data_core`, `estados`, e `zones_geom`.


---

# 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/trips.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.