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

Criação de conta de serviço DataURI para Datasources

## 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](/guia/configuracoes/grupos.md) 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](#pre-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](#pre-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](#transformacao-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](#uso-de-variaveis-em-datasource).

Implementação de transformação em consulta

## 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: ```javascript 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](#conector-datasource) ou a documentação de [conectores Datasource](/guia/conectores/categorias/servicos-do-floui/floui-datasource.md). ## 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](#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](/guia/conectores/categorias/servicos-do-floui/floui-datasource.md) 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. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.floui.io/guia/ferramentas/construcao/floui-datasources.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.