Elasticsearch - APIs de documentos

Elasticsearch fornece APIs de documento único e APIs de vários documentos, em que a chamada da API tem como objetivo um único documento e vários documentos, respectivamente.

API de índice

Isso ajuda a adicionar ou atualizar o documento JSON em um índice quando uma solicitação é feita para esse respectivo índice com mapeamento específico. Por exemplo, a solicitação a seguir adicionará o objeto JSON para indexar escolas e mapeamento de escolas -

PUT schools/_doc/5
{
   name":"City School", "description":"ICSE", "street":"West End",
   "city":"Meerut",
   "state":"UP", "zip":"250002", "location":[28.9926174, 77.692485],
   "fees":3500,
   "tags":["fully computerized"], "rating":"4.5"
}

Ao executar o código acima, obtemos o seguinte resultado -

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

Criação Automática de Índice

Quando uma solicitação é feita para adicionar um objeto JSON a um índice específico e esse índice não existe, esta API cria automaticamente esse índice e também o mapeamento subjacente para esse objeto JSON específico. Essa funcionalidade pode ser desabilitada alterando os valores dos seguintes parâmetros para false, que estão presentes no arquivo elasticsearch.yml.

action.auto_create_index:false
index.mapper.dynamic:false

Você também pode restringir a criação automática de índice, onde apenas o nome do índice com padrões específicos são permitidos, alterando o valor do seguinte parâmetro -

action.auto_create_index:+acc*,-bank*

Note - Aqui + indica permitido e - indica não permitido.

Controle de versão

Elasticsearch também fornece facilidade de controle de versão. Podemos usar um parâmetro de consulta de versão para especificar a versão de um determinado documento.

PUT schools/_doc/5?version=7&version_type=external
{
   "name":"Central School", "description":"CBSE Affiliation", "street":"Nagan",
   "city":"paprola", "state":"HP", "zip":"176115", "location":[31.8955385, 76.8380405],
   "fees":2200, "tags":["Senior Secondary", "beautiful campus"], "rating":"3.3"
}

Ao executar o código acima, obtemos o seguinte resultado -

{
   "_index" : "schools",
   "_type" : "_doc",
   "_id" : "5",
   "_version" : 7,
   "result" : "updated",
   "_shards" : {
      "total" : 2,
      "successful" : 1,
      "failed" : 0
   },
   "_seq_no" : 3,
   "_primary_term" : 1
}

O controle de versão é um processo em tempo real e não é afetado pelas operações de pesquisa em tempo real.

Existem dois tipos mais importantes de controle de versão -

Controle de versão interno

O controle de versão interno é a versão padrão que começa com 1 e aumenta a cada atualização, incluindo exclusões.

Controle de versão externo

É usado quando a versão dos documentos é armazenada em um sistema externo, como sistemas de versão de terceiros. Para habilitar essa funcionalidade, precisamos definir version_type como externo. Aqui, o Elasticsearch armazenará o número da versão conforme designado pelo sistema externo e não os incrementará automaticamente.

Tipo de operação

O tipo de operação é usado para forçar uma operação de criação. Isso ajuda a evitar a substituição de documentos existentes.

PUT chapter/_doc/1?op_type=create
{
   "Text":"this is chapter one"
}

Ao executar o código acima, obtemos o seguinte resultado -

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

Geração automática de ID

Quando o ID não é especificado na operação de índice, o Elasticsearch gera automaticamente o id para esse documento.

POST chapter/_doc/
{
   "user" : "tpoint",
   "post_date" : "2018-12-25T14:12:12",
   "message" : "Elasticsearch Tutorial"
}

Ao executar o código acima, obtemos o seguinte resultado -

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

Obter API

A API ajuda a extrair o objeto JSON do tipo executando uma solicitação get para um documento específico.

pre class="prettyprint notranslate" > GET schools/_doc/5

Ao executar o código acima, obtemos o seguinte resultado -

{
   "_index" : "schools",
   "_type" : "_doc",
   "_id" : "5",
   "_version" : 7,
   "_seq_no" : 3,
   "_primary_term" : 1,
   "found" : true,
   "_source" : {
      "name" : "Central School",
      "description" : "CBSE Affiliation",
      "street" : "Nagan",
      "city" : "paprola",
      "state" : "HP",
      "zip" : "176115",
      "location" : [
         31.8955385,
         76.8380405
      ],
      "fees" : 2200,
      "tags" : [
         "Senior Secondary",
         "beautiful campus"
      ],
      "rating" : "3.3"
   }
}
  • Esta operação é em tempo real e não é afetada pela taxa de atualização do Índice.

  • Você também pode especificar a versão, então o Elasticsearch buscará apenas essa versão do documento.

  • Você também pode especificar _all na solicitação, de modo que o Elasticsearch possa pesquisar esse id de documento em todos os tipos e retorne o primeiro documento correspondente.

  • Você também pode especificar os campos que deseja no resultado desse documento específico.

GET schools/_doc/5?_source_includes=name,fees

Ao executar o código acima, obtemos o seguinte resultado -

{
   "_index" : "schools",
   "_type" : "_doc",
   "_id" : "5",
   "_version" : 7,
   "_seq_no" : 3,
   "_primary_term" : 1,
   "found" : true,
   "_source" : {
      "fees" : 2200,
      "name" : "Central School"
   }
}

Você também pode buscar a parte de origem em seu resultado, apenas adicionando a parte _source em sua solicitação get.

GET schools/_doc/5?_source

Ao executar o código acima, obtemos o seguinte resultado -

{
   "_index" : "schools",
   "_type" : "_doc",
   "_id" : "5",
   "_version" : 7,
   "_seq_no" : 3,
   "_primary_term" : 1,
   "found" : true,
   "_source" : {
      "name" : "Central School",
      "description" : "CBSE Affiliation",
      "street" : "Nagan",
      "city" : "paprola",
      "state" : "HP",
      "zip" : "176115",
      "location" : [
         31.8955385,
         76.8380405
      ],
      "fees" : 2200,
      "tags" : [
         "Senior Secondary",
         "beautiful campus"
      ],
      "rating" : "3.3"
   }
}

Você também pode atualizar o fragmento antes de executar a operação get, definindo o parâmetro de atualização como true.

Apagar API

Você pode excluir um índice, mapeamento ou documento específico enviando uma solicitação HTTP DELETE para o Elasticsearch.

DELETE schools/_doc/4

Ao executar o código acima, obtemos o seguinte resultado -

{
   "found":true, "_index":"schools", "_type":"school", "_id":"4", "_version":2,
   "_shards":{"total":2, "successful":1, "failed":0}
}

A versão do documento pode ser especificada para excluir essa versão particular. O parâmetro de roteamento pode ser especificado para excluir o documento de um determinado usuário e a operação falhará se o documento não pertencer a esse usuário específico. Nesta operação, você pode especificar a opção de atualização e tempo limite da mesma forma que a API GET.

API de atualização

O script é usado para executar esta operação e o controle de versão é usado para garantir que nenhuma atualização tenha ocorrido durante a obtenção e reindexação. Por exemplo, você pode atualizar as taxas escolares usando o script -

POST schools/_update/4
{
   "script" : {
      "source": "ctx._source.name = params.sname",
      "lang": "painless",
      "params" : {
         "sname" : "City Wise School"
      }
   }
 }

Ao executar o código acima, obtemos o seguinte resultado -

{
   "_index" : "schools",
   "_type" : "_doc",
   "_id" : "4",
   "_version" : 3,
   "result" : "updated",
   "_shards" : {
      "total" : 2,
      "successful" : 1,
      "failed" : 0
   },
   "_seq_no" : 4,
   "_primary_term" : 2
}

Você pode verificar a atualização enviando uma solicitação get para o documento atualizado.