Floui Datasources

Introdução

Floui Datasources são ferramentas poderosas para realizar consultas sobre bancos de dados externos integrados com o Workspace Floui, além de permitir a integração destes datasources com fluxos, por meio de conectores. Com os datasources é possível realizar consultas dinâmicas em bancos de dados e manipular os seus registros de forma isolada. Se tornando uma ferramenta poderosa tanto para integrações gerais quanto análise de dados.

Neste artigo, iremos abordar os pré-requisitos e configuração inicial até a utilização avançada do datasource, apresentando a transformação de dados e o uso de conectores para integrar o seu datasource com um fluxo. Além disso, algumas boas práticas para uso da ferramenta, visando expandir o conhecimento da ferramenta.

Pré-requisitos

Para utilizar a ferramenta de datasources é necessário, primeiramente, um banco de dados externo. O datasource irá realizar a conexão com este banco externo e realizar operações sobre os registros deste banco de dados.

Atualmente a ferramenta de Datasources suporta a conexão com os seguintes tipos de bancos de dados:

• Oracle;

• MySQL;

• SQLite;

• SQLServer;

• Firebird;

Tendo um banco de dados é necessário estabelecer os meios de comunicação entre o Workspace Floui e o seu banco de dados. A conexão com o banco de dados é abstraída via cadastro de uma Conta de Serviço no Workspace Floui, realizando a conexão via DataURI.

Para criar esta conexão, acesse o menu Contas de Serviço do seu Workspace Floui e acesse o formulário de criação de uma conta de serviço. Na criação da conta de serviço, selecione o Tipo de autenticação > Database Connection URI, em seguida insira o DataURI de conexão no campo URI de Conexão. Insira um nome para a sua conexão e salve a conta de serviço.

Gerenciamento de Datasources

Acesse o menu Datasources para visualizar as opções de gerenciamento dos datasources. Por esta tela é possível visualizar informações gerais do datasource, além de opções adicionais, como:

• Criar datasource;

• Editar datasource;

• Remover datasource;

• Visualizar datasource;

• Buscar por datasources;

• Filtar datasources por grupos;

Criação de Datasources

Para criar um novo datasource, clique em Criar Datasource. Entenda os campos de configuração do datasource:

• Nome do datasource: Nome de exibição do datasource;

• Grupo: Selecione um grupo cadastrado no Workspace Floui para associar com o datasource. A associação com grupos facilita a organização dos recursos dentro do seu Workspace Floui. Clique aqui para saber mais sobre grupos.

• Tipo: Selecione o tipo de banco de dados que está realizando operações. Para visualizar os tipos suportados acesse a seção Pré-requisitos.

• Conta de serviço: Selecione a conta de serviço para realizar a conexão com banco de dados. Para visualizar como criar uma conta de serviço para conexão acesse a seção Pré-requisitos.

• Query SQL: Campo principal para inserir as operações a serem realizadas no banco de dados.

• Transformação de dados: Seção para realizar modificações dos registros retornados em consulta ao banco de dados. As modificações devem ser realizadas utilizando Javascript e dentro da função transform. Para saber mais sobre a transformação de dados acesse a seção Transformação de dados de consulta.

• Variáveis de entrada: Configure variáveis para utilizar dentro das operações no banco de dados. A configuração permite definir uma legenda para a variável, o código da variável, um valor padrão pré-definido para ela e, por fim, a obrigatoriedade desta variável dentro da operação. Para saber mais como utilizar as variáveis dentro da sua operação acesse a seção Uso de variáveis em datasource.

Transformação de dados de consulta

A Transformação de Dados possibilita a manipulação dos dados recebidos da consulta. Essa funcionalidade viabiliza a realização de cálculos, aplicação de filtros, tratamento de dados, e diversas outras operações diretamente durante o processo de consulta.

Para implementar uma transformação de dados, é obrigatório utilizar a função assíncrona transform(), garantindo que o campo data seja devidamente retornado. O parâmetro data representa os resultados obtidos diretamente da consulta ao banco de dados.

A Transformação de Dados é realizada em linguagem Javascript. Segue a estrutura básica para aplicação de transformações:

async function transform(data) {
    //seu código
    return data
}

O resultado da consulta serão os dados já transformados pela função.

Uso de variáveis em Datasource

O uso de variáveis no datasource amplia a flexibilidade da ferramenta, permitindo a manipulação dinâmica de dados durante a construção da operação.

Para adicionar variáveis, clique no botão Adicionar variável, no canto lateral da edição do datasource, que exibirá uma nova linha para configuração. Preencha os seguintes campos:

• Label: Uma legenda visual para identificar a variável.

• Código da Variável: O nome que será usado na construção da query.

• Valor Padrão: Um valor inicial que será usado, caso outro não seja fornecido.

• Obrigatoriedade: Indique se a variável é obrigatória para a execução.

Na query, utilize a seguinte notação para referenciar variáveis:{{var nome_da_variavel}}

A configuração de variáveis no datasource é, complementarmente, utilizado em conjunto com os conectores Datasource. Nos conectores é possível adicionar as variáveis do Datasource e atribuir valores gerados ao longo da execução do fluxo. Para mais detalhes, consulte a seção Conector Datasource ou a documentação de conectores Datasource.

Execução de Datasource

Após configurar o Datasource, ele poderá ser executado a qualquer momento clicando no botão Executar. Se a execução for bem-sucedida, os resultados serão exibidos em formato de tabela, incluindo o tipo de dado de cada coluna. Para visualizar os resultados no formato JSON, basta clicar no botão de mesmo nome.

Clique em Exportar CSV para realizar o download dos resultados como um arquivo CSV.

Conector Datasource

O conector Datasource permite que fluxos utilizem dados diretamente de datasources configurados no ambiente. Para utilizá-lo, é necessário que já existam datasources configuradas. Caso ainda não tenha, acesse a seção Gerenciamento de Datasources para entender como criar um novo.

Com o conector Datasource - Consultar Dados, é possível executar o datasource selecionado e utilizar seus resultados no contexto do fluxo em que o conector foi acionado.

Se o datasource possuir variáveis, insira as variáveis e seus respectivos valores na tabela de parâmetros Variáveis de Entrada na configuração do conector.

Em caso de erro, pode-se optar por gerar uma exceção, interrompendo a execução do fluxo, ou permitir que ele continue. Caso seja escolhida a opção para gerar uma saída com erro, recomenda-se tratar esses erros dentro do fluxo para evitar problemas no processamento, visto que o fluxo não será interrompido nestes casos.

Os conectores de datasource permitem a interação direta entre um fluxo e um banco de dados externo, possibilitando a execução de consultas e a recuperação de dados. Esses dados podem ser utilizados no fluxo exatamente como estão no banco ou transformados pelo datasource para atender a necessidades específicas.

Atualmente, está disponível apenas o conector Datasource - Consultar Dados, que permite executar consultas em datasources configurados e integrar os resultados ao contexto do fluxo. Clique aqui para saber mais sobre estes conectores.

Visualização do Datasource

A ferramenta de datasource permite que usuários acessem uma visualização isolada do datasource, liberando apenas a execução e visualização dos dados retornados da consulta, e sem o acesso a modificação da consulta ou da transformação de dados.

Para acessar esta visualização, acesse a listagem de datasources, e, em um datasource configurado, clique no botão Visualizar. A partir desta visualização usuários poderão executar a consulta, visualizar os resultados tabelados ou em JSON, exportar estes resultados para CSV, e, caso necessário, disponibilizar o botão Editar para que a consulta seja modificada.

Boas práticas no uso da funcionalidade

O uso eficiente de datasources no Workspace Floui é essencial para sua operação. Seguir boas práticas ajuda a otimizar a configuração, organização e execução de datasources, visando que processos possam escalar de forma saudável. Abaixo, apresentamos algumas recomendações para maximizar o uso da ferramenta.

• Utilize nomes claros e descritivos ao criar datasources e variáveis.

• Agrupe datasources em categorias (grupos) para manter o Workspace Floui organizado.

• Ao configurar o campo Query SQL, revise a consulta que será realizada para garantir que esteja otimizada e adequada ao seu contexto.

• Teste as suas consultas utilizando o botão Executar, verificando se os resultados retornados estão conforme a sua necessidade e no formato esperado, visto que não é necessário salvar o datasource para executá-lo. Entretanto, certifique-se de salvar o seu datasource após concluir as suas modificações.

• Lembre-se de realizar a manutenção dos conectores Datasource usados no fluxo após realizar alterações no datasource em que o conector está utilizando.

• No Conector Datasource - Consultar Dados configure o campo Em caso de erro para tratar cenários de erro na consulta de datasource, escolhendo se o fluxo deve ser interrompido, ou se deve gerar uma saída com erro e continuar a execução. Neste último caso, lembre-se de tratar os erros que podem decorrer das consultas dentro do fluxo.