Introdução

Os sistemas supervisórios devem ser capazes de armazenar os dados históricos da planta de forma permanente. Normalmente, estes dados são valores de variáveis, horário de logins de usuário, alertas e quaisquer outros eventos relevantes ocorridos na planta monitoradas, sendo importantes para registrar todo o histórico da planta.

Uma das formas mais eficiente, confiável e segura de armazenar estes dados é utilizando softwares de bancos de dados (do inglês, Data Base, ou DB). Além de viabilizarem um armazenamento seguro, estes softwares disponibilizam ferramentas para recuperar e manipular os dados de forma eficiente.

Para a nossa prática, iremos interagir o Node-RED com um servidor de banco de dados do Mongo-DB, software gratuito e muito utilizado devido a sua versatilidade e fácil integração com Javascript, permitindo a escrita e leitura de dados diretamente em formato JSON.

Na prática, o software do Mongo-DB disponibiliza um servidor de banco de dados e um serviço que permite receber chamadas em uma das portas da máquina que o executa. Assim, qualquer software terceiro que deseja utilizar este serviço deve interagir com o Mongo-DB através de seu endereço URI (i.e., https://<IP>:<PORTA>). Por padrão, o Mongo-DB utiliza a porta 27017.

Organização dos dados

Um único servidor Mongo-DB é capaz de armazenar vários bancos de dados, que são unidades de armazenamento independentes identificados por um nome único naquele servidor. O identificador deve ser uma string única naquele servidor. Recomenda-se definir seu nome somente com letras minúsculas, sem espaços ou caracteres especiais.

Cada banco de dados pode ter diversas coletâneas (do inglês, collection), que são similares ao conceito de planilhas do excel, permitindo registrar diversas colunas de diferentes tipos de dados, cada coluna podendo receber várias entradas (linhas/rows) de dados. Cada coletânea também é identificada por uma string única cujo nome deve ser definido de maneira similar aos identificadores dos bancos de dados.

Instalando o Mongo-DB

O Mongo-DB pode ser instalado diretamente no Sistema Operacional. Os links a seguir descrevem como fazê-lo no Linux, macOS e Windows.).

Entretanto, para quem já tem o Docker instalado na máquina, basta executar o seguinte comando para levantar um container executando o servidor do Mongo-DB:

docker run -d -p 27017:27017 --name mongo-container -v mongo-data:/data/db --network net-nodered mongo:latest

Os parâmetros do comando acima são:

• docker run: Invoca o docker e pede para ele rodar um container a partir de uma imagem.
• -d: Executa em modo "detached", i.e., o container será executado em segundo plano, não "prendendo" o terminal atual.
• -p 27017:27017: Mapeia a porta 27017 o computador host na porta 27017 do container, i.e., chamadas na porta 27017 do host serão direcionadas para a porta 27017 do container. Caso queira disponibilizar o Mongo-DB em outra porta do host, pode-se alterar o primeiro valor deste argumento. Por exemplo, para disponibilizar o BD na porta 30301, pode-se alterar este argumento para -p 30301:27017.
• --name mongo-container: Nome do container que será executado. Este nome pode ser alterado para o que preferir.
• -v mongo-data:/data/db: Cria um volume de armazenamento permanente no host chamado mongo-data e remapeia este volume no caminho /data/db do container. Este parâmetro garante que os dados armazenados pelo Mongo-DB serão permanentes enquanto o volume mongo-data existir no host, mesmo que o container do servidor seja deletado. Este parâmetro é essencial na criação de servidores de banco de dados.
• --network net-nodered: conecta o container à rede net-nodered. Este parâmetro garante que o container do banco de dados estará conectado à mesma rede virtual que o container do Node-RED.
• mongo:latest: O container será criado utilizando a imagem mongo em sua versão latest (i.e., a última versão estável disponível). Note que o docker faz automaticamente o download desta imagem a partir do dockerhub, que é seu servidor de imagens oficial.

Após levantar o servidor, pode-se testar se o Mongo-DB está disponível utilizando o comando nmap:

nmap -p <PORTA-DO-MONGO> <IP>

Caso esteja executando o docker em sua própria máquina, pode substituir o parâmetro <IP> por localhost.

Interagindo o Node-RED com um servidor Mongo-DB

Para interagir com o servidor Mongo-DB, instale no Node-RED o módulo node-red-contrib-mongodb4, cujo manual pode ser encontrado neste link. Ao instalá-lo, irá aparecer na paleta o nó mongodb4, que permite interagir e realizar operações em um servidor Mongo-DB.

Para iniciar, arraste o nó mongodb4 para o flow e dê 2x cliques nele para abrir suas propriedades. A propriedade Connection permite criar uma conexão com um servidor em execução. Para isto, clique no símbolo de + e abrirá a janela Simple Connection URI. Como configurações mínimas, defina os seguintes parâmetros:

• Hostname: Insira o IP da máquina que está executando o servidor.
• Port: Insira a porta em que o serviço está disponibilizado.
• Database: O nome do banco de dados que será utilizado. Caso ainda não exista, o nó irá criá-lo no servidor.

Clique então em Add para criar a conexão com este banco de dados. A janela irá retornar para as propriedades do nó mongodb4 com a propriedade Connection já definida com a conexão recém criada. Pronto! assim já é possível interagir com o banco de dados.

Mensagem básica de interação

Para utilizar o nó mongodb4, deve-se enviar uma msg na entrada de seu bloco. É obrigatório que cada mensagem contenha os seguintes campos:

• msg.collection: String com o nome da coletânea (tabela) de trabalho.
• msg.operation: Tipo da operação que será realizada (find, findOne, insertOne, insertMany, updateOne, updateMany, deleteOne, deleteMany, aggregate).
• msg.payload: Conteúdo em função da operação que será realizada.

msg = {}; // limpa completamente a mensagem
msg.collection = "nome-da-coletanea";
msg.operation = "tipo-de-operacao";
msg.payload = [ /* argumentos posicionais */ ];
return msg;

Msg.payload

O msg.payload é sempre um array posicional que mapeia diretamente para os argumentos do driver oficial do MongoDB para Node.js:

Operadores de filtro mais comuns

Opções de leitura mais comuns (2º elemento do array)

Operações

A seguir seguem as definições e exemplos de utilização de cada uma das possíveis operações com o Mongo-DB.

insertOne

Insere uma única linha de dados na collection. Os dados devem ser organizados como um JSON, sendo a chave o nome da coluna e seu valor o dado a ser inserido naquela linha.

Sua sintaxe é:

msg.payload = [ {nome-coluna-1: <dado-a-ser-inserido>, 
                  nome-coluna-2: <dado-a-ser-inserido>
              } ];

Exemplo 3·insertOne

Exemplo de código típico no armazenamento de dados de sensores com marcação de hora da leitura.

javascript

msg = {} // Limpa a mensagem por completo.
msg.collection = "sensores-temperatura";
msg.operation = "insertOne";

// Dados a serem inseridos no banco de dados
msg.payload = [{
  sensor:    "sensor-12", // uma string que descreve o nome do sensor que coletou o dado
  timestamp: new Date().getTime(), // recebe um número com o timestamp atual
  value:     Math.random()*100 // cria um número aleatório entre 0 e 100 para mockar o dado do sensor
}];

return msg;

Ao injetar esta mensagem, colete a saída do nó mongodb4 em um nó Debug e note que é retornada uma mensagem indicando sucesso (ou não) na operação e o identificador da entrada de dados recém criada.

insertMany

Insere múltiplos documentos no banco de dados em uma única operação. Esta operação é mais eficiente do que chamar várias vezes insertOne, sendo preferida caso já haja uma grande quantidade de linhas disponíveis a serem salvas.

A sintaxe é:

msg.payload = [ arrayDeDocumentos, opções ];

msg = {} // Limpa a mensagem por completo.
msg.collection = "sensores-temperatura";
msg.operation = "insertMany";
msg.payload = [[{ sensor: "sensor-1", timestamp: new Date().getTime(), value: Math.random()*100 },
    { sensor: "sensor-2", timestamp: new Date().getTime(), value: Math.random()*100 },
    { sensor: "sensor-3", timestamp: new Date().getTime(), value: Math.random()*100 }
    ]]; // note que há um array de entradas dentro do array que, caso tivesse, traria os filtros e opções nos outros elementos.
return msg;

find

Retorna um array contendo todos os documentos que satisfazem o filtro enviado.

Sintaxe:

msg.payload = [ <filtro>, <opções> ];

// Todos os documentos da collection
msg.collection = "sensores-temperatura";
msg.operation = "find";
msg.payload = [ {}, {} ];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "findOne";
msg.payload = [
    { _id: new mongodb.ObjectId("6a15e0a54ea48a43ab568637") }
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "find";
msg.payload = [
  {},
  { sort: { timestamp: -1 }, // `-1` para ordenação decrescente
    limit: 10 } // 
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "find";
msg.payload = [
  { value: { $gte: 60, $lte: 95 } },
  {
    sort: { timestamp: 1 }, // `1` para ordenação crescente
    limit: 50,  // quantidade máxima de retorno
    projection: { sensor: 1, timestamp: 1, value: 1, _id: 0 } // retorna apenas `timestamp`, `value` e nome do sensor
  }
];
return msg;

findOne

Retorna apenas o primeiro documento que satisfaz o filtro. Esta operação é mais eficiente que find quando deseja-se encontrar somente um registro.

Sua sintaxe é:

msg.payload = [ filtro, opções ];

msg.collection = "sensores-temperatura";
msg.operation = "findOne";
msg.payload = [{}, { sort: { timestamp: -1 } }
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "findOne";
msg.payload = [{sensor: "sensor-1"}, {}
];
return msg;

updateOne

Atualiza o primeiro registro que satisfaz o filtro.

Sintaxe:

msg.payload = [ filtro, update, opções ];

Os operadores de update mais comuns são:

msg.collection = "sensores-temperatura";
msg.operation = "updateOne";
msg.payload = [
    { _id: new mongodb.ObjectId("6a15e0a54ea48a43ab568635") },
    { $set: { sensor: "sensor-24" } }
]; 
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "updateOne";
msg.payload = [
    { sensor: "sensor-1" },
    { $unset: { value: "" } }
];
return msg;

updateMany

Atualiza todos os registros que satisfazem o filtro. Possui a mesma sintaxe do updateOne, mas afeta múltiplos documentos ao mesmo tempo.

msg.collection = "sensores-temperatura";
msg.operation = "updateMany";
msg.payload = [
    { sensor: "sensor-1" },
    { $set: { sensor: "sensor-01" } }
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "updateMany";
msg.payload = [
    { },
    { $set: { planta: "Ouro Branco" } }
];
return msg;

deleteOne

Remove o primeiro documento que satisfaz o filtro.

Sua sintaxe é somente:

msg.payload = [ filtro ];

msg.collection = "sensores-temperatura";
msg.operation = "deleteOne";
msg.payload = [
    {  },
    { sort: {timestamp: 1} }
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "deleteOne";
msg.payload = [{ _id: new mongodb.ObjectId("6a15e0a54ea48a43ab568632")  }, 
                {  }];
return msg;

deleteMany

Remove todos os documentos que satisfazem o filtro.

Sintaxe da mensagem:

msg.payload = [ filtro ];

msg.collection = "sensores-temperatura";
msg.operation = "deleteMany";
let dezMinutosAtras = new Date().getTime() - ( 10 * 60 * 1000);
msg.payload = [
    { timestamp: { $lt: dezMinutosAtras } }
];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "deleteMany";
msg.payload = [
    { sensor: "sensor-2" }
];
return msg;

aggregate

Executa um pipeline de agregação, permitindo encadear estágios de filtragen, transformação, agrupamento e cálculo sobre os dados. É a operação mais poderosa do MongoDB.

Sua sintaxe é:

msg.payload = [[ estágio1, estágio2, ... ]];  // array dentro de array

Os estágios mais comuns são:

Os acumuladores para o estágio $group são:

msg.collection = "sensores-temperatura";
msg.operation = "aggregate";
msg.payload = [[
    { $sort: { timestamp: -1 } },
    { $limit: 20 },
    {
        $group: {
            _id: null,
            media: { $avg: "$value" },
            maximo: { $max: "$value" },
            minimo: { $min: "$value" },
        }
    }
]];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "aggregate";
msg.payload = [[
    {
        $group: {
            _id: "$sensor", // cria um grupo onde o _id é o valor da chave sensor dos dados de entrada
            media: { $avg: "$value" },
            count: { $sum: 1 }
        }
    },
    { $sort: { _id: 1 } }
]];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "aggregate";
msg.payload = [[
    {
        $group: {
            _id: {
                $dateToString: {
                    format: "%Y-%m-%dT%H:00", // note que o marcador vai até horas, o resto está zerado
                    date: { $toDate: "$timestamp" }
                }
            },
            media: { $avg: "$value" },
            count: { $sum: 1 }
        }
    },
    { $sort: { _id: 1 } }
]];
return msg;

msg.collection = "sensores-temperatura";
msg.operation = "aggregate";
msg.payload = [[
    { $match: { sensor: "sensor-1", value: { $gt: 70 } } },
    { $sort: { timestamp: -1 } },
    { $limit: 50 },
    {
        $group: {
            _id: null,
            media: { $avg: "$value" },
            ultimo: { $first: "$timestamp" } // note que ordenação por timestamp está descrescente
        }
    },
    { $project: { _id: 0, media: 1, ultimo: 1 } }
]];
return msg;