Vinculação de Dados

A vinculação de dados é a ponte entre o banco de dados do projeto e os widgets nos seus boards IoT. Quase toda propriedade configurável de um widget — seu título, valores, cores, séries de gráfico, intervalos de medidor — pode ser alimentada dinamicamente por dados ao vivo do TimescaleDB do seu projeto. Esta página explica como conectar colunas de tabela a propriedades de widget e como refinar seus dados com filtros.

Para uma visão ampla de como os dados chegam ao banco de dados do projeto, veja a visão geral de gerenciamento de dados.

Duas formas de vincular dados

O IronFlock Board Studio suporta dois modos fundamentais de vinculação:

Referências de valor — vinculam um único valor escalar (o registro mais recente de uma coluna) a uma propriedade de widget.
Referências de tabela — vinculam um conjunto inteiro de resultados (várias linhas) a uma propriedade de widget que espera um array.

Ambos os modos suportam filtragem e fornecem atualizações em tempo real: assim que novas linhas chegam ao banco de dados do projeto, as propriedades vinculadas do widget atualizam automaticamente sem polling.

Referências de valor

A maioria dos campos de configuração de widget espera um único valor — um título, um número para exibir, uma cor, um rótulo de status. No editor de widgets, há um pequeno interruptor de vinculação de dados abaixo desses campos.

Ao habilitar o interruptor e clicar no campo, um menu suspenso se abre listando todos os dados disponíveis no seu banco de dados do projeto. Você pode:

escolher uma tabela do banco de dados do projeto;
escolher uma coluna dessa tabela para vincular à propriedade.

Exemplo: você pode vincular o campo Título de um widget de medidor à coluna name da tabela machine, ou o campo Valor de um widget numérico ao valor mais recente de temperature da tabela sensor_data.

Valor mais recente

Uma referência de valor sempre entrega o único valor mais recente da coluna selecionada. “Mais recente” é determinado pela coluna obrigatória tsp — toda tabela no banco de dados do projeto tem uma coluna de timestamp tsp, e a linha com o maior tsp vence.

Ícone de filtro

Ao vincular uma coluna a uma propriedade de widget, um pequeno ícone de filtro aparece ao lado do interruptor de dados abaixo do campo. Clicar nele abre uma caixa de diálogo onde você pode configurar filtros para restringir quais linhas são consideradas ao extrair o valor. Veja Configuração de filtro abaixo.

Referências de tabela

Alguns widgets esperam um array de valores em vez de um escalar. Por exemplo, um widget de gráfico precisa de muitos pontos (x, y) para desenhar uma linha, e um widget de tabela precisa de muitas linhas.

Nesses lugares, o editor do widget exibe tanto um botão Adicionar ao lado do rótulo do campo (para adicionar elementos de array manualmente) quanto um interruptor de vinculação de dados.

Modo manual: clique em Adicionar para anexar elementos um por um, com valores estáticos.
Modo de vinculação de dados: ative o interruptor para vincular o array a uma tabela. Ao selecionar uma tabela, cada linha que corresponde aos seus critérios se torna um elemento no array.

O ícone de filtro ao lado do interruptor de dados permite restringir quais linhas são retornadas para corresponder aos seus requisitos — veja Configuração de filtro.

Mapeando colunas para campos de elementos de array

Quando a vinculação de dados por referência de tabela está ativa, você configura um único modelo de elemento de array usando valores da tabela conectada. Para um gráfico de linhas, um elemento precisa de um valor x e um valor y — você pode fazer com que ambos sejam orientados por dados selecionando qual coluna da tabela vinculada alimenta cada eixo. Cada linha no conjunto de resultados filtrado é então renderizada no gráfico usando esse mapeamento.

O mesmo padrão se aplica a qualquer widget que aceita um array: gráficos de barras, tabelas, listas, mapas de calor, etc.

Configuração de filtro

Os filtros restringem quais linhas são usadas para uma referência de valor ou tabela. As seções da caixa de diálogo são aplicadas na ordem em que aparecem — que é também a ordem em que o banco de dados do projeto as aplica:

1. Janela de tempo móvel

Configure como os registros são filtrados por tempo:

Janela deslizante — mostre apenas linhas dos últimos N minutos, horas, dias, etc., relativo ao agora.
Janela temporal personalizada — forneça os nomes de um parâmetro de início e um parâmetro de fim. Esses nomes de parâmetro são alimentados em tempo de execução pelo widget de calendário, permitindo que os usuários finais escolham um intervalo de tempo no board.

2. Filtros de coluna arbitrários

Adicione quantos filtros de nível de coluna quiser usando uma das seguintes fontes de valor:

Valores constantes — um valor codificado (ex.: status = 'active').
Parâmetros de filtro — valores alimentados pela URL por widgets de filtro.
Segmentos de caminho de roteamento — valores extraídos da URL da página atual via widgets de navegação.

3. Agregação

Por padrão, uma vinculação retorna linhas brutas. Mude-a para Agregado ao longo do tempo e o banco de dados do projeto agrupa os registros selecionados em intervalos de tempo — ou em categorias — e retorna um valor calculado por grupo: médias horárias, registros por máquina, o total de hoje.

Como os filtros rodam antes dessa etapa, são eles que decidem quais registros entram em cada intervalo. A agregação é tratada por completo em sua própria página: veja Agregação e Downsampling.

4. Limite de Linhas

Defina um limite superior para o número de linhas retornadas para o widget. O limite não pode exceder 3000 — esse teto protege tanto o navegador quanto o banco de dados do projeto de conjuntos de resultados excessivamente grandes.

Para uma vinculação agregada, o número de intervalos retornados é derivado de outra forma (da largura do widget ou do intervalo que você escolheu), e o limite de linhas atua apenas como salvaguarda de reserva.

Todas as seções se combinam: a janela temporal restringe o intervalo de tempo, os filtros de coluna refinam ainda mais as linhas, a agregação as reduz a um valor por intervalo, e o limite de linhas limita a saída final.

Selecionando campos de colunas JSON

O banco de dados do projeto suporta colunas JSON para dados não estruturados ou semi-estruturados — payloads de telemetria de dispositivos, blobs de configuração, registros aninhados.

Ao vincular uma coluna JSON a uma propriedade de widget, uma entrada adicional aparece permitindo especificar um caminho para um campo folha dentro da estrutura JSON. O caminho usa notação padrão de objetos JavaScript:


sensor.temperature
payload.items.0.value
metadata.location.city

O widget extrai o valor nesse caminho de cada registro. Isso funciona tanto para referências de valor (folha do registro JSON mais recente) quanto para referências de tabela (folha de cada linha).

Resumo

Use referências de valor para propriedades escalares (títulos, valores, cores) — você obtém o valor mais recente por tsp.
Use referências de tabela para propriedades de array (séries de gráfico, tabelas, listas) — mapeando colunas para campos de elementos de array.
Use a caixa de diálogo de filtro para refinar linhas por janela temporal, filtros de coluna e limite de linhas (máx. 3000).
Mude uma vinculação para agregada quando quiser valores calculados em vez de registros — veja Agregação e Downsampling.
Use a notação de caminho JSON para explorar colunas JSON não estruturadas.