API Get

GET <index>/_doc/<_id>

HEAD <index>/_doc/<_id>

GET <index>/_source/<_id>

HEAD <index>/_source/<_id>

Вы используете GET для извлечения документа и его исходных данных или сохраненных полей из определённого индекса. Используйте HEAD для проверки существования документа. Вы можете использовать ресурс _source для извлечения только исходных данных документа или проверки его существования.

По умолчанию API get работает в режиме реального времени и не зависит от частоты обновления индекса (когда данные станут видимыми для поиска). В случае, если запрашиваются сохранённые поля (см. параметр stored_fields) и документ был обновлён, но ещё не обновлён в индексе, API get должен проанализировать исходные данные для извлечения сохранённых полей. Для отключения режима реального времени GET можно установить параметр realtime в значение false.

По умолчанию операция get возвращает содержимое поля _source, если не используется параметр stored_fields или если поле _source отключено. Вы можете отключить извлечение _source, используя параметр _source:

GET my-index-000001/_doc/0?_source=false

Если вам нужны только одно или два поля из _source, используйте параметры _source_includes или _source_excludes для включения или исключения определённых полей. Это особенно полезно с большими документами, где частичное извлечение может сэкономить сетевой трафик. Оба параметра принимают список полей, разделённых запятыми, или выражения с подстановкой. Пример:

GET my-index-000001/_doc/0?_source_includes=*.id&_source_excludes=entities

Если вам нужно только указать включения, можно использовать более короткую запись:

GET my-index-000001/_doc/0?_source=*.id

Если при индексировании используется маршрутизация, необходимо также указать значение маршрутизации для извлечения документа. Например:

GET my-index-000001/_doc/2?routing=user1

Этот запрос получает документ с id 2, но он маршрутизируется на основе пользователя. Документ не извлекается, если не указана правильная маршрутизация.

Управляет preference, какой репликой фрагмента выполнить запрос get. По умолчанию операция выбирается случайным образом среди реплик фрагмента.

Параметр preference может быть установлен на:

Параметр refresh можно установить в true, чтобы обновить соответствующий фрагмент перед операцией get и сделать его доступным для поиска. Установка его в true должна быть тщательно обдумана и проверена, чтобы это не создавало большой нагрузки на систему (и не замедляло индексирование).

Операция get хешируется в определённый идентификатор фрагмента. Затем она перенаправляется на одну из реплик в этом идентификаторе фрагмента и возвращает результат. Реплики — это основной фрагмент и его реплики в группе фрагментов. Это означает, что чем больше у нас реплик, тем лучше масштабирование GET.

Вы можете использовать параметр version, чтобы извлечь документ только в том случае, если его текущая версия совпадает с заданной.

Внутренне Elasticsearch помечает старый документ как удалённый и добавляет совершенно новый. Старая версия документа не исчезает сразу, хотя получить к ней доступ нельзя. Elasticsearch очищает удалённые документы в фоновом режиме, по мере продолжения индексирования данных.

Получите документ JSON с _id 0 из индекса my-index-000001:

GET my-index-000001/_doc/0

API возвращает следующий результат:

{
  "_index": "my-index-000001",
  "_type": "_doc",
  "_id": "0",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "found": true,
  "_source": {
    "@timestamp": "2099-11-15T14:12:12",
    "http": {
      "request": {
        "method": "get"
      },
      "response": {
        "status_code": 200,
        "bytes": 1070000
      },
      "version": "1.1"
    },
    "source": {
      "ip": "127.0.0.1"
    },
    "message": "GET /search HTTP/1.1 200 1070000",
    "user": {
      "id": "kimchy"
    }
  }
}

Проверьте, существует ли документ с _id 0:

HEAD my-index-000001/_doc/0

Elasticsearch возвращает код состояния 200 - OK, если документ существует, или 404 - Not Found, если его нет.

Используйте ресурс <index>/_source/<id>, чтобы получить только поле _source документа. Например:

GET my-index-000001/_source/1

Вы можете использовать параметры фильтрации source, чтобы контролировать, какие части _source будут возвращены:

GET my-index-000001/_source/1/?_source_includes=*.id&_source_excludes=entities

Вы можете использовать HEAD с конечной точкой _source, чтобы эффективно проверить, существует ли _source документа. Источник документа недоступен, если он отключен в карте.

HEAD my-index-000001/_source/1

Используйте параметр stored_fields, чтобы указать набор сохранённых полей, которые вы хотите получить. Любые запрошенные поля, которые не сохранены, игнорируются. Рассмотрим, например, следующую карту:

PUT my-index-000001
{
   "mappings": {
       "properties": {
          "counter": {
             "type": "integer",
             "store": false
          },
          "tags": {
             "type": "keyword",
             "store": true
          }
       }
   }
}

Теперь мы можем добавить документ:

PUT my-index-000001/_doc/1
{
  "counter": 1,
  "tags": [ "production" ]
}

И затем попытаться его получить:

GET my-index-000001/_doc/1?stored_fields=tags,counter

API возвращает следующий результат:

{
   "_index": "my-index-000001",
   "_type": "_doc",
   "_id": "1",
   "_version": 1,
   "_seq_no" : 22,
   "_primary_term" : 1,
   "found": true,
   "fields": {
      "tags": [
         "production"
      ]
   }
}

Значения полей, извлеченные из самого документа, всегда возвращаются в виде массива. Поскольку поле counter не сохранено, запрос get его игнорирует.

Вы также можете получить поля метаданных, такие как поле _routing:

PUT my-index-000001/_doc/2?routing=user1
{
  "counter" : 1,
  "tags" : ["env2"]
}

GET my-index-000001/_doc/2?routing=user1&stored_fields=tags,counter

API возвращает следующий результат:

{
   "_index": "my-index-000001",
   "_type": "_doc",
   "_id": "2",
   "_version": 1,
   "_seq_no" : 13,
   "_primary_term" : 1,
   "_routing": "user1",
   "found": true,
   "fields": {
      "tags": [
         "env2"
      ]
   }
}

Только листовые поля могут быть получены с опцией stored_field. Поля-объекты не могут быть возвращены — в случае указания запрос завершается ошибкой.