Storage

objetivo/resumo o conector storage da fluid oferece uma interface simplificada e padronizada para armazenar, recuperar, listar e deletar dados de forma eficiente e escalável no armazenamento dedicado ao seu tenant/workspace ele integra se perfeitamente com as soluções de integração da fluid, permitindo que você gerencie informações estruturadas por meio de identificadores únicos, sem demandar um armazenamento externo e se preocupar com gerenciamento de banco de dados cada identificador pode conter um ou mais conjuntos de dados organizados em pares de chave ( key ) e valor ( value ) , facilitando a organização e o acesso aos dados conforme necessário criando conexão para o conector storage para utilizar o conector storage, é necessário criar uma conexão e, em seguida, configurar o fluxo abaixo estão as instruções detalhadas criando conexão acessar o painel principal faça login na plataforma fluid no painel à esquerda, navegue até a opção "conexões" e clique nela iniciar nova conexão no canto superior direito, clique em "nova conexão" seleção do tipo de conexão na tela de configuração, localize "configure uma nova conexão" e selecione "storage" da lista suspensa nome da conexão forneça um nome descritivo para a conexão no campo "nome" descrição da conexão no campo "descrição", forneça uma breve descrição da conexão chave/key insira a chave/key da tabela do storage que será utilizada pela api pode ser criada de acordo com o nome que você desejar operações 1\ salvar descrição a operação de salvar permite que você armazene informações novas, atualize informações existentes, ou acrescente novas informações associadas a um identificador específico como funciona ao salvar, você fornece um identificador único que será usado para agrupar os conjuntos de informações que deseja armazenar cada conjunto consiste em pares de chave ( key ) e valor ( value ), que representam os dados que você quer guardar ao salvar habilitando o campo salvar como append os valores que informar serão acrescentados ao identificador caso ele já exista exemplo prático imagine que você está salvando informações de clientes o identificador pode ser o número do cliente, e os pares de key/values podem incluir nome, endereço e e mail 2\ recuperar chave descrição a operação de recuperar chave permite que você obtenha uma chave específica que esteja salva no identificador se a chave não existir, retornará uma mensagem informando que a chave não existe \\ como funciona ao fornecer o identificador previamente usado para salvar as informações e informar a chave específica que deseja retornar, você pode recuperar o valor salvo para a chave informada dentro do identificador exemplo prático se você salvou informações do cliente com o identificador 00001 1 e a chave nome e valor cliente de testes , ao utilizar a operação de recuperar chave com o identificador 00001 1 e a chave nome , você obterá o valor cliente de testes que foi salvo anteriormente para a chave nome { "id" "00001 1", "table key" " ", "values" { "nome" "cliente de testes" } } 3\ verificar chave descrição a operação de verificar chave, verifica se a chave existe no identificador previamente informado do storage retorna true se a chave existir e false se não existir como funciona ao fornecer o identificador previamente usado para salvar as informações e informar a chave específica que deseja verificar, será retornado um json informando se a chave existe ou não exemplo prático se você salvou informações do cliente com o identificador 00001 1 e a chave nome , ao utilizar a operação verificar chave com o identificador 00001 1 e a chave nome , você obterá dentro da tag exist o valor true { "id" "00001 1", "table key" " ", "values" { "exist" true } } 4\ listar descrição a operação de listar permite que você veja todos os identificadores disponíveis juntamente com seus conjuntos de key/values associados como funciona ao utilizar a operação de listar, você receberá uma lista de todos os identificadores armazenados no banco de dados, juntamente com os conjuntos de key/values associados a cada um deles exemplo prático se você está gerenciando informações de vários clientes, a operação de listar fornecerá uma visão geral de todos os clientes existentes, cada um com suas respectivas informações armazenadas \[ { "id" "00001 1", "table key" "clientes", "values" { "cliente" "fulano de tal", "endereço" "rua sem saída, n 10, centro", "email" "fulano\@exemplo com" } }, { "id" "00002 1", "table key" "clientes", "values" { "cliente" "ciclano de tal", "endereço" "rua teste, n 20, centro", "email" "ciclano\@exemplo com" } } ] 5\ listar com prefixo descrição a operação listar com prefixo verifica no storage todos os identificadores que iniciem com o prefixo informado retorna todos os identificadores encontrados e seus respectivos conjuntos de chaves e valores como funciona ao fornecer o prefixo do identificador, será retornado um json com todos os identificadores que iniciem com esse prefixo exemplo prático se você salvou um cliente com o identificador 00001 1 e outro com o identificador 00002 1 , e deseja buscar todos os identificadores que iniciem com o prefixo 0000 , ao utilizar a operação listar com prefixo, passando o prefixo 0000 , serão listados tanto o cliente 00001 1 quanto o cliente 00002 1 \[ { "id" "00001 1", "table key" "clientes", "values" { "cliente" "fulano de tal", "endereço" "rua sem saída, n 10, centro", "email" "fulano\@exemplo com" } }, { "id" "00002 1", "table key" "clientes", "values" { "cliente" "ciclano de tal", "endereço" "rua teste, n 20, centro", "email" "ciclano\@exemplo com" } } ] 6\ deletar descrição a operação de deletar permite que você remova completamente um identificador específico e todos os seus conjuntos de key/values associados como funciona ao fornecer o identificador que deseja excluir, todos os dados associados a esse identificador serão permanentemente removidos do armazenamento exemplo prático se um cliente não é mais ativo e você deseja remover todas as informações dele do sistema, você pode usar a operação de deletar com o identificador desse cliente para eliminar todas as informações associadas 7\ deletar chave descrição a operação deletar chave permite excluir uma chave específica que esteja salva em um identificador após a execução, será retornada a quantidade de registros afetados no storage como funciona ao fornecer o identificador previamente utilizado para salvar as informações, junto com a chave específica que deseja deletar, a chave será removida do identificador exemplo prático se você salvou informações de um cliente com o identificador 00001 1 e a chave nome , ao utilizar a operação deletar chave com o identificador 00001 1 e a chave nome , essa chave será deletada, e será retornada a quantidade de registros afetados { "last inserted id" 0, "rows affected" 1 } 8\ limpar storage descrição a operação limpar storage permite deletar todos os identificadores de uma determinada conexão após a execução, será retornada a quantidade de registros afetados no storage como funciona ao selecionar a operação o conector irá efetuar a limpeza completa do storage com base na conexão selecionada exemplo prático 9\ ler e deletar descrição a operação recuperar e deletar permite que você recupere os dados de um identificador específico e o remova em uma única operação atômica esta operação garante que você obtenha os dados antes da exclusão, evitando a perda de informações importantes como funciona ao fornecer o identificador que deseja ler e deletar, o sistema primeiro recupera todos os dados associados a esse identificador e, em seguida, remove o permanentemente do armazenamento esta operação é executada como uma transação atômica, garantindo consistência dos dados exemplo prático se você tem um pedido temporário no storage que precisa ser processado e removido após o processamento, você pode usar a operação ler e deletar com o identificador desse pedido para obter os dados e removê lo do storage em uma única operação exemplo de retorno { "id" "00001 1", "table key" "pedidos temporarios", "values" { "cliente" "fulano de tal", "produto" "laptop", "quantidade" 1, "valor" "2500 00" } } vantagens operação atômica garante que a leitura e exclusão aconteçam em uma única transação recuperação de dados permite obter os dados antes da exclusão consistência evita condições de corrida em ambientes concorrentes eficiência realiza duas operações em uma única consulta ao banco caso de uso ideal para cenários onde você precisa processar dados armazenados temporariamente e removê los após o processamento 10\ salvar em lote descrição esta operação permite o processamento de múltiplos registros de uma só vez é a forma mais eficiente de lidar com grandes volumes de dados (como listas de centenas de produtos ou clientes), garantindo alta velocidade e estabilidade na automação como funciona ao receber uma lista de itens, o sistema aplica um processo de otimização automática antes da gravação consolidação de dados se houver registros com o mesmo identificador (id) no lote, o sistema mescla as informações e salva apenas o estado final consolidado, evitando redundâncias processamento em massa em vez de realizar centenas de comunicações individuais com o banco de dados, o sistema agrupa as informações e as processas de forma massiva, o que reduz drasticamente o tempo total de execução flexibilidade você decide se quer que a nova informação substitua a antiga (overwrite) ou se deve apenas adicionar novos detalhes ao que já existe (append) exemplo prático ao processar uma lista de 500 pedidos via integração, o sistema organiza os dados, resolve possíveis duplicatas de id presentes no lote e persiste todas as informações, garantindo que sua automação seja rápida e o banco de dados permaneça íntegro exemplo de payload válido (input) \[ { "id" "user 001", "append" true, // append adiciona novos dados ao registro existente para user 001 "values" { "status" "ativo", "tag" "premium" } }, { "id" "user 002", "append" false, // overwrite substitui qualquer dado existente para user 002 "values" { "nome" "joão silva", "email" "joao\@email com" } }, { "id" "user 001", "append" true, "values" { "last login" "2023 10 27" } } ] note que user 001 aparece duas vezes os dados serão mesclados em um único registro final exemplo de payload inválido \[ { "id" "", "append" true, "values" { "data" "erro sem id" } }, { "id" "user 999", "values" { "error" "faltando campo append" } } ] exemplo de retorno { "total items" 1000, "processed" 1000, "successes" 998, "errors" 2, "details" { "item errors" \[{ "error" "id field cannot be empty", "offset" 50 }], "append" { "success count" 500, "total" 500, "processed" 500, "errors" 0, "batch errors" \[] }, "overwrite" { "success count" 498, "total" 500, "processed" 500, "errors" 2, "batch errors" \[ { "error" "invalid json format", "count" 2, "offset" 100, "ids" \["user 101", "user 102"] } ] } } } explicação dos campos de retorno total items quantidade total de registros enviados no payload original processed quantidade de itens que o sistema conseguiu analisar e processar, independentemente do resultado final successes número de registros que foram processados e gravados com sucesso errors soma de erros de validação estrutural e falhas na escrita no banco details item errors lista falhas no formato do json enviado (ex falta de campos obrigatórios) details append / overwrite detalhamento técnico segregado por tipo de operação por que os números totais podem ser diferentes dos comandos executados? para otimizar a performance, realizamos um processo inteligente de compactação se você enviar 10 atualizações para o mesmo id em um único lote, o sistema executará apenas um comando no banco de dados com o estado final no entanto, o retorno mostrará successes 10, pois todos os seus pedidos originais foram processados com sucesso vantagens alta performance otimizado para processar grandes volumes de dados com latência mínima inteligência de dados consolida informações repetidas no lote automaticamente, sem necessidade de lógica complexa no fluxo eficiência operacional reduz o tráfego de rede e o consumo de recursos rastreabilidade retorno detalhado sobre o status de processamento de cada lote caso de uso sincronização de catálogos, ingestão de dados de sensores/iot, atualizações em massa de status de pedidos e migrações rápidas entre sistemas 11\ deletar em lote (delete bulk) descrição esta operação permite a remoção de múltiplos registros do storage de uma só vez, utilizando uma lista de identificadores é a forma mais performática de realizar limpezas massivas de dados ou expurgar grandes volumes de informações obsoletas como funciona ao receber uma lista de identificadores (ids), o sistema processa a exclusão de forma otimizada processamento em massa em vez de executar um comando de exclusão para cada item individualmente, o sistema agrupa os ids e realiza a operação de forma massiva diretamente no banco de dados divisão em sub lotes para garantir a estabilidade e evitar sobrecarga, o sistema divide automaticamente listas muito grandes em grupos de 100 itens por vez foco em performance a operação é executada com baixa latência, focando na liberação rápida de espaço e recursos do armazenamento exemplo prático se você precisar remover 1 000 registros de logs temporários ou pedidos cancelados antigos, basta enviar a lista de ids o sistema cuidará de agrupar as remoções para que o processo seja concluído em instantes, sem gerar centenas de chamadas individuais exemplo de payload válido (input) \["user 001", "user 002", "old order 123", "temp cache 99"] o payload deve ser um array simples contendo apenas os textos dos identificadores (ids) que deseja remover exemplo de payload inválido \[ { "id" "user 001" }, // erro o sistema espera um array de textos (strings), não de objetos "", null ] exemplo de retorno { "total" 100, "processed" 100, "successes" 98, "errors" 2, "rows affected" 98, "batch errors" \[ { "error" "database connection refused", "count" 2, "offset" 50, "ids" \["id 051", "id 052"] } ] } explicação dos campos de retorno total quantidade total de ids que você enviou no payload original processed quantidade de ids que o sistema analisou e conseguiu processar, independentemente do resultado final successes número total de ids para os quais o comando de exclusão foi executado com sucesso errors quantidade de registros que falharam durante a tentativa de exclusão (ex falha de comunicação com o banco) rows affected indica o número real de registros que foram efetivamente removidos do armazenamento por que os números totais podem ser diferentes de rows affected? o campo successes reflete que o comando para deletar aquele id foi enviado e aceito pelo sistema já o campo rows affected mostra quantos registros foram de fato removidos do banco por exemplo, se você tentar deletar um id que não existe mais ou enviar o mesmo id duas vezes no lote, o comando será um "sucesso" técnico, mas não aumentará o contador de registros afetados no banco de dados vantagens alta performance remoção em massa com mínima latência e tráfego de rede escalabilidade suporta listas extensas através do processamento automático por sub lotes rastreabilidade informa quais grupos de ids falharam, facilitando auditorias ou novas tentativas otimização de recursos libera espaço de armazenamento de forma rápida e eficiente caso de uso limpeza de logs e dados temporários, expurgo de registros antigos por política de retenção, revogação massiva de tokens ou remoção de dados após finalização de processos 12\ listar com paginação descrição esta operação permite recuperar grandes conjuntos de dados de forma organizada e em partes (páginas) é essencial para exibir listas de informações em interfaces ou processar registros em etapas, evitando sobrecarga de memória e garantindo a fluidez do sistema como funciona o sistema utiliza dois parâmetros principais para navegar pelos dados de uma tabela e um opcional para filtrar por prefixo limite (limit) define o número máximo de registros que você deseja receber em uma única chamada deslocamento (offset) indica quantos registros o sistema deve "pular" antes de começar a listar, permitindo que você navegue entre as páginas de resultados prefixo (prefix) (opcional) permite filtrar os resultados para incluir apenas os identificadores que começam com um determinado prefixo, facilitando a segmentação dos dados consistência os dados são retornados em uma ordem fixa (por identificador), garantindo que você não veja itens repetidos ou perca registros ao mudar de página exemplo prático se você possui 1 000 clientes cadastrados e deseja exibir 50 por vez em seu dashboard, basta definir o limit como 50 para visualizar a "página 2", você mantém o limit em 50 e define o offset como 50 (pulando os primeiros 50 que já foram vistos) se quiser listar apenas os clientes cujo identificador começa com "cli ", basta usar o parâmetro prefix com o valor "cli " o sistema retornará apenas os registros que correspondem a esse critério, facilitando a navegação em grandes volumes de dados exemplo de parametrização \[imagem 1]\(aurelio aqui a imagem que lhe enviei) dica para percorrer toda a base, basta incrementar o offset somando o valor do limit a cada nova consulta exemplo de retorno { "items" \[ { "id" "cli 001", "table key" "clientes ativos", "values" { "nome" "empresa a", "segmento" "tecnologia" } }, { "id" "cli 002", "table key" "clientes ativos", "values" { "nome" "empresa b", "segmento" "varejo" } } ], "count" 2, "limit" 50, "offset" 0, "total items" 1000, "total pages" 20, "current page" 1, "has next page" true, "has previous page" false } explicação dos campos de retorno items lista contendo os dados detalhados dos registros encontrados na página atual count quantidade de registros retornados nesta chamada específica limit o limite que foi aplicado à consulta offset o ponto de partida (deslocamento) utilizado para gerar esta página total items o número total de registros disponíveis na tabela, independentemente da paginação total pages o número total de páginas disponíveis, calculado com base no total de itens e no limite current page a página atual que está sendo visualizada, calculada a partir do offset e do limite has next page indica se existe uma próxima página de resultados além da atual has previous page indica se existe uma página anterior de resultados antes da atual vantagens navegação otimizada permite percorrer milhões de registros sem perda de performance economia de recursos carrega apenas o necessário por vez, mantendo a aplicação leve e rápida previsibilidade a ordenação garantida evita confusão visual ao paginar os dados escalabilidade ideal para alimentar grids, tabelas e processos de exportação de dados em massa caso de uso criação de listas paginadas em painéis administrativos, relatórios de histórico, exportação de dados em lotes (e mail marketing, faturamento) e busca de logs por categorias caso de uso gerenciamento de pedidos pendentes no erp cenário você está implementando uma integração de pedidos entre o seu e commerce e erp se o cliente associado ao pedido não estiver cadastrado no erp, o pedido não pode ser registrado e deve ser salvo temporariamente em um storage até que o cliente seja cadastrado e o pedido reenviado fluxo do caso de uso 1\ cadastro de pedido no erp objetivo tentar cadastrar um pedido no erp passos enviar dados do pedido o sistema envia dados do pedido para o erp verificar resposta do erp se o cliente associado ao pedido já estiver cadastrado, o pedido é registrado com sucesso se o cliente não estiver cadastrado, o erp retorna um erro exemplo pedido pedido123 cliente cliente456 (não cadastrado no erp) produto laptop quantidade 1 2\ salvar pedido no storage objetivo se o pedido não puder ser cadastrado no erp devido ao cliente não estar registrado, salvar o pedido no storage para processamento futuro passos definir identificador use um identificador único para o pedido, como o id do pedido (pedido123) salvar dados chaves e valores cliente cliente456 produto laptop quantidade 1 operação salvar 3\ listar pedidos salvos no storage objetivo recuperar todos os pedidos que foram salvos no storage para tentar reenviá los ao erp passos executar operação de listar liste todos os identificadores e seus pares chave/valor armazenados operação listar exemplo de resultado identificador pedido123 cliente cliente456 produto laptop quantidade 1 objetivo listar os pedidos pendentes de envio e direcionar para o fluxo de reenvio do pedido 4\ deletar pedido do storage objetivo após o pedido ser cadastrado com sucesso no erp, remova o do storage para evitar processamento duplicado passos definir identificador use o mesmo identificador do pedido (pedido123) operação deletar resumo das funções salvar adiciona ou substitui pares chave/valor para um identificador recuperar obtém pares chave/valor para um identificador específico listar mostra todos os identificadores e seus pares chave/valor deletar remove um identificador e seus dados do storage dicas e considerações escolha de conexão certifique se de selecionar a conexão apropriada para o tipo de dados que está manipulando uso de identificadores use identificadores únicos para evitar sobrescrever dados inadvertidamente conclusão o conector de storage da fluid é uma ferramenta essencial para a gestão eficiente de dados, oferecendo operações intuitivas e robustas para armazenar, recuperar, listar e deletar informações sem se preocupar em gerenciar banco de dados ele se integra perfeitamente com outras soluções da fluid, proporcionando uma experiência de uso coesa e simplificada com sua capacidade de gerenciar dados estruturados através de identificadores únicos, o conector de storage não apenas facilita a organização dos dados, mas também garante que eles sejam acessíveis e manipuláveis conforme as necessidades de seu aplicativo ou sistema independentemente da complexidade dos dados, o conector de storage oferece uma solução confiável e escalável para todas as suas necessidades de armazenamento