Criar um índice do Elasticsearch

Dois conceitos muito importantes no Elasticsearch são documentos e índices.

Um documento é uma coleção de campos com seus respectivos valores. Para trabalhar com o Elasticsearch, você precisa organizar seus dados em documentos e, em seguida, adicionar todos os seus documentos a um índice. Você pode pensar em um índice como uma coleção de documentos armazenados em um formato altamente otimizado, projetado para realizar buscas eficientes.

Se você já trabalhou com outros bancos de dados, deve saber que muitos deles exigem uma definição de esquema, que é essencialmente uma descrição de todos os campos que você deseja armazenar e seus respectivos tipos. Um índice do Elasticsearch pode ser configurado com um esquema, se desejado, mas também pode derivar automaticamente o esquema dos próprios dados. Nesta seção, você deixará o Elasticsearch determinar o esquema por conta própria, o que funciona muito bem para tipos de dados simples, como texto, números e datas. Mais tarde, quando você for apresentado a tipos de dados mais complexos, aprenderá como fornecer definições de esquema explícitas.

Criar o índice

Veja como criar um índice do Elasticsearch usando a biblioteca cliente Python:

Neste exemplo, self.es é uma instância da classe Elasticsearch , que neste tutorial é armazenada na classe Search em search.py. Uma implementação do Elasticsearch pode ser usada para armazenar vários índices, cada um identificado por um nome como my_documents no exemplo acima.

Os índices também podem ser excluídos:

Se você tentar criar um índice com um nome que já esteja atribuído a um índice existente, você receberá um erro. Às vezes, é útil criar um índice que exclua automaticamente uma instância anterior do índice, caso ela exista. Isso é especialmente útil durante o desenvolvimento de um aplicativo, pois provavelmente você precisará regenerar um índice várias vezes.

Vamos adicionar um método auxiliar create_index() em search.py. Abra este arquivo no seu editor de código e adicione o seguinte código na parte inferior, mantendo o conteúdo existente como está:

O método create_index() primeiro exclui um índice com o nome my_documents. A opção ignore_unavailable=True impede que esta chamada falhe quando o nome do índice não for encontrado. A linha seguinte no método cria um índice totalmente novo com esse mesmo nome.

Adicionar documentos ao índice

Na biblioteca cliente Elasticsearch para Python, um documento é representado como um dicionário de campos chave/valor. Os campos que contêm um valor de texto são indexados automaticamente para pesquisa de texto completo e por palavra-chave, mas, além de textos, você pode usar outros tipos de campo, como números, datas e valores booleanos, que também são indexados para operações eficientes, como filtragem. Você também pode construir estruturas de dados complexas nas quais um campo é definido como uma lista ou um dicionário com subitens.

• Saiba mais sobre os tipos do Elasticsearch.

Para inserir um documento em um índice, o método index() do cliente Elasticsearch é usado. Por exemplo:

O valor retornado pelo método index() é a resposta retornada pelo serviço Elasticsearch. A informação mais importante retornada nesta resposta é um item com um nome de chave _id, representando o identificador único que foi atribuído ao documento quando ele foi inserido no índice. O identificador pode ser usado para recuperar, excluir ou atualizar o documento.

Agora que você já sabe como inserir um documento, vamos continuar criando uma biblioteca de funções auxiliares úteis em search.py. com um novo método insert_document() para a classe Search . Adicione este método ao final do arquivo search.py:

O método aceita o cliente Elasticsearch e um documento do chamador e insere o documento no índice my_documents , retornando a resposta do serviço.

Importando documentos de um arquivo JSON

Ao configurar um novo índice do Elasticsearch, você provavelmente precisará importar um grande número de documentos. Para este tutorial, o projeto inicial inclui um arquivo data.json com alguns dados em formato JSON. Nesta seção, você aprenderá como importar todos os documentos contidos neste arquivo para o índice.

A estrutura dos documentos incluídos no arquivo data.json é a seguinte:

• name: o título do documento
• url: um URL para o documento hospedado em um site externo
• summary: um breve resumo do conteúdo do documento
• content: o corpo do documento
• created_on: data de criação
• updated_atData de atualização (pode estar ausente se o documento nunca foi atualizado)
• category: a categoria do documento, que pode ser github, sharepoint ou teams
• rolePermissions: uma lista de permissões de função

Neste ponto, recomendamos que você abra o arquivo data.json em seu editor para se familiarizar com os dados com os quais você irá trabalhar.

Em essência, importar um grande número de documentos não é diferente de importar um único documento dentro de um laço `for`. Para importar todo o conteúdo do arquivo data.json , você pode fazer algo assim:

Embora essa abordagem funcione, ela não é escalável. Se você precisasse inserir um número muito grande de documentos, precisaria fazer inúmeras chamadas ao serviço Elasticsearch. Infelizmente, cada chamada à API acarreta um custo de desempenho, e o serviço também possui limites de taxa que impedem a realização de um grande número de chamadas em um curto período. Por esses motivos, é melhor usar o recurso de inserção em lote do serviço Elasticsearch, que permite que várias operações sejam comunicadas ao serviço em uma única chamada de API.

O método insert_documents() mostrado abaixo, que você deve adicionar na parte inferior do arquivo search.py, usa o método bulk() para inserir todos os documentos em uma única chamada:

O método aceita uma lista de documentos. Em vez de adicionar cada documento separadamente, ele monta uma única lista chamada operations e então passa a lista para o método bulk() . Para cada documento, duas entradas são adicionadas à lista operations :

• Uma descrição da operação a ser realizada, definida como index, com o nome do índice fornecido como argumento.
• Os dados reais do documento

Ao processar uma solicitação em lote, o serviço Elasticsearch percorre a lista de operações desde o início e executa as operações solicitadas.

• Saiba mais sobre o método bulk() na documentação.

Regenerando o Índice

Ao realizar este tutorial, você precisará regenerar o índice algumas vezes. Para simplificar essa operação, adicione um método reindex() ao search.py:

Este método combina os métodos create_index() e insert_documents() criados anteriormente, de modo que com uma única chamada o índice antigo pode ser destruído (se existir) e um novo índice construído e repovoado.

Para tornar este método mais fácil de invocar, vamos expô-lo através do comando flask . Abra o arquivo app.py no seu editor de código e adicione a seguinte função no final:

O decorador @app.cli.command() diz ao framework Flask para registrar esta função como um comando personalizado, que estará disponível como flask reindex. O nome do comando é retirado do nome da função, e a docstring é incluída aqui porque o Flask a usa na documentação --help .

A resposta da função reindex() , que por sua vez é a resposta do método bulk() do cliente Elasticsearch, contém alguns itens úteis que podem ser usados para construir uma boa mensagem de status. Em particular, response['took'] é a duração da chamada em milissegundos e response['items'] é uma lista dos resultados individuais de cada operação, que não é realmente útil diretamente, mas o comprimento da lista fornece uma contagem de documentos inseridos.

Veja como isso fica executando flask --help a partir de uma sessão de terminal, certificando-se de que o ambiente virtual do Python esteja ativado (se a sua sessão de terminal ainda estiver executando o aplicativo Flask, você pode abrir uma segunda janela de terminal). Na parte final da tela de ajuda, você deverá ver a opção reindex incluída como um comando disponível, juntamente com outras opções fornecidas pelo framework Flask:

Agora, quando você quiser gerar um índice limpo, tudo o que você precisa fazer é executar flask reindex.