> 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/connection-setup/selecting-bi-tools/connecting-grafana.md).

# Conectando o Grafana

Conecte o Grafana ao IoT Query por meio da Fonte de Dados PostgreSQL. Crie gráficos de séries temporais e painéis para monitoramento telemático em tempo real e histórico

Este guia demonstra como conectar o Grafana ao **IoT Query** para visualizar dados de telemetria e de Frota. O Grafana oferece recursos poderosos de visualização para monitorar o status do veículo, dados de sensores e outras métricas em tempo real.

{% hint style="info" %}
Este guia faz parte do **IoT Query** conjunto de documentação e aborda especificamente a conexão do Power BI ao seu data warehouse. Se você ainda estiver decidindo qual ferramenta de BI usar, consulte a [Selecionando ferramentas de BI](https://www.navixy.com/docs/analytics/iot-query/connection-setup/selecting-bi-tools) Visão geral.
{% endhint %}

Assista a uma breve visão geral em vídeo para ver o que é possível com **IoT Query**combinação +Grafana (disponível em inglês e espanhol):

{% tabs %}
{% tab title="Inglês" %}
{% embed url="<https://youtu.be/jGO3hIAjPCo?si=7bzWO4XrTwGnTq3c>" %}
**IoT Query** + tutorial de visão geral e configuração do Grafana.
{% endembed %}
{% endtab %}

{% tab title="Espanhol" %}
{% embed url="<https://youtu.be/jEf7i_mAWPE?si=pru7QyYHzyoqK79Q>" %}
Visão geral e tutorial de configuração de **IoT Query** + Grafana.
{% endembed %}
{% endtab %}
{% endtabs %}

## Recursos do painel

* Visualização de dados de sensores em tempo real
* Análise de séries temporais com intervalos de tempo personalizáveis
* Filtragem dinâmica usando variáveis
* Suporte para várias fontes de dados
* Gráficos e diagramas interativos
* Criação personalizada de consultas com SQL

## Requisitos técnicos

* Grafana 9.3 ou posterior
* plugin da Fonte de Dados PostgreSQL (incluído por padrão)
* Acesso à internet para conexão com o banco de dados
* Ativa **IoT Query** instância com credenciais de conexão

## Instalação e configuração

O Grafana deve estar instalado no seu sistema antes que você possa conectar-se ao **IoT Query**.

{% stepper %}
{% step %}

#### Instalar Grafana

1. Baixe e instale o Grafana do site oficial:\
   <https://grafana.com/grafana/download>
2. Siga as instruções de instalação para o seu sistema operacional.
   {% endstep %}

{% step %}

#### Baixar modelos de painel (opcional)

Modelos de painel pré-construídos estão disponíveis para ajudá-lo a começar rapidamente sem criar visualizações do zero. Esses modelos são mantidos no [repositório bi-intergrations](https://github.com/Navixy/bi-integrations) na `pasta grafana.` Você pode clonar o repositório para acessar painéis prontos:

```bash
git clone https://github.com/Navixy/bi-integrations.git
```

Verifique a `pasta grafana.` pasta para arquivos JSON de painel disponíveis.
{% endstep %}
{% endstepper %}

## Conexão com o banco de dados

A seção Connections no Grafana é onde você gerencia todas as integrações de fontes de dados.

{% stepper %}
{% step %}

#### Acesse a guia Connections

Abra o Grafana e navegue até **Connections** na barra lateral esquerda. **IoT Query** é executado em PostgreSQL, então você precisa adicionar uma Fonte de Dados PostgreSQL para permitir que o Grafana consulte seus dados de telemetria.
{% endstep %}

{% step %}

#### Adicionar Fonte de Dados PostgreSQL

O plugin da Fonte de Dados PostgreSQL vem pré-instalado com o Grafana e oferece suporte nativo para conexão com bancos de dados PostgreSQL.

Para adicionar a fonte de dados:

1. Na seção Connections, procure por **PostgreSQL**
2. Clique em **Adicionar nova fonte de dados**
3. A página de configuração do PostgreSQL será aberta
   {% endstep %}

{% step %}

#### Configure os parâmetros de conexão

Seus **IoT Query** detalhes de conexão contêm todas as informações necessárias para estabelecer uma conexão segura. Esses parâmetros são exclusivos da sua instância e garantem que o Grafana possa acessar seus dados de telemetria.

Localize seus parâmetros de conexão na sua conta Navixy e no **IoT Query** e-mail de boas-vinda&#x73;**.**

**Referência dos parâmetros de conexão**

| Parâmetro          | Campo de configuração | Descrição                                                                                     |
| ------------------ | --------------------- | --------------------------------------------------------------------------------------------- |
| Host               | `Host`                | Endereço do servidor do banco de dados fornecido nos seus **IoT Query** detalhes de conexão   |
| Port               | `Port`                | O padrão é 5432 para PostgreSQL                                                               |
| Database name      | `Database`            | O nome do banco de dados atribuído a você                                                     |
| Username           | `User`                | Seu nome de usuário do banco de dados (referido como "database user" nos detalhes de conexão) |
| Password           | `Password`            | Sua senha segura do banco de dados                                                            |
| SSL mode           | `SSL Mode`            | Defina como `require` para conexões seguras                                                   |
| PostgreSQL version | `Version`             | Selecione **9.3** (configuração recomendada)                                                  |
| {% endstep %}      |                       |                                                                                               |

{% step %}

#### Configure configurações adicionais

Além dos parâmetros de conexão essenciais, o Grafana oferece opções adicionais de configuração. Para a maioria dos usuários, os valores padrão são adequados e funcionarão corretamente sem modificação. Você pode ajustar essas configurações depois com base nos requisitos de segurança da sua organização, nas restrições da infraestrutura ou nas necessidades específicas do equipamento.

Deixe todos os outros campos com seus valores padrão para a configuração inicial. Você não precisa ativar nenhum botão ou alternador adicional.
{% endstep %}

{% step %}

#### Teste a conexão

Testar a conexão antes de salvar garante que todos os parâmetros estejam corretos e que o Grafana possa se comunicar com êxito com sua **IoT Query** instância.

Para verificar e salvar:

1. Dê um nome descritivo à sua conexão (por exemplo, "**IoT Query** Produção" ou "Análises de Frota")
2. Clique em **Salvar & Testar** para verificar sua conexão
3. Uma mensagem verde de sucesso indica que a conexão está funcionando corretamente
   {% endstep %}
   {% endstepper %}

## Criando sua primeira visualização

Criar sua primeira visualização ajuda você a entender como o Grafana consulta **IoT Query** e exibe dados de telemetria. Esse processo envolve criar um painel, adicionar um painel, configurar uma consulta e selecionar um formato de visualização apropriado.

{% stepper %}
{% step %}
**Criar um novo painel**

Os painéis no Grafana servem como contêineres para várias visualizações. Criar um painel dedicado ajuda você a organizar visualizações relacionadas e fornece um local central para monitorar aspectos específicos das operações da sua Frota.

Para criar um painel:

1. Navegue até **Dashboards** na barra lateral esquerda
2. Clique em **Criar painel**
3. Selecione **Adicionar visualização**
4. Escolha a Fonte de Dados PostgreSQL que você acabou de configurar
   {% endstep %}

{% step %}
**Configurar a consulta**

O Grafana oferece dois modos de consulta: um Builder visual e um editor de código. Para **IoT Query** conexões, o editor de código oferece controle total sobre as consultas SQL e é recomendado para análise de dados de telemetria.

Para escrever sua consulta:

1. No editor de consultas, alterne de **Builder** para **Code** modo
2. Insira sua consulta SQL diretamente

Exemplo de consulta para visualização de dados de sensores:

```sql
SELECT 
    device_time AS time,
    value::numeric AS value,
    sensor_name
FROM raw_telematics_data.inputs
WHERE sensor_name = 'temperature'
    AND device_id = 12345
    AND $__timeFilter(device_time)
ORDER BY device_time
```

A consulta inclui um componente de tempo (`device_time AS time`) o qual é essencial para visualizações de séries temporais. A `$__timeFilter()` função é uma macro do Grafana que aplica automaticamente o intervalo de tempo selecionado do painel à sua consulta.

Para mais exemplos de consulta, consulte o [Livro de receitas SQL](https://www.navixy.com/docs/analytics/example-queries).
{% endstep %}

{% step %}
**Definir formato de visualização**

O formato de visualização determina como seus dados aparecem no painel. Diferentes formatos se adequam a diferentes tipos de dados — séries temporais funcionam bem para leituras de sensores ao longo do tempo, enquanto tabelas são melhores para registros detalhados.

Para configurar o formato:

1. Clique em **Executar consulta** para verificar se sua consulta retorna dados
2. Localize o seletor de tipo de visualização (geralmente no canto superior direito do painel)
3. Altere o formato de **Table** para **Time series** ou seu formato preferido
4. Observe a exibição dos dados para garantir que ela apareça corretamente

As visualizações de séries temporais exigem uma coluna de tempo e valores numéricos para funcionar corretamente. Sua consulta deve retornar dados no formato apropriado para o tipo de visualização selecionado.
{% endstep %}

{% step %}
**Salvar sua visualização**

Salvar seu trabalho preserva a configuração da visualização e a torna disponível para referência futura. Salvamentos regulares são importantes — o Grafana não salva as alterações automaticamente, então você pode perder seu trabalho se sair sem salvar.

Para salvar uma visualização:

1. Clique em **Salvar**
2. Forneça um nome descritivo para o seu painel
3. Selecione ou crie uma pasta para organização
4. Confirme a operação de salvamento

O painel agora está disponível na sua instância do Grafana e pode ser acessado pelo menu Dashboards.
{% endstep %}
{% endstepper %}

### Trabalhando com variáveis

As variáveis são um dos recursos mais poderosos do Grafana para criar painéis dinâmicos e interativos. Em vez de codificar valores específicos como nomes de sensores ou IDs de dispositivos nas suas consultas, as variáveis permitem que os usuários selecionem valores diferentes em menus suspensos sem editar o SQL subjacente. Isso torna os painéis mais flexíveis e fáceis de usar.

{% stepper %}
{% step %}
**Acessar as configurações de variáveis**

As variáveis são configuradas no nível do painel e se aplicam a todas as visualizações dentro desse painel. Você precisa acessar as configurações do painel para criar e gerenciar variáveis.

Para começar:

1. Abra seu painel
2. Clique no ícone do painel **Configurações** ícone (ícone de engrenagem) no canto superior direito
3. Navegue até a **Variáveis** seção no painel esquerdo
4. A seção estará vazia se nenhuma variável tiver sido criada ainda
   {% endstep %}

{% step %}
**Configurar uma variável**

Cada variável precisa de um nome, uma Fonte de Dados e uma consulta que retorne os valores possíveis que os usuários podem selecionar. Os valores da variável são preenchidos dinamicamente por meio de consulta à sua **IoT Query** instância.

Para criar uma variável:

1. Clique em **Adicionar variável**
2. Configure as seguintes definições:
   1. **Configurações gerais:**
      1. **Nome**: `sensor_name` (use um identificador claro e descritivo sem espaços)
      2. **Rótulo**: O mesmo que o nome para consistência; é isso que os usuários veem no painel
      3. **Tipo**: Selecione **Consulta** para preencher os valores do banco de dados
   2. **Opções da consulta:**
      1. **Fonte de Dados**: Selecione sua conexão PostgreSQL **IoT Query** no menu suspenso
      2. **Consulta**: Insira uma consulta SQL para preencher os valores da variável

Exemplo de consulta para listar todos os sensores de um dispositivo específico:

```sql
SELECT DISTINCT sensor_name
FROM raw_telematics_data.inputs
WHERE device_id = 12345
ORDER BY sensor_name
```

Depois de inserir a consulta, o Grafana a executa imediatamente e exibe uma pré-visualização dos valores retornados na parte inferior da página de configuração. Isso confirma que sua consulta está funcionando corretamente e mostra quais opções estarão disponíveis no menu suspenso.
{% endstep %}

{% step %}
**Aplicar variáveis nas consultas**

Depois que uma variável é criada, você precisa atualizar suas consultas de visualização para referenciá-la. As variáveis usam uma sintaxe especial com prefixo de cifrão, e o Grafana substitui automaticamente o valor selecionado ao executar consultas.

Para usar a variável:

1. Abra a visualização que você quer tornar dinâmica
2. Edite a consulta
3. Substitua o valor codificado pela referência da variável

Exemplo de consulta atualizada usando a variável:

```sql
SELECT 
    device_time AS time,
    value::numeric AS value,
    sensor_name
FROM raw_telematics_data.inputs
WHERE sensor_name = '$sensor_name'
    AND device_id = 12345
    AND $__timeFilter(device_time)
ORDER BY device_time
```

Observe como `'temperature'` foi substituído por `'$sensor_name'`. As aspas são importantes para valores de string em SQL.
{% endstep %}

{% step %}
**Salvar e testar**

Testar a variável garante que ela funcione corretamente e atualize as visualizações como esperado. Certifique-se de salvar seu trabalho em cada etapa para evitar perder alterações de configuração.

Para concluir a configuração:

1. Clique em **Aplicar** para salvar a configuração da variável
2. Clique em **Salvar painel** para preservar todas as alterações
3. Retorne à visualização principal do painel
4. Localize o menu suspenso da variável na parte superior do painel
5. Selecione nomes de sensores diferentes no menu suspenso
6. Observe que a visualização é atualizada automaticamente com os dados do sensor selecionado

Se a visualização não for atualizada quando você alterar a seleção da variável, verifique se o nome da variável na sua consulta corresponde exatamente ao nome da variável que você criou (os nomes das variáveis diferenciam maiúsculas de minúsculas).
{% endstep %}
{% endstepper %}

### Importando painéis pré-criados

Painéis pré-criados oferecem uma forma rápida de começar a visualizar seus dados sem construir tudo do zero. Esses painéis são projetados por usuários experientes e incluem boas práticas de visualização, layout e otimização de consultas. No entanto, eles exigem configuração para se conectar à sua específica **IoT Query** instância.

{% stepper %}
{% step %}
**Acesse a função de importação**

O recurso de importação do Grafana permite carregar configurações de painel a partir de arquivos JSON ou diretamente do Grafana.com usando IDs de painel.

1. Navegue até **Dashboards**
2. Clique em **Novo** → **Importar**
3. Uma janela de envio aparecerá
   {% endstep %}

{% step %}
**Importe o painel**

O processo de importação aceita configurações de painel em vários formatos, dando a você flexibilidade na forma como carrega painéis pré-criados.

Você pode importar painéis usando:

* **ID do painel** do Grafana.com
* **arquivo JSON** baixado do repositório bi-intergrations
* **modelo JSON** colado diretamente

Se estiver usando um arquivo JSON:

1. Clique em **Carregue o arquivo JSON**
2. Selecione o arquivo do painel
3. Forneça um nome e selecione a pasta de destino
4. Clique em **Importar**

Aguarde a conclusão do envio do modelo de painel. Quando estiver concluído, o painel aparecerá, mas ainda não exibirá dados porque ainda está conectado à fonte de dados original usada quando o modelo foi criado.
{% endstep %}

{% step %}
**Atualizar conexões da fonte de dados**

Este é um passo crítico. Os painéis importados estão inicialmente conectados a fontes de dados externas que não têm acesso aos seus **IoT Query** dados. Você deve atualizar cada visualização para usar seu PostgreSQL **IoT Query** conexão.

Para atualizar as visualizações:

1. Abra o painel importado
2. Clique em **Editar** no primeiro painel de visualização (procure o ícone de edição ou o menu de três pontos)
3. No editor de consultas, localize o seletor de fonte de dados
4. Altere a fonte de dados da fonte original do modelo para seu PostgreSQL **IoT Query** conexão
5. Clique em **Executar consulta** para verificar se a visualização recupera dados com sucesso
6. Clique em **Salvar** para preservar as alterações
7. Repita esse processo para cada painel de visualização do painel

{% hint style="info" %}
Salve seu trabalho com frequência durante esse processo. Você pode ter várias visualizações para atualizar, e salvar após cada uma garante que você não perca o progresso.
{% endhint %}
{% endstep %}

{% step %}
**Atualizar variáveis do painel**

Muitos painéis pré-criados usam variáveis para filtragem e interatividade. Essas variáveis também estão conectadas à fonte de dados original e precisam ser atualizadas para consultar a sua **IoT Query** instância.

Para atualizar as variáveis:

1. Abra **Configurações** → **Variáveis**
2. Você verá uma lista de todas as variáveis usadas no painel
3. Clique em **Editar** na primeira variável
4. Localize o **Fonte de Dados** menu suspenso na seção Query options
5. Altere-o para seu PostgreSQL **IoT Query** conexão
6. Verifique se a prévia na parte inferior mostra os valores esperados do seu banco de dados
7. Clique em **Aplicar** para confirmar as alterações
8. Repita para cada variável da lista

Depois de atualizar todas as variáveis, salve o painel novamente. As variáveis agora devem ser preenchidas com valores da sua **IoT Query** instância.
{% endstep %}

{% step %}
**Verificar a funcionalidade do painel**

Depois de atualizar todas as visualizações e variáveis, verifique se tudo funciona corretamente em conjunto. Essa verificação final garante que o painel esteja totalmente funcional e pronto para uso regular.

Para verificar:

1. Salve o painel uma última vez usando **Ctrl+S** ou o **Salvar** botão
2. Atualize completamente a página do navegador (ou use **F5**)
3. Verifique se todas as visualizações exibem dados corretamente
4. Teste cada menu suspenso de variável para garantir que ele seja preenchido com valores
5. Selecione valores diferentes de variável e confirme se as visualizações são atualizadas de acordo
6. Experimente diferentes intervalos de tempo usando o seletor de tempo

Se alguma visualização continuar vazia ou mostrar erros, volte para o modo de edição e verifique a configuração da fonte de dados e da consulta desses painéis específicos.
{% endstep %}
{% endstepper %}

## Solução de problemas

### Problemas de conexão com o banco de dados

**Erro de conexão**: Verifique se as credenciais e os parâmetros de conexão correspondem exatamente aos seus **IoT Query** detalhes. Verifique se o host, a porta, o nome do banco de dados, o nome de usuário e a senha estão corretos.

**Erro de firewall**: Garanta que sua rede permita conexões ao host e à porta especificados. Entre em contato com o administrador da rede se as tentativas de conexão forem bloqueadas.

**Erro de SSL/TLS**: Verifique se o modo SSL está definido como `require` e sua instância do Grafana oferece suporte a conexões SSL.

### Problemas de consulta e visualização

**Visualização vazia**: Primeiro, verifique se a consulta realmente retorna dados conferindo o inspetor de consultas (clique no botão "Inspetor de consultas" no editor do painel). Certifique-se de que o intervalo de tempo selecionado inclua períodos em que haja dados no seu banco de dados. Confirme se a fonte de dados está selecionada e conectada corretamente. Verifique se os nomes de tabela e coluna em sua consulta correspondem à estrutura real do esquema.

**Variável não funciona**: Verifique se a consulta da variável retorna valores conferindo a prévia na página de configuração da variável. Certifique-se de que a referência da variável em sua consulta use a sintaxe correta (`$variable_name`) sem erros de digitação. Verifique se a variável está salva corretamente e aplicada ao painel. Se o menu suspenso da variável estiver vazio, revise a consulta SQL da variável em busca de erros.

**Desempenho lento de consultas**: Considere adicionar índices de banco de dados às colunas consultadas com frequência, como `device_time` e `device_id`. Limite os intervalos de dados usando filtros de tempo de forma mais restritiva. Otimize a estrutura da consulta selecionando apenas as colunas necessárias em vez de usar `SELECT *`. Consulte [Livro de receitas SQL](https://www.navixy.com/docs/analytics/example-queries) para exemplos de otimização de desempenho e padrões de consulta comprovados.

**Incompatibilidade de formato**: Garanta que sua consulta retorne dados no formato esperado pelo seu tipo de visualização. Painéis de série temporal exigem uma coluna com alias de `time` e colunas de valores numéricos. Painéis de tabela aceitam qualquer estrutura de colunas. Painéis de gráfico precisam de dados de tempo e numéricos. Consulte a documentação do Grafana para requisitos específicos de cada tipo de visualização.

### Problemas de importação

**Dados ausentes após a importação**: Verifique se as conexões da Fonte de Dados estão atualizadas para todos os painéis e variáveis. Não pule nenhum painel durante o processo de atualização. Verifique se os nomes dos esquemas (`raw_business_data` ou `raw_telematics_data`) especificados nas consultas estão corretos para sua **IoT Query** instância. Certifique-se de que os nomes de tabelas e colunas correspondam à estrutura real do seu banco de dados.

**O painel mostra erros**: Abra o editor de consultas de cada painel e clique em "Query inspector" para ver mensagens de erro detalhadas. Revise as mensagens de erro com atenção — elas costumam indicar problemas específicos, como colunas ausentes, tipos de dados incorretos ou erros de sintaxe. Certifique-se de que os nomes dos campos nas consultas correspondam exatamente ao seu **IoT Query** esquema exatamente (os nomes dos campos diferenciam maiúsculas de minúsculas). Verifique se os tipos de dados retornados pelas consultas são compatíveis com o tipo de visualização.

**Variáveis não estão sendo preenchidas**: Verifique se você atualizou a Fonte de Dados de cada variável, e não apenas os painéis de visualização. Verifique se as consultas das variáveis estão sintaticamente corretas e retornam dados quando executadas diretamente. Certifique-se de que o tipo da variável esteja definido como "Query" em vez de "Custom" ou outros tipos.

## Próximos passos

Depois de conectar o Grafana com sucesso à sua **IoT Query** instância:

* Explore os esquemas de dados disponíveis revisando a [Visão geral do esquema](/docs/analytics/pt-br/iot-query/schema-overview.md) para entender a estrutura dos dados, as relações entre as tabelas e os campos disponíveis.
* Comece com consultas simples focadas em entidades de negócios específicas antes de criar painéis complexos; isso ajuda você a aprender a estrutura dos dados e evitar problemas de desempenho.
* Revise os [Livro de receitas SQL](/docs/analytics/pt-br/example-queries.md) para padrões de consulta comprovados e técnicas de otimização, e exemplos de cenários comuns de análise de telemetria
* Experimente diferentes tipos de visualização (séries temporais, tabelas, medidores, painéis de estatísticas) para encontrar a melhor representação para seus dados específicos e casos de uso
* Considere criar vários painéis para diferentes finalidades: monitoramento em tempo real, análise histórica, resumos executivos e Relatórios operacionais.

### Suporte

Para dúvidas técnicas ou assistência com **IoT Query** conexões, entre em contato com o suporte em <support@navixy.com>.


---

# 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/connection-setup/selecting-bi-tools/connecting-grafana.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.