Rivia ES Cloud

Uma biblioteca JavaScript para simplificar operações com o Elasticsearch Cloud, fornecendo uma interface limpa e intuitiva para as operações mais comuns.

📋 Descrição

A Rivia ES Cloud é uma biblioteca wrapper que simplifica a interação com o Elasticsearch Cloud, oferecendo funções de alto nível para operações CRUD, consultas e gerenciamento de documentos. A biblioteca utiliza o cliente oficial do Elasticsearch e adiciona funcionalidades úteis como formatação automática de resultados, paginação simplificada e mapeamento de campos.

🚀 Instalação

npm install rivia-es-cloud

⚙️ Configuração

Antes de usar a biblioteca, você precisa configurar as seguintes variáveis de ambiente:

# ID do serviço Elasticsearch Cloud
ELASTIC_CLOUD_ID=your_cloud_id_here

# Usuário de acesso (opcional, padrão: 'elastic')
ELASTIC_CLOUD_USER=your_username

# Senha de acesso
ELASTIC_CLOUD_PWD=your_password
# OU
ELASTIC_CLOUD_PASSWORD=your_password

📖 Uso Básico

import { insert, get, query, update, delete: remove } from 'rivia-es-cloud';

// Inserir um documento
const newUser = await insert('users', {
    name: 'João Silva',
    email: '[email protected]',
    age: 30
});

// Buscar um documento por ID
const user = await get('users', 'document_id_here');

// Atualizar um documento
const updatedUser = await update('users', 'document_id_here', {
    age: 31
});

// Deletar um documento
await remove('users', 'document_id_here');

🔧 Funções Disponíveis

Operações CRUD

insert(index, object)

Insere um novo documento no Elasticsearch.

• Parâmetros:
  • index (string): Nome do índice
  • object (object): Objeto a ser inserido
• Retorna: Objeto inserido com ID gerado automaticamente
• Exemplo:

const result = await insert('products', {
    name: 'Produto A',
    price: 99.99,
    category: 'eletrônicos'
});
// result.id contém o ID gerado pelo Elasticsearch

get(index, id)

Recupera um documento específico por ID.

• Parâmetros:
  • index (string): Nome do índice
  • id (string): ID do documento
• Retorna: Documento encontrado com ID incluído
• Exemplo:

const product = await get('products', 'abc123');
// product contém todos os campos + id

update(index, id, object)

Atualiza um documento existente.

• Parâmetros:
  • index (string): Nome do índice
  • id (string): ID do documento
  • object (object): Campos a serem atualizados
• Retorna: Objeto atualizado
• Exemplo:

const updated = await update('products', 'abc123', {
    price: 89.99,
    lastModified: new Date()
});

upsert(index, id, object)

Insere um documento se não existir, ou atualiza se já existir.

• Parâmetros:
  • index (string): Nome do índice
  • id (string): ID do documento
  • object (object): Objeto completo
• Retorna: Objeto inserido/atualizado
• Exemplo:

const result = await upsert('products', 'abc123', {
    name: 'Produto A',
    price: 99.99,
    category: 'eletrônicos'
});

delete(index, id)

Remove um documento do índice.

• Parâmetros:
  • index (string): Nome do índice
  • id (string): ID do documento
• Retorna: Resultado da operação de remoção
• Exemplo:

await delete('products', 'abc123');

Operações de Atualização Avançadas

updateByScript(index, id, script)

Atualiza um documento usando um script Painless.

• Parâmetros:
  • index (string): Nome do índice
  • id (string): ID do documento
  • script (object): Script de atualização
• Exemplo:

await updateByScript('products', 'abc123', {
    source: 'ctx._source.price *= 1.1' // Aumenta preço em 10%
});

updateByQuery(index, script, query)

Atualiza múltiplos documentos que correspondem a uma query.

• Parâmetros:
  • index (string): Nome do índice
  • script (object): Script de atualização
  • query (object): Query de filtro
• Exemplo:

await updateByQuery('products', 
    { source: 'ctx._source.category = "promoção"' },
    { match: { price: { lt: 50 } } }
);

Operações de Consulta

query(index, match, pagination, sort, pretty)

Executa uma consulta personalizada no Elasticsearch.

• Parâmetros:
  • index (string): Nome do índice
  • match (object): Query de busca
  • pagination (object, opcional): Parâmetros de paginação
  • sort (array, opcional): Critérios de ordenação
  • pretty (boolean, opcional): Se deve formatar o resultado (padrão: true)
• Retorna: Resultados formatados ou resposta bruta da API
• Exemplo:

const results = await query('products', 
    { match: { category: 'eletrônicos' } },
    { limit: 20, offset: 0 },
    [{ price: 'asc' }]
);

all(index, pagination, sort, pretty)

Recupera todos os documentos de um índice.

• Parâmetros:
  • index (string): Nome do índice
  • pagination (object, opcional): Parâmetros de paginação
  • sort (array, opcional): Critérios de ordenação
  • pretty (boolean, opcional): Se deve formatar o resultado
• Exemplo:

const allProducts = await all('products', 
    { limit: 100, page: 1 },
    [{ createdAt: 'desc' }]
);

Funções de Apoio

mustMatchAllFields(fields, parameters)

Cria uma query expression para buscar por todos os campos informados.

• Parâmetros:
  • fields (array): Lista de campos para filtro
  • parameters (object): Objeto com valores dos campos
• Retorna: Query expression para filtro
• Exemplo:

// Criar a query expression
const matchQuery = mustMatchAllFields(
    ['name', 'category', 'price'],
    { name: 'produto', category: 'eletrônicos', price: 100 }
);

// Usar a query na função query (modo padrão de uso)
const results = await query('products', matchQuery, {
    limit: 20,
    page: 1
});

// Resultado da query: { bool: { must: [...] } }

📊 Paginação

A biblioteca suporta dois tipos de paginação:

Paginação por Offset/Limit

const results = await query('products', matchQuery, {
    limit: 20,    // Número de resultados por página
    offset: 40    // Número de resultados para pular
});

Paginação por Página

const results = await query('products', matchQuery, {
    limit: 20,    // Número de resultados por página
    page: 3       // Número da página (começa em 1)
});

🔍 Exemplos de Queries

Busca Simples

// Buscar produtos por categoria
const electronics = await query('products', {
    match: { category: 'eletrônicos' }
});

Busca com Múltiplos Critérios

// Buscar produtos com preço entre 50 e 200
const affordableProducts = await query('products', {
    range: {
        price: {
            gte: 50,
            lte: 200
        }
    }
});

Busca com Filtros Combinados

// Buscar produtos eletrônicos com preço menor que 100
const query = {
    bool: {
        must: [
            { match: { category: 'eletrônicos' } },
            { range: { price: { lt: 100 } } }
        ]
    }
};

const results = await query('products', query);

📝 Formato dos Resultados

Quando pretty = true (padrão), os resultados são formatados da seguinte forma:

{
    items: [
        { id: 'doc1', name: 'Produto A', price: 99.99 },
        { id: 'doc2', name: 'Produto B', price: 149.99 }
    ],
    total: 2,
    aggs: {} // Agregações se houver
}

🛠️ Dependências

• @elastic/elasticsearch: Cliente oficial do Elasticsearch
• lodash: Utilitários para manipulação de objetos e arrays
• luxon: Biblioteca para manipulação de datas

🔧 Desenvolvimento

Scripts Disponíveis

# Executar testes
npm test

# Executar linting
npm run lint

# Preparar ambiente (inclui husky para git hooks)
npm run prepare

Estrutura do Projeto

rivia-es-cloud/
├── index.js          # Funções principais da biblioteca
├── utils.js          # Funções utilitárias
├── package.json      # Dependências e configurações
└── README.md         # Este arquivo

📄 Licença

ISC License

👥 Autores

• Backend Team: [email protected]
• Rivia Development: https://bitbucket.org/riviadev

🐛 Reportar Problemas

Para reportar bugs ou solicitar novas funcionalidades, acesse: https://bitbucket.org/riviadev/rivia-es-cloud/issues

📚 Recursos Adicionais

• Documentação do Elasticsearch
• Cliente JavaScript do Elasticsearch
• Query DSL do Elasticsearch