DEV Community: Bruno Flegler Dal'Col

#009: Como definir um template para um índice

Bruno Flegler Dal'Col — Thu, 10 Feb 2022 01:59:21 +0000

No artigo anterior #008: Como definir o mapeamento no Elasticsearch definimos um mapping diretamente no índice, porém podemos criar um template e criar o índice a partir dele. Essa estratégia é útil quando criamos índices temporais.

PUT /_template/customers
{
  "index_patterns": [
    "customers_*"
  ],
  "aliases": {
    "customers": {}
  },
  "mappings": {
    "properties": {
      "id": {
        "type": "text"
      },
      "age": {
        "type": "integer"
      },
      "email": {
        "type": "text"
      },
      "name": {
        "type": "text"
      },
      "createdAt": {
        "type": "date"
      }
    }
  }
}

O campo index_patterns será usado para corresponder aos nomes dos índices durante a criação. Exemplo: customers_2022_02, customers_2022_03, uma vez que o nome do índice corresponde ao pattern customers_* o índice é criado com o mapping definido no template.

PUT /customers_2022_02

GET /customers_2022_02/_mapping
{
  "customers_2022_02" : {
    "mappings" : {
      "properties" : {
        "age" : {
          "type" : "integer"
        },
        "createdAt" : {
          "type" : "date"
        },
        "email" : {
          "type" : "text"
        },
        "id" : {
          "type" : "text"
        },
        "name" : {
          "type" : "text"
        }
      }
    }
  }
}

O campo aliases também é bem útil quando queremos buscar em todos índices criados a partir do template. Exemplo: customers_2022_02, customers_2022_03, podemos pesquisar em ambos índices utilizando apenas o nome customers.

GET /customers/_search
{
  "query": {
    "match_all": {}
  }
}

Sua vez de praticar, te vejo em breve.

#008: Como definir o mapeamento no Elasticsearch

Bruno Flegler Dal'Col — Mon, 30 Aug 2021 00:23:21 +0000

O mapeamento defini como cada campo do documento será indexado. Uma vez que não é definido o tipo do campo o Elasticsearch irá definir dinamicamente. Podemos ver o mapping criado no nosso índice customers.

GET /customers/_mapping

{
  "customers" : {
    "mappings" : {
      "properties" : {
        "age" : {
          "type" : "long"
        },
        "createdAt" : {
          "type" : "date"
        },
        "email" : {
          "type" : "text",
          "fields" : {
            "keyword" : {
              "type" : "keyword",
              "ignore_above" : 256
            }
          }
        },
        "id" : {
          "type" : "long"
        },
        "name" : {
          "type" : "text",
          "fields" : {
            "keyword" : {
              "type" : "keyword",
              "ignore_above" : 256
            }
          }
        }
      }
    }
  }
}

Os tipos sugeridos pelo Elasticsearch:

Campo	Tipo	Valor
age	long	18
createdAt	date	"2021-08-21T03:16:33.116Z"
email	text	"Antonia.Will@gmail.com"
id	long	55
name	text	"Mrs. Mable Ritchie"

⚠️ Atenção:

Uma vez que o índice é definido não podemos mais alterar o tipo do campo, apenas adicionar um campo novo. Da mesma forma não será mais possível indexar um documento com outro formato. Vamos tentar indexar um documento com o id a abcdef.

POST /customers/_doc
{
  "id": "abcdef",
  "name": "Brenda H. Barajas",
  "email": "bredahbarajas@hotmail.com",
  "age": 97,
  "createdAt": "2021-08-29T19:16:33.099Z"
}

O Elasticsearch indica que não é possível transformar abcedf em um valor numérico.

{
  "error" : {
    "root_cause" : [
      {
        "type" : "mapper_parsing_exception",
        "reason" : "failed to parse field [id] of type [long] in document with id 'q64NlHsBLpS_vORe78sd'. Preview of field's value: 'abcdef'"
      }
    ],
    "type" : "mapper_parsing_exception",
    "reason" : "failed to parse field [id] of type [long] in document with id 'q64NlHsBLpS_vORe78sd'. Preview of field's value: 'abcdef'",
    "caused_by" : {
      "type" : "illegal_argument_exception",
      "reason" : "For input string: \"abcdef\""
    }
  },
  "status" : 400
}

Vamos deletar o índice customers e criar ele novamente definindo o mapping antes.

DELETE customers

Agora podemos criar o mapping antes de indexar o primeiro documento.

PUT /customers
{
  "mappings": {
    "properties": {
      "id": {
        "type": "text"
      },
      "age": {
        "type": "integer"
      },
      "email": {
        "type": "text"
      },
      "name": {
        "type": "text"
      },
      "createdAt": {
        "type": "date"
      }
    }
  }
}

Se olharmos o mapping agora o id será do tipo text e conseguiríamos indexar com o valor abcdef.

O mapeamento é um tema complexo, envolve os tipos dos campos e depende de um conhecimento prévio do documento que será indexado para conseguir otimizar as buscas. Com o tempo vamos entender quais tipos são sugeridos para cada tipo de situação.

#007: Paginando resultados na pesquisa do Elasticsearch

Bruno Flegler Dal'Col — Sun, 29 Aug 2021 01:20:25 +0000

Como mencionado no artigo #003: Buscando todos os documentos no Elasticsearch, por padrão ele retorna 10 documentos. Hoje iremos aprender a paginar os resultados.

Vamos usar os parâmetros size que é o total de registros que será retornado e o from que é a quantidade de documentos que serão ignorados, começando como 0. Juntos, as duas propriedades formam a paginação. Dessa forma temos na primeira requisição:

GET customers/_search
{
  "query": {
    "match_all": {}
  },
  "from": 0,
  "size": 10
}

Na segunda requisição será from + size, igual à 0 + 10 = 10:

GET customers/_search
{
  "query": {
    "match_all": {}
  },
  "from": 10,
  "size": 10
}

Na terceira requisição será from + size, igual à 10 + 10 = 20:

GET customers/_search
{
  "query": {
    "match_all": {}
  },
  "from": 20,
  "size": 10
}

E assim por diante, porém por padrão a soma de from + size não pode ultrapassar 10000. É aconselhável usar search_after para essa situação, veremos nos próximos artigos.

⚠️ Atenção:

Evite usar o paginação com muita profundidade, ou seja, o from com um valor muito alto ou solicitar muitos resultados de uma vez. Os registros das páginas anteriores são mantidos em mémoria e podem aumentar o consumo de mémoria e CPU, resultando em degradação do desempenho ou falhas de nó.

Sua vez de praticar, te vejo em breve.

#006: Ordenando resultados na pesquisa do Elasticsearch

Bruno Flegler Dal'Col — Thu, 26 Aug 2021 21:45:28 +0000

Artigo super rápido e fácil. Vamos aprender a ordenar os resultados do Elasticsearch.

GET customers/_search
{
  "query": {
    "match_all": {}
  },
  "sort": [
    {
      "age": "asc"
    }
  ]
}

A ordenação pode ser asc ou desc. Por padrão o Elasticsearch utiliza a propriedade _score: desc, ou seja do maior para o menor. Quando adicionamos qualquer outra propriedade a ordenação é ascendente, do menor para o maior.

⚠️ Atenção:

Uma vez adicionado a ordenação o _score é null, uma vez que não será utilizado a relevância do documento.

O _score é o resultado do cálculo de relevância sobre a sua pesquisa, quanto maior _score mais relevante é o documento, iremos entender melhor nos próximos artigos.

Como podemos observar a ordenação é um array e podemos adicionar mais propriedade.

"sort": [
  {
    "field1": "asc"
  },
  {
    "field2": "desc"
  }
]

Artigo super rápido, mas super importante no dia a dia.

#005: Combinando filtros na busca do Elasticsearch

Bruno Flegler Dal'Col — Tue, 24 Aug 2021 12:30:21 +0000

Antes de continuarmos é importante ler #004: Adicionando filtro na busca do Elasticsearch.

Dessa vez vamos aprender como combinar mais de um filtro na sua pesquisa, suponha que queremos filtrar todos os documentos que foram criados no dia 21/08/2021 e que o cliente tenha 49 anos.

GET customers/_search
{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "age": 49
          }
        },
        {
          "term": {
            "createdAt": "2021-08-21"
          }
        }
      ]
    }
  }
}

Encontramos 2 clientes com idade igual a 49 anos e que foram criados no mesmo dia.

{
  "took" : 1,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 2,
      "relation" : "eq"
    },
    "max_score" : 2.0,
    "hits" : [
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "4",
        "_score" : 2.0,
        "_source" : {
          "id" : 4,
          "name" : "Mrs. Zachary Schneider",
          "email" : "Ruthie47@yahoo.com",
          "age" : 49,
          "createdAt" : "2021-08-21T03:16:33.102Z"
        }
      },
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "92",
        "_score" : 2.0,
        "_source" : {
          "id" : 92,
          "name" : "Charlotte Hansen",
          "email" : "Adelbert82@gmail.com",
          "age" : 49,
          "createdAt" : "2021-08-21T03:16:33.126Z"
        }
      }
    ]
  }
}

Quando queremos combinar filtros onde TODOS os valores deverão estar nos resultados, iremos usar o termo must. Ex: Os clientes com 49 anos que não foram criados no dia 21 não serão retornados. O must equivale ao famoso AND se fizermos uma analogia aos bancos de dados relacionais.

Agora ficou fácil, para filtrar por mais atributos é só adicioná-los dentro do array.

{
  "query": {
    "bool": {
      "must": [
        {
          "term": {
            "campo 1": "valor 1"
          }
        },
        {
          "term": {
            "campo 2": "valor 2"
          }
        },
        {
          "term": {
            "campo 3": "valor 3"
          }
        },
      ]
    }
  }
}

Sua vez agora, pratique. E te vejo no próximo artigo.

#004: Adicionando filtro na busca do Elasticsearch

Bruno Flegler Dal'Col — Sat, 21 Aug 2021 19:35:33 +0000

Antes de continuarmos não esqueça de ler #003:Buscando todos os documentos no Elasticsearch.

Bônus

Vamos instalar e iniciar o Kibana. O Kibana é uma interface de usuário gratuita e aberta para você visualizar seus documentos no Elasticsearch.

Edite o arquivo docker-compose.yml e atualize:

version: '3.3'

services:
  cluster-elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.14.0
    container_name: cluster-elasticsearch
    ports:
      - "9202:9200"
    environment:
      - discovery.type=single-node

  kibana:
    image: docker.elastic.co/kibana/kibana:7.14.0
    container_name: kibana
    ports: 
      - "5601:5601"
    environment: 
      - ELASTICSEARCH_HOSTS=http://cluster-elasticsearch:9200

Acesse em http://localhost:5601, no menu principal clique em Dev Tools -> Console

Antes de fazermos a busca, vamos adicionar mais documentos. Podemos usar _bulk que cria N documentos em uma única requisição. Para facilitar esse processo utilize o arquivo o 100 clientes aleatórios.

POST _bulk
{"index":{"_index":"customers","_id":1}}
{"id":1,"name":"Mrs. Leonard Roob","email":"Arnoldo22@hotmail.com","age":97,"createdAt":"2021-08-21T03:16:33.099Z"}
{"index":{"_index":"customers","_id":2}}

...five minutes later

Imagine que gostaríamos de filtrar os clientes por idade. Sendo assim podemos usar term query. Retornará todos documentos exatamente igual ao valor informado.

GET customers/_search
{
  "query": {
    "term": {
      "age": 18
    }
  }
}

Encontramos 4 clientes com idade igual a 18 anos.

{
  "took" : 2,
  "timed_out" : false,
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits" : {
    "total" : {
      "value" : 4,
      "relation" : "eq"
    },
    "max_score" : 1.0,
    "hits" : [
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "55",
        "_score" : 1.0,
        "_source" : {
          "id" : 55,
          "name" : "Mrs. Mable Ritchie",
          "email" : "Antonia.Will@gmail.com",
          "age" : 18,
          "createdAt" : "2021-08-21T03:16:33.116Z"
        }
      },
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "78",
        "_score" : 1.0,
        "_source" : {
          "id" : 78,
          "name" : "Lauren Howell",
          "email" : "Mathilde.Waters@hotmail.com",
          "age" : 18,
          "createdAt" : "2021-08-21T03:16:33.123Z"
        }
      },
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "82",
        "_score" : 1.0,
        "_source" : {
          "id" : 82,
          "name" : "Phillip Schulist",
          "email" : "Annamae99@yahoo.com",
          "age" : 18,
          "createdAt" : "2021-08-21T03:16:33.124Z"
        }
      },
      {
        "_index" : "customers",
        "_type" : "_doc",
        "_id" : "89",
        "_score" : 1.0,
        "_source" : {
          "id" : 89,
          "name" : "Warren Crooks",
          "email" : "Madilyn22@gmail.com",
          "age" : 18,
          "createdAt" : "2021-08-21T03:16:33.126Z"
        }
      }
    ]
  }
}

⚠️ Atenção:

Por padrão o Elasticsearch utiliza standard analyzer para campos do tipo text. Ex: O nome Mrs. Mable Ritchieé indexado as palavras separadamente sem pontuação como um array [mrs, mable, ritchie]

Usando o term não será possível filtrar o nome completo. Nos próximos artigos iremos falar sobre esses casos.

#003: Buscando todos os documentos no Elasticsearch

Bruno Flegler Dal'Col — Thu, 19 Aug 2021 00:05:45 +0000

No artigo anterior vimos como indexar os documentos no elasticsearch e hoje vamos aprender a retornar todos os registros indexados. Se você ainda não leu segue a referência #002: Indexando o primeiro documento
É importante indexar mais de um documento para conseguir observar os resultados da pesquisa.

...five minutes later

Use o curl para pesquisar os documentos. O intuito nesse momento não é obter performance na query é apenas entender como fazer uma busca total sem filtro e identificar os atríbutos principais.

$ curl -X GET "http://localhost:9202/customers/_search?pretty" -H "Content-Type: application/json" -d '
{
  "query": {
    "match_all": {}
  }
}'

{
  "took": 524,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 3,
      "relation": "eq"
    },
    "max_score": 1.0,
    "hits": [
      {
        "_index": "customers",
        "_type": "_doc",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "id": 1,
          "name": "Christopher M. Bass",
          "age": 45,
          "createdAt": "2021-08-17T02: 36: 39.104"
        }
      },
      {
        "_index": "customers",
        "_type": "_doc",
        "_id": "2",
        "_score": 1.0,
        "_source": {
          "id": 2,
          "name": "Alberto D. Wilson",
          "age": 77,
          "createdAt": "2021-08-18T17: 36: 39.104"
        }
      },
      {
        "_index": "customers",
        "_type": "_doc",
        "_id": "3",
        "_score": 1.0,
        "_source": {
          "id": 3,
          "name": "Darla G. Barney",
          "age": 19,
          "createdAt": "2021-08-18T17: 40: 39.104"
        }
      }
    ]
  }
}

O resultado retorna dentre eles o atributo total onde identificamos o total de documentos encontrados de acordo com o filtro. Nesse exemplo foram retornados 3 documentos.

"total": {
  "value": 3,
  "relation": "eq"
},

Por default o cluster irá retornar 10 documentos, mesmo que o total seja maior. Para aumentar esse valor precisamos adicionar a propriedade no corpo da requisição, mas por questão de performance o valor limite é 10000.

$ curl -X GET "http://localhost:9202/customers/_search?pretty" -H "Content-Type: application/json" -d '
{
  "query": {
    "match_all": {}
  },
  "size": 100,
}'

Nos próximos artigos iremos entender mais sobre atributos retornados na pesquisa, além de entender como filtrar por um atributo simples. Até lá pratiquem!

#002: Indexando o primeiro documento no Elasticsearch

Bruno Flegler Dal'Col — Wed, 18 Aug 2021 01:00:02 +0000

Certifique-se que o cluster foi iniciado. Como podemos ver nesse artigo #001: Iniciando no Elasticsearch.

Os documentos são indexados no elasticsearch no formato como JSON. Ex:

{
  "id": 1,
  "name": "Christopher M. Bass",
  "age": 45,
  "createdAt": "2021-08-17T02:36:39.104"
}

Use o curl para indexar o documento. O mesmo será indexado no índice customers. A palavra _doc é reservada e iremos entende-lá melhor quando falarmos sobre mappings.

$ curl -X POST "http://localhost:9202/customers/_doc" -H "Content-Type: application/json" -d '
{
  "id": 1,
  "name": "Christopher M. Bass",
  "age": 45,
  "createdAt": "2021-08-17T02:36:39.104"
}'

O cluster confirma a indexação e como não atribuímos um identificador para o documento, o cluster cria automáticamente. Como podemos ver no atributo _id.

{
  "_index": "customers",
  "_type": "_doc",
  "_id": "TKMXUnsBDnCk96a8UqV7",
  "_version": 1,
  "result": "created",
  "_shards": {
    "total": 2,
    "successful": 1,
    "failed": 0
  },
  "_seq_no": 1,
  "_primary_term": 1
}

Para atribuir um identificador basta informar um valor único depois do _doc/?. Ex: http://localhost:9202/customers/_doc/1".

É importante frisar a diferença entre id e _id. O _id é identificador único do elasticsearch, diferentemente de id que pode conter ou não no documento indexado.

Para visualizar o documento indexado podemos fazer a pesquisa pelo identificador _id. Ex:

$ curl -X GET "http://localhost:9202/customers/_doc/1"

{
  "_index": "customers",
  "_type": "_doc",
  "_id": "1",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "id": 1,
    "name": "Christopher M. Bass",
    "age": 45,
    "createdAt": "2021-08-17T02: 36: 39.104"
  }
}

No próximo artigo iremos entender como retornar todos os documentos de um indíce. Até lá pratique bem essa etapa, ela é o coração para um bom aprendizado sobre elasticsearch.

#001: Iniciando no Elasticsearch

Bruno Flegler Dal'Col — Sun, 15 Aug 2021 22:05:50 +0000

1 - Instale e inicie Docker Desktop.

2 - Crie o arquivo docker-compose.yml e adicione:

  version: '3.3'

  services:
    cluster-elasticsearch:
      image: docker.elastic.co/elasticsearch/elasticsearch:7.14.0
      container_name: cluster-elasticsearch
      ports:
        - "9202:9200"
      environment:
        - discovery.type=single-node

3 - Inicie o cluster:

$ docker-compose up --build -d

4 - Use o curl para acessar o status do cluster:

$ curl -X GET http://localhost:9202/_cluster/health?pretty

O status do cluster é definido pelo funcionamento da shards primárias e réplica. Os status são:

green: Todos as shards foram iniciadas.

yellow: Todas shards primárias foram iniciadas, mas uma ou mais réplicas não foi iniciada. Se um nó falhar, alguns dados podem ficar indisponíveis até que o nó seja reparado.

red: Uma ou mais shards primárias não foi iniciada, portanto os dados estão indisponíveis.

{
  "cluster_name" : "docker-cluster",
  "status" : "green",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1,
  "active_shards" : 1,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 0,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 100.0
}

O intuito desse artigo não é detalhar todas as propriedades, durante os próximos artigos veremos com mais detalhes. Te vejo até lá.