API индексирования

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

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

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

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

resp = client.cluster.put_settings(
    persistent={
        "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*"
    },
)
print(resp)

resp1 = client.cluster.put_settings(
    persistent={
        "action.auto_create_index": "false"
    },
)
print(resp1)

resp2 = client.cluster.put_settings(
    persistent={
        "action.auto_create_index": "true"
    },
)
print(resp2)

response = client.cluster.put_settings(
  body: {
    persistent: {
      'action.auto_create_index' => 'my-index-000001,index10,-index1*,+ind*'
    }
  }
)
puts response

response = client.cluster.put_settings(
  body: {
    persistent: {
      'action.auto_create_index' => 'false'
    }
  }
)
puts response

response = client.cluster.put_settings(
  body: {
    persistent: {
      'action.auto_create_index' => 'true'
    }
  }
)
puts response

const response = await client.cluster.putSettings({
  persistent: {
    "action.auto_create_index": "my-index-000001,index10,-index1*,+ind*",
  },
});
console.log(response);

const response1 = await client.cluster.putSettings({
  persistent: {
    "action.auto_create_index": "false",
  },
});
console.log(response1);

const response2 = await client.cluster.putSettings({
  persistent: {
    "action.auto_create_index": "true",
  },
});
console.log(response2);

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, и операция индексирования генерирует уникальный идентификатор для документа.

resp = client.index(
    index="my-index-000001",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)
print(resp)

response = client.index(
  index: 'my-index-000001',
  body: {
    "@timestamp": '2099-11-15T13:12:00',
    message: 'GET /search HTTP/1.1 200 1070000',
    user: {
      id: 'kimchy'
    }
  }
)
puts response

const response = await client.index({
  index: "my-index-000001",
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});
console.log(response);

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",
  "_id": "W0tpsmIBdwcYyG50zbta",
  "_version": 1,
  "_seq_no": 0,
  "_primary_term": 1,
  "result": "created"
}

Операции индексирования могут быть условными и выполняться только в том случае, если последнее изменение документа было присвоено порядковый номер и первичный термин, указанные параметрами if_seq_no и if_primary_term. Если обнаружено несоответствие, операция приведёт к ошибке VersionConflictException и статусному коду 409. Подробнее см. Контроль конкурентности (optimistic concurrency control).

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

resp = client.index(
    index="my-index-000001",
    routing="kimchy",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)
print(resp)

response = client.index(
  index: 'my-index-000001',
  routing: 'kimchy',
  body: {
    "@timestamp": '2099-11-15T13:12:00',
    message: 'GET /search HTTP/1.1 200 1070000',
    user: {
      id: 'kimchy'
    }
  }
)
puts response

const response = await client.index({
  index: "my-index-000001",
  routing: "kimchy",
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});
console.log(response);

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
  }
}

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

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

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

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

resp = client.index(
    index="my-index-000001",
    id="1",
    timeout="5m",
    document={
        "@timestamp": "2099-11-15T13:12:00",
        "message": "GET /search HTTP/1.1 200 1070000",
        "user": {
            "id": "kimchy"
        }
    },
)
print(resp)

response = client.index(
  index: 'my-index-000001',
  id: 1,
  timeout: '5m',
  body: {
    "@timestamp": '2099-11-15T13:12:00',
    message: 'GET /search HTTP/1.1 200 1070000',
    user: {
      id: 'kimchy'
    }
  }
)
puts response

const response = await client.index({
  index: "my-index-000001",
  id: 1,
  timeout: "5m",
  document: {
    "@timestamp": "2099-11-15T13:12:00",
    message: "GET /search HTTP/1.1 200 1070000",
    user: {
      id: "kimchy",
    },
  },
});
console.log(response);

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. Указанное значение должно быть числовым, длинным значением, большим или равным 0 и меньшим приблизительно 9.2e+18.

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

resp = client.index(
    index="my-index-000001",
    id="1",
    version="2",
    version_type="external",
    document={
        "user": {
            "id": "elkbee"
        }
    },
)
print(resp)

response = client.index(
  index: 'my-index-000001',
  id: 1,
  version: 2,
  version_type: 'external',
  body: {
    user: {
      id: 'elkbee'
    }
  }
)
puts response

const response = await client.index({
  index: "my-index-000001",
  id: 1,
  version: 2,
  version_type: "external",
  document: {
    user: {
      id: "elkbee",
    },
  },
});
console.log(response);

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

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

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

Помимо типа версионирования external, Elasticsearch также поддерживает другие типы для определённых случаев: