› › ›

API для моделирования обработки данных

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

resp = client.simulate.ingest(
    docs=[
        {
            "_index": "my-index",
            "_id": "id",
            "_source": {
                "foo": "bar"
            }
        },
        {
            "_index": "my-index",
            "_id": "id",
            "_source": {
                "foo": "rab"
            }
        }
    ],
    pipeline_substitutions={
        "my-pipeline": {
            "processors": [
                {
                    "set": {
                        "field": "field3",
                        "value": "value3"
                    }
                }
            ]
        }
    },
    component_template_substitutions={
        "my-component-template": {
            "template": {
                "mappings": {
                    "dynamic": "true",
                    "properties": {
                        "field3": {
                            "type": "keyword"
                        }
                    }
                },
                "settings": {
                    "index": {
                        "default_pipeline": "my-pipeline"
                    }
                }
            }
        }
    },
    index_template_substitutions={
        "my-index-template": {
            "index_patterns": [
                "my-index-*"
            ],
            "composed_of": [
                "component_template_1",
                "component_template_2"
            ]
        }
    },
    mapping_addition={
        "dynamic": "strict",
        "properties": {
            "foo": {
                "type": "keyword"
            }
        }
    },
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_ingest/_simulate",
  body: {
    docs: [
      {
        _index: "my-index",
        _id: "id",
        _source: {
          foo: "bar",
        },
      },
      {
        _index: "my-index",
        _id: "id",
        _source: {
          foo: "rab",
        },
      },
    ],
    pipeline_substitutions: {
      "my-pipeline": {
        processors: [
          {
            set: {
              field: "field3",
              value: "value3",
            },
          },
        ],
      },
    },
    component_template_substitutions: {
      "my-component-template": {
        template: {
          mappings: {
            dynamic: "true",
            properties: {
              field3: {
                type: "keyword",
              },
            },
          },
          settings: {
            index: {
              default_pipeline: "my-pipeline",
            },
          },
        },
      },
    },
    index_template_substitutions: {
      "my-index-template": {
        index_patterns: ["my-index-*"],
        composed_of: ["component_template_1", "component_template_2"],
      },
    },
    mapping_addition: {
      dynamic: "strict",
      properties: {
        foo: {
          type: "keyword",
        },
      },
    },
  },
});
console.log(response);

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "id",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "id",
      "_source": {
        "foo": "rab"
      }
    }
  ],
  "pipeline_substitutions": { 
    "my-pipeline": {
      "processors": [
        {
          "set": {
            "field": "field3",
            "value": "value3"
          }
        }
      ]
    }
  },
  "component_template_substitutions": { 
    "my-component-template": {
      "template": {
        "mappings": {
          "dynamic": "true",
          "properties": {
            "field3": {
              "type": "keyword"
            }
          }
        },
        "settings": {
          "index": {
            "default_pipeline": "my-pipeline"
          }
        }
      }
    }
  },
  "index_template_substitutions": { 
    "my-index-template": {
      "index_patterns": ["my-index-*"],
      "composed_of": ["component_template_1", "component_template_2"]
    }
  },
  "mapping_addition": { 
    "dynamic": "strict",
    "properties": {
      "foo": {
        "type": "keyword"
      }
    }
  }
}

	Это заменяет существующий `my-pipeline` конвейер содержанием, указанным здесь, на период выполнения этого запроса.
	Это заменяет существующую `my-component-template` шаблон компонента содержанием, указанным здесь, на период выполнения этого запроса. Эти шаблоны могут быть использованы для изменения используемых конвейера(ов) или для изменения схемы, которая будет использоваться для проверки результата.
	Это заменяет существующий `my-index-template` шаблон индекса содержанием, указанным здесь, на период выполнения этого запроса. Эти шаблоны могут быть использованы для изменения используемых конвейера(ов) или для изменения схемы, которая будет использоваться для проверки результата.
	Эта схема объединяется в итоговую схему индекса непосредственно перед проверкой. Она используется только на период выполнения этого запроса.

Запрос

POST /_ingest/_simulate

GET /_ingest/_simulate

POST /_ingest/<target>/_simulate

GET /_ingest/<target>/_simulate

Предварительные условия

Если в Elasticsearch включены функции безопасности, вам необходимо иметь index или create права доступа к индексам, чтобы использовать этот API.

Описание

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

Этот API отличается от API для моделирования конвейера тем, что вы указываете один конвейер для этого API, и он выполняет только этот один конвейер. API для моделирования конвейера более полезен для разработки одного конвейера, а API для моделирования обработки данных более полезен для устранения неполадок во взаимодействии различных конвейеров, которые применяются при обработке данных в индексе.

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

Параметры пути

<target>: (Необязательно, строка) Индекс, в который нужно смоделировать обработку данных. Это можно переопределить, указав индекс в каждом документе. Если вы предоставляете <target> в пути запроса, он используется для любых документов, которые явно не указывают аргумент индекса.

Параметры запроса

pipeline: (Необязательно, строка) Конвейер, который следует использовать в качестве конвейера по умолчанию. Это можно использовать для переопределения конвейера по умолчанию для индекса, в который обрабатываются данные.

Тело запроса

docs

(Обязательный, массив объектов) Образцы документов для тестирования в конвейере.

Свойства объектов docs

_id: (Необязательный, строка) Уникальный идентификатор документа.
_index: (Необязательный, строка) Название индекса, в который будет добавлен документ.
_source: (Обязательный, объект) Тело документа в формате JSON.

pipeline_substitutions

(Необязательный, карта строк к объектам) Карта идентификаторов конвейеров к объектам определений конвейеров.

Свойства объектов определения конвейеров

description

(Необязательный, строка) Описание конвейера импорта.

on_failure

(Необязательный, массив объектов процессора) Процессоры, которые будут выполнены сразу после сбоя процессора.

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

processors

(Обязательный, массив объектов процессора) Процессоры, используемые для выполнения преобразований документов перед индексированием. Процессоры выполняются последовательно в указанном порядке.

version

(Необязательный, целое число) Номер версии, используемый внешними системами для отслеживания конвейеров импорта.

См. параметр if_version выше, чтобы узнать, как используется атрибут версии.

_meta

(Необязательный, объект) Дополнительные метаданные о конвейере импорта. Может содержать любые данные. Эта карта не генерируется автоматически Elasticsearch.

deprecated

(Необязательный, булево) Отмечает этот конвейер импорта как устаревший. Когда устаревший конвейер импорта используется как конвейер по умолчанию или конечный конвейер при создании или обновлении шаблона индекса, не помеченного как устаревший, Elasticsearch будет генерировать предупреждение об устаревании.

component_template_substitutions

(Необязательный, карта строк к объектам) Карта имен шаблонов компонентов для замены объектами определений шаблонов компонентов.

Свойства объектов определений шаблонов компонентов

template

(Обязательный, объект) Это шаблон, который должен быть применен, и может дополнительно содержать конфигурацию mappings, settings или aliases.

Свойства template

aliases

(Необязательный, объект объектов) Псевдонимы для добавления.

Если шаблон индекса содержит объект data_stream, это псевдонимы потоков данных. В противном случае, это псевдонимы индексов. Псевдонимы потоков данных игнорируют параметры index_routing, routing и search_routing.

Свойства объектов aliases

<alias>

(Обязательный, объект) Ключ — это имя псевдонима. Имена псевдонимов индексов поддерживают date math.

Тело объекта содержит параметры для псевдонима. Поддерживается пустой объект.

Свойства <alias>

filter: (Необязательный, объект запроса DSL) Запрос, используемый для ограничения документов, к которым может получить доступ псевдоним.
index_routing: (Необязательный, строка) Значение, используемое для маршрутизации операций индексирования на определенный фрагмент. Если указано, это переопределяет значение routing для операций индексирования.
is_hidden: (Необязательный, логическое значение) Если true, псевдоним скрыт. По умолчанию false. Все индексы для псевдонима должны иметь одинаковое значение is_hidden.
is_write_index: (Необязательный, логическое значение) Если true, индекс является индексом записи для псевдонима. По умолчанию false.
routing: (Необязательный, строка) Значение, используемое для маршрутизации операций индексирования и поиска на определенный фрагмент.
search_routing: (Необязательный, строка) Значение, используемое для маршрутизации операций поиска на определенный фрагмент. Если указано, это переопределяет значение routing для операций поиска.

mappings

(Необязательный, объект картирования) Картирование полей в индексе. Если указано, это отображение может включать:

См. Картирование.

settings

(Необязательный, объект настроек индекса) Параметры конфигурации индекса. См. Настройки индекса.

version

(Необязательный, целое число) Номер версии для управления шаблонами компонентов внешним образом. Это число не генерируется и не увеличивается автоматически Elasticsearch.

allow_auto_create

(Необязательный, логическое значение) Этот параметр переопределяет значение кластерного параметра action.auto_create_index. Если установлено значение true в шаблоне, тогда индексы могут быть автоматически созданы с помощью этого шаблона, даже если автоматическое создание индексов отключено с помощью actions.auto_create_index. Если установлено значение false, тогда индексы или потоки данных, соответствующие шаблону, всегда должны быть явно созданы и никогда не могут быть созданы автоматически.

_meta

(Необязательный, объект) Дополнительные пользовательские метаданные о шаблоне компонента. Может содержать любые данные. Эта карта не генерируется автоматически Elasticsearch.

deprecated

(Необязательный, булево) Отмечает этот шаблон компонента как устаревший. Когда на шаблон компонента, помеченный как устаревший, ссылаются при создании или обновлении шаблона индекса, не помеченного как устаревший, Elasticsearch выведет предупреждение об устаревании.

index_template_substitutions

(Необязательно, карта строк к объектам) Карта имен шаблонов индексов для замены объектами определений шаблонов индексов.

Свойства объектов определений шаблонов индексов

composed_of

(Необязательно, массив строк) Упорядоченный список имён шаблонов компонентов. Шаблоны компонентов объединяются в указанном порядке, что означает, что последний указанный шаблон компонента имеет наивысший приоритет. См. создание нескольких шаблонов компонентов для примера.

data_stream

(Необязательно, объект) Если этот объект включён, шаблон используется для создания потоков данных и их базовых индексов. Поддерживается пустой объект.

Потоки данных требуют соответствующего шаблона индекса с объектом data_stream. См. создайте шаблон индекса.

Свойства объекта data_stream

allow_custom_routing

(Необязательно, Булево) Если true, поток данных поддерживает настраиваемое маршрутизирование. По умолчанию false.

hidden

(Необязательно, Булево) Если true, поток данных скрыт. По умолчанию false.

index_mode

(Необязательно, строка) Тип потока данных для создания. Допустимые значения: null (стандартный поток данных), time_series (поток данных временных рядов) и logsdb (поток данных журналов).

index_mode шаблона устанавливает index.mode базового индекса.

index_patterns

(Обязательно, массив строк) Массив выражений с подстановкой (*), используемых для сопоставления имён потоков данных и индексов во время создания.

Elasticsearch включает несколько встроенных шаблонов индексов. Чтобы избежать коллизий имён с этими шаблонами, см. избегайте коллизий шаблонов индексов.

_meta

(Необязательно, объект) Необязательные пользовательские метаданные о шаблоне индекса. Может содержать любые данные. Эта карта не генерируется автоматически Elasticsearch.

priority

(Необязательно, целое число) Приоритет для определения приоритета шаблона индекса при создании или обновлении потока данных или индекса. Выбирается шаблон индекса с наивысшим приоритетом. Если приоритет не указан, шаблон рассматривается как имеющий приоритет 0 (наименьший приоритет). Это число не генерируется автоматически Elasticsearch.

template

(Необязательно, объект) Шаблон для применения. Он может необязательно включать конфигурацию aliases, mappings или settings.

Свойства объекта template

aliases

(Необязательно, объект объектов) Псевдонимы для добавления.

Если шаблон индекса включает объект data_stream, это псевдонимы потоков данных. В противном случае это псевдонимы индексов. Псевдонимы потоков данных игнорируют параметры index_routing, routing и search_routing.

Свойства объектов aliases

<alias>

(Обязательно, объект) Ключ — имя псевдонима. Имена псевдонимов индексов поддерживают математику дат.

Тело объекта содержит параметры для псевдонима. Поддерживается пустой объект.

Свойства объекта <alias>

filter: (Необязательно, объект Query DSL) Запрос, используемый для ограничения документов, к которым может получить доступ псевдоним.
index_routing: (Необязательно, строка) Значение, используемое для маршрутизации операций индексирования на определённый фрагмент. Если указано, это значение перекрывает значение routing для операций индексирования.
is_hidden: (Необязательно, Булево) Если true, псевдоним скрыт. По умолчанию false. Все индексы для псевдонима должны иметь одинаковое значение is_hidden.
is_write_index: (Необязательно, Булево) Если true, индекс является индексом записи для псевдонима. По умолчанию false.
routing: (Необязательно, строка) Значение, используемое для маршрутизации операций индексирования и поиска на определённый фрагмент.
search_routing: (Необязательно, строка) Значение, используемое для маршрутизации операций поиска на определённый фрагмент. Если указано, это значение перекрывает значение routing для операций поиска.

mappings

(Необязательно, объект отображения) Отображение для полей в индексе. Если указано, это отображение может включать:

См. Отображение.

settings

(Необязательно, объект настроек индекса) Параметры конфигурации индекса. См. Настройки индекса.

version

(Необязательно, целое число) Номер версии, используемый для внешнего управления шаблонами индексов. Это число не генерируется автоматически Elasticsearch.

deprecated

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

mapping_addition

(Необязательно, объект отображения) Определение отображения, которое будет объединённо с отображением индекса для проверки во время выполнения этого запроса.

Примеры

Использование существующих определений конвейера

В этом примере индекс index имеет конвейер по умолчанию, называемый my-pipeline, и конечный конвейер, называемый my-final-pipeline. Поскольку оба документа импортируются в index, оба конвейера выполняются с использованием определений конвейеров, которые уже находятся в системе.

resp = client.simulate.ingest(
    docs=[
        {
            "_index": "my-index",
            "_id": "123",
            "_source": {
                "foo": "bar"
            }
        },
        {
            "_index": "my-index",
            "_id": "456",
            "_source": {
                "foo": "rab"
            }
        }
    ],
)
print(resp)

response = client.simulate.ingest(
  body: {
    docs: [
      {
        _index: 'my-index',
        _id: '123',
        _source: {
          foo: 'bar'
        }
      },
      {
        _index: 'my-index',
        _id: '456',
        _source: {
          foo: 'rab'
        }
      }
    ]
  }
)
puts response

const response = await client.transport.request({
  method: "POST",
  path: "/_ingest/_simulate",
  body: {
    docs: [
      {
        _index: "my-index",
        _id: "123",
        _source: {
          foo: "bar",
        },
      },
      {
        _index: "my-index",
        _id: "456",
        _source: {
          foo: "rab",
        },
      },
    ],
  },
});
console.log(response);

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "foo": "rab"
      }
    }
  ]
}

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

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field1": "value1",
               "field2": "value2",
               "foo": "bar"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field1": "value1",
               "field2": "value2",
               "foo": "rab"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      }
   ]
}

Указание замены конвейера в теле запроса

В этом примере индекс my-index имеет конвейер по умолчанию, называемый my-pipeline, и конечный конвейер, называемый my-final-pipeline. Но в pipeline_substitutions предоставлено определение замены my-pipeline. Замена my-pipeline будет использоваться вместо my-pipeline, которое находится в системе, а затем будет выполнен my-final-pipeline, уже определённый в системе.

resp = client.simulate.ingest(
    docs=[
        {
            "_index": "my-index",
            "_id": "123",
            "_source": {
                "foo": "bar"
            }
        },
        {
            "_index": "my-index",
            "_id": "456",
            "_source": {
                "foo": "rab"
            }
        }
    ],
    pipeline_substitutions={
        "my-pipeline": {
            "processors": [
                {
                    "uppercase": {
                        "field": "foo"
                    }
                }
            ]
        }
    },
)
print(resp)

response = client.simulate.ingest(
  body: {
    docs: [
      {
        _index: 'my-index',
        _id: '123',
        _source: {
          foo: 'bar'
        }
      },
      {
        _index: 'my-index',
        _id: '456',
        _source: {
          foo: 'rab'
        }
      }
    ],
    pipeline_substitutions: {
      "my-pipeline": {
        processors: [
          {
            uppercase: {
              field: 'foo'
            }
          }
        ]
      }
    }
  }
)
puts response

const response = await client.transport.request({
  method: "POST",
  path: "/_ingest/_simulate",
  body: {
    docs: [
      {
        _index: "my-index",
        _id: "123",
        _source: {
          foo: "bar",
        },
      },
      {
        _index: "my-index",
        _id: "456",
        _source: {
          foo: "rab",
        },
      },
    ],
    pipeline_substitutions: {
      "my-pipeline": {
        processors: [
          {
            uppercase: {
              field: "foo",
            },
          },
        ],
      },
    },
  },
});
console.log(response);

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "bar"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "foo": "rab"
      }
    }
  ],
  "pipeline_substitutions": {
    "my-pipeline": {
      "processors": [
        {
          "uppercase": {
            "field": "foo"
          }
        }
      ]
    }
  }
}

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

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field2": "value2",
               "foo": "BAR"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "field2": "value2",
               "foo": "RAB"
            },
            "executed_pipelines": [
               "my-pipeline",
               "my-final-pipeline"
            ]
         }
      }
   ]
}

Указание замены шаблона компонента в теле запроса

В этом примере предположим, что индекс my-index имеет жёсткую сопоставление только с ключевым полем foo. Скажем, это сопоставление полей пришло из шаблона компонента, названного my-mappings-template. Мы хотим проверить добавление нового поля, bar. Поэтому в component_template_substitutions предоставлено определение замены my-mappings-template. Замена my-mappings-template будет использоваться вместо существующего сопоставления для my-index и вместо my-mappings-template, которое находится в системе.

resp = client.simulate.ingest(
    docs=[
        {
            "_index": "my-index",
            "_id": "123",
            "_source": {
                "foo": "foo"
            }
        },
        {
            "_index": "my-index",
            "_id": "456",
            "_source": {
                "bar": "rab"
            }
        }
    ],
    component_template_substitutions={
        "my-mappings_template": {
            "template": {
                "mappings": {
                    "dynamic": "strict",
                    "properties": {
                        "foo": {
                            "type": "keyword"
                        },
                        "bar": {
                            "type": "keyword"
                        }
                    }
                }
            }
        }
    },
)
print(resp)

const response = await client.transport.request({
  method: "POST",
  path: "/_ingest/_simulate",
  body: {
    docs: [
      {
        _index: "my-index",
        _id: "123",
        _source: {
          foo: "foo",
        },
      },
      {
        _index: "my-index",
        _id: "456",
        _source: {
          bar: "rab",
        },
      },
    ],
    component_template_substitutions: {
      "my-mappings_template": {
        template: {
          mappings: {
            dynamic: "strict",
            properties: {
              foo: {
                type: "keyword",
              },
              bar: {
                type: "keyword",
              },
            },
          },
        },
      },
    },
  },
});
console.log(response);

POST /_ingest/_simulate
{
  "docs": [
    {
      "_index": "my-index",
      "_id": "123",
      "_source": {
        "foo": "foo"
      }
    },
    {
      "_index": "my-index",
      "_id": "456",
      "_source": {
        "bar": "rab"
      }
    }
  ],
  "component_template_substitutions": {
    "my-mappings_template": {
      "template": {
        "mappings": {
          "dynamic": "strict",
          "properties": {
            "foo": {
              "type": "keyword"
            },
            "bar": {
              "type": "keyword"
            }
          }
        }
      }
    }
  }
}

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

{
   "docs": [
      {
         "doc": {
            "_id": "123",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "foo": "foo"
            },
            "executed_pipelines": []
         }
      },
      {
         "doc": {
            "_id": "456",
            "_index": "my-index",
            "_version": -3,
            "_source": {
               "bar": "rab"
            },
            "executed_pipelines": []
         }
      }
   ]
}

© 2023-2025 Elasticsearch
As of September 2024, Elasticsearch is available under a choice of three licenses: the Server Side Public License (SSPL), the Elastic License, or the AGPLv3 (OSI approved).
Elasticsearch and the Elasticsearch logo are trademarks of Elasticsearch B.V., registered in the U.S. and in other countries.
https://www.elastic.co/guide/en/elasticsearch/reference/8.17/simulate-ingest-api.html