API индекса

Если целевой объект запроса не существует и соответствует шаблону индекса с определением data_stream, операция индексации автоматически создаст поток данных. См. создание шаблона индекса.

Если целевой объект не существует и не соответствует шаблону потока данных, операция автоматически создает индекс и применяет все соответствующие шаблоны индексов.

Если отображение отсутствует, операция индексации создаёт динамическое отображение. По умолчанию новые поля и объекты автоматически добавляются в отображение при необходимости. Дополнительную информацию об отображении полей см. в разделе отображение и в API обновления отображения.

Автоматическое создание индекса контролируется настройкой action.auto_create_index. По умолчанию используется значение true, что позволяет автоматически создавать любой индекс. Вы можете изменить эту настройку, чтобы явно разрешить или заблокировать автоматическое создание индексов, соответствующих указанным шаблонам, или установить её в значение false, чтобы полностью отключить автоматическое создание индексов. Укажите список шаблонов через запятую, которые вы хотите разрешить, или добавьте префикс + или - к каждому шаблону, чтобы указать, следует ли его разрешить или заблокировать. При указании списка по умолчанию поведение настроек — блокировка.

PUT _cluster/settings
{
  "persistent": {
    "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*" 
  }
}

PUT _cluster/settings
{
  "persistent": {
    "action.auto_create_index": "false" 
  }
}

PUT _cluster/settings
{
  "persistent": {
    "action.auto_create_index": "true" 
  }
}

Вы можете принудительно выполнить операцию создания, используя ресурс _create или установив параметр op_type в значение create. В этом случае операция индексации завершается ошибкой, если документ с указанным идентификатором уже существует в индексе.

При использовании формата запроса POST /<target>/_doc/ параметр op_type автоматически устанавливается в значение create, и операция индексации генерирует уникальный идентификатор для документа.

POST my-index-000001/_doc/
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

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

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  },
  "_index": "my-index-000001",
   "_type": "_doc",
  "_id": "W0tpsmIBdwcYyG50zbta",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}

Операции индексации могут выполняться условно и только если последнее изменение документа было присвоено порядковый номер и первичный термин, указанные параметрами if_seq_no и if_primary_term. Если обнаружено несоответствие, операция приведет к VersionConflictException и коду состояния 409. Дополнительные сведения см. в разделе Оптимистический контроль одновременного доступа.

По умолчанию размещение фрагментов — или routing — управляется с помощью хэширования значения идентификатора документа. Для более точного контроля значение, подаваемое в функцию хэширования, используемую маршрутизатором, можно указать непосредственно для каждой операции с помощью параметра routing. Например:

POST my-index-000001/_doc?routing=kimchy
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

В этом примере документ маршрутизируется в фрагмент на основе параметра routing, предоставленного: "kimchy".

При настройке явного отображения вы также можете использовать поле _routing для направления операции индексации на извлечение значения маршрутизации из самого документа. Это влечёт (очень незначительные) затраты на дополнительный проход по анализу документа. Если отображение _routing определено и установлено в значение required, операция индексации завершится ошибкой, если не предоставлено или не извлечено значение маршрутизации.

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

Для повышения устойчивости операций записи в систему операции индексирования могут быть сконфигурированы для ожидания определённого количества активных копий фрагментов перед продолжением операции. Если необходимое количество активных копий фрагментов недоступно, операция записи должна ожидать и повторять попытку, пока либо необходимые копии фрагментов не начнут работу, либо не произойдёт истечение времени ожидания. По умолчанию операции записи ожидают только активации первичных фрагментов перед продолжением (то есть wait_for_active_shards=1). Это значение по умолчанию может быть динамически переопределено в настройках индекса, установив index.write.wait_for_active_shards. Чтобы изменить это поведение для каждой операции, можно использовать параметр запроса wait_for_active_shards.

Допустимые значения — all или любое положительное целое число до максимального количества настроенных копий на фрагмент в индексе (которое равно number_of_replicas+1). Указание отрицательного значения или числа, превышающего количество копий фрагментов, вызовет ошибку.

Например, предположим, что у нас есть кластер из трёх узлов, A, B и C, и мы создаём индекс index с количеством реплик, установленным в 3 (что приводит к 4 копиям фрагментов, на одну копию больше, чем узлов). Если мы пытаемся выполнить операцию индексирования, то по умолчанию операция будет гарантировать, что доступна первичная копия каждого фрагмента, прежде чем продолжить. Это означает, что даже если B и C вышли из строя, а A разместил первичные копии фрагментов, операция индексирования всё равно продолжится с одной копией данных. Если wait_for_active_shards установлено в запросе на 3 (и все 3 узла работают), то операция индексирования потребует 3 активных копий фрагментов перед продолжением, что должно быть выполнено, так как в кластере 3 активных узла, каждый из которых содержит копию фрагмента. Однако, если мы установим wait_for_active_shards на all (или на 4, что равнозначно), операция индексирования не будет продолжена, так как у нас нет всех 4 копий каждого фрагмента, активных в индексе. Операция истечёт, если не будет поднят новый узел в кластере для размещения четвёртой копии фрагмента.

Важно отметить, что эта настройка значительно снижает вероятность того, что операция записи не будет записана в необходимое количество копий фрагментов, но не исключает её полностью, поскольку эта проверка происходит до начала операции записи. После того, как операция записи началась, всё ещё возможно, что репликация завершится неудачей на любом количестве копий фрагментов, но операция всё же может завершиться успехом на первичном. Раздел _shards ответа операции записи показывает количество копий фрагментов, на которых репликация прошла успешно/неудачно.

{
  "_shards": {
    "total": 2,
    "failed": 0,
    "successful": 2
  }
}

Управление временем, когда изменения, внесённые данным запросом, будут видны в результатах поиска. См. обновление.

При обновлении документа с помощью API индексации всегда создаётся новая версия документа, даже если документ не изменился. Если это неприемлемо, используйте API _update с параметром detect_noop, установленным в значение true. Этот параметр недоступен в API индексации, так как API индексации не извлекает старое исходное значение и не может сравнить его с новым исходным значением.

Нет жёстких правил, когда операции без изменений неприемлемы. Это сочетание множества факторов, таких как частота, с которой ваш источник данных отправляет обновления, которые на самом деле являются операциями без изменений, и количество запросов в секунду, выполняемых Elasticsearch на фрагменте, получающем обновления.

Первичный фрагмент, назначенный для выполнения операции индексации, может быть недоступен при выполнении операции индексирования. Причинами этого могут быть текущая реконфигурация первичного фрагмента из-за восстановления с портала или перераспределения. По умолчанию операция индексирования будет ждать, пока первичный фрагмент станет доступным в течение 1 минуты перед завершением с ошибкой и возвращением ошибки. Параметр timeout может использоваться для явного указания времени ожидания. Вот пример установки его на 5 минут:

PUT my-index-000001/_doc/1?timeout=5m
{
  "@timestamp": "2099-11-15T13:12:00",
  "message": "GET /search HTTP/1.1 200 1070000",
  "user": {
    "id": "kimchy"
  }
}

Каждый индексируемый документ получает номер версии. По умолчанию используется внутренняя система версионирования, которая начинается с 1 и увеличивается при каждом обновлении, включая удаления. Дополнительно, номер версии может быть установлен во внешнее значение (например, если он хранится в базе данных). Для активации этой функции version_type следует установить в значение external. Указанное значение должно быть числовым значением типа long, большим или равным 0 и меньшим примерно 9.2e+18.

При использовании внешнего типа версии система проверяет, больше ли номер версии, переданный в запрос индексирования, чем версия текущего хранимого документа. Если это так, документ будет индексирован, и будет использоваться новый номер версии. Если предоставленное значение меньше или равно номеру версии хранимого документа, произойдёт конфликт версий, и операция индексации завершится неудачей. Например:

PUT my-index-000001/_doc/1?version=2&version_type=external
{
  "user": {
    "id": "elkbee"
  }
}

В предыдущем примере операция будет выполнена успешно, так как указанная версия 2 выше текущей версии документа 1. Если документ уже был обновлен и его версия установлена на 2 или выше, команда индексирования завершится с ошибкой и конфликтом (код состояния HTTP 409).

Приятным побочным эффектом является то, что нет необходимости поддерживать строгую последовательность операций асинхронного индексирования, выполняемых в результате изменений в исходной базе данных, если используются номера версий из исходной базы данных. Даже в простом случае обновления индекса Elasticsearch данными из базы данных упрощается, если используется внешнее версионирование, так как будет использоваться только последняя версия, если операции индексирования по какой-либо причине придут в неправильном порядке.

В дополнение к типу версии external Elasticsearch также поддерживает другие типы для определенных случаев использования: