› › ›

Предварительный просмотр API трансформации

Предварительный просмотр трансформации.

Запрос

GET _transform/<transform_id>/_preview

POST _transform/<transform_id>/_preview

GET _transform/_preview

POST _transform/_preview

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

Требуются следующие привилегии:

cluster: manage_transform (роль transform_admin предоставляет эту привилегию)
индексы-источники: read, view_index_metadata.

Описание

Этот API генерирует предварительный просмотр результатов, которые вы получите при запуске API создания трансформации с такой же конфигурацией. Он возвращает максимум 100 результатов. Вычисления основаны на всех текущих данных в индексе-источнике.

Он также генерирует список отображений и настроек для целевого индекса. Если целевой индекс не существует при запуске трансформации, используются именно эти отображения и настройки. Эти значения определяются на основе типов полей индекса-источника и агрегаций трансформации.

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

Вы должны выбрать либо метод latest, либо метод pivot для своей трансформации; вы не можете использовать оба в одной трансформации.

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

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

<transform_id>: (Необязательно, строка) Идентификатор трансформации для предварительного просмотра.

Если вы предоставите <transform_id> в качестве параметра пути, вы не сможете указать детали конфигурации трансформации в теле запроса.

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

timeout: (Необязательно, время) Период ожидания ответа. Если ответ не получен до истечения срока ожидания, запрос завершается ошибкой. По умолчанию 30s.

Тело запроса

description: (Необязательно, строка) Свободное текстовое описание преобразования.

dest

(Необязательно, объект) Назначение преобразования.

Свойства dest

index: (Необязательно, строка) Индекс назначения для преобразования.

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

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

pipeline: (Необязательно, строка) Уникальный идентификатор конвейера обработки данных.

frequency

(Необязательно, единицы измерения времени) Интервал между проверками изменений в исходных индексах во время непрерывной работы преобразования. Минимальное значение — 1s, максимальное — 1h. Значение по умолчанию — 1m.

latest

(Обязательно^*, объект) Метод latest преобразует данные, находя последний документ для каждого уникального ключа.

Свойства latest

sort: (Обязательно, строка) Указывает поле даты, используемое для определения последних документов.
unique_key: (Обязательно, массив строк) Указывает массив одного или нескольких полей, используемых для группировки данных.

pivot

(Обязательно, объект) Метод pivot преобразует данные, агрегируя и группируя их. Эти объекты определяют поля group by и агрегацию для уменьшения данных.

Свойства pivot

aggregations или aggs

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

group_by

(Обязательно, объект) Определяет, как сгруппировать данные. Для каждого сводного отчета можно определить несколько группировок. В настоящее время поддерживаются следующие группировки:

Свойства группировки могут необязательно иметь свойство missing_bucket. Если оно равно true, документы без значения в соответствующем поле group_by включаются. По умолчанию false.

retention_policy

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

Свойства retention_policy

time

(Обязательно, объект) Указывает, что преобразование использует поле времени для установки политики удержания. Данные удаляются, если time.field для политики удержания существует и содержит данные старше max.age.

Свойства time

field: (Обязательно, строка) Поле даты, используемое для расчета возраста документа. Установите time.field на существующее поле даты.
max_age: (Обязательно, единицы измерения времени) Указывает максимальный возраст документа в индексе назначения. Документы, старше указанного значения, удаляются из индекса назначения.

source

(Обязательно, объект) Источник данных для преобразования.

Свойства source

index: (Обязательно, строка или массив) Исходные индексы для преобразования. Это может быть один индекс, шаблон индекса (например, "my-index-*"), массив индексов (например, ["my-index-000001", "my-index-000002"]) или массив шаблонов индексов (например, ["my-index-*", "my-other-index-*"]. Для удалённых индексов используйте синтаксис "remote_name:index_name".

Если какие-либо индексы находятся в удалённых кластерах, у узла-мастера и по крайней мере одного узла преобразования должен быть узел роли remote_cluster_client.
query: (Необязательно, объект) Оператор запроса, который извлекает подмножество данных из исходного индекса. См. Query DSL.
runtime_mappings: (Необязательно, объект) Определения полей времени выполнения для поиска, которые могут использоваться преобразованием. Для полей времени выполнения поиска все узлы данных, включая удалённые узлы, должны быть версии 7.12 или выше.

sync

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

Свойства sync

time

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

Свойства time

delay: (Необязательный, единицы времени) Задержка времени между текущим временем и временем последних входных данных. Значение по умолчанию — 60s.
field: (Необязательный, строка) Поле даты, используемое для идентификации новых документов в исходном источнике.

settings

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

Свойства settings

align_checkpoints: (Необязательный, булево) Указывает, следует ли оптимизировать диапазоны контрольных точек преобразования для повышения производительности. Такая оптимизация может согласовать диапазоны контрольных точек с интервалом гистограммы дат, если гистограмма дат указана в качестве исходного источника группы в конфигурации преобразования. В результате будет выполнено меньше обновлений документов в целевом индексе, что повысит общую производительность. Значение по умолчанию — true, что означает, что диапазоны контрольных точек будут оптимизированы, если это возможно.
dates_as_epoch_millis: (Необязательный, булево) Определяет, должны ли даты в выводе записываться в формате ISO (по умолчанию) или в миллисекундах с начала эпохи. epoch_millis было значением по умолчанию для преобразований, созданных до версии 7.11. Для совместимого вывода установите это значение в true. Значение по умолчанию — false.
deduce_mappings: (Необязательный, булево) Указывает, следует ли выводить соответствия целевого индекса из конфигурации преобразования. Значение по умолчанию — true, что означает, что соответствия целевого индекса будут выведены, если это возможно.
docs_per_second: (Необязательный, число с плавающей точкой) Указывает ограничение на количество входных документов в секунду. Этот параметр ограничивает преобразование, добавляя время ожидания между запросами поиска. Значение по умолчанию — null, что отключает ограничение.
max_page_search_size: (Необязательный, целое число) Определяет начальный размер страницы для составной агрегации для каждой контрольной точки. При возникновении исключений блокировки схемы размер страницы динамически корректируется до меньшего значения. Минимальное значение — 10, максимальное — 65,536. Значение по умолчанию — 500.
unattended: (Необязательный, булево) Если true, преобразование выполняется в автономном режиме. В автономном режиме преобразование бесконечно повторяет попытки в случае ошибки, что означает, что преобразование никогда не завершается ошибкой. Установка количества попыток, отличных от бесконечного, приводит к ошибке валидации. По умолчанию значение равно false.

Тело ответа

generated_dest_index

(объект) Содержит подробности о целевом индексе.

Свойства generated_dest_index

aliases: (объект) Псевдонимы для целевого индекса.
mappings: (объект) Сопоставления для каждого документа в целевом индексе.
settings: (объект) Параметры индекса для целевого индекса.

preview

(массив) Массив документов. В частности, это JSON-представление документов, которые будут созданы в целевом индексе преобразованием.

Примеры

resp = client.transform.preview_transform(
    source={
        "index": "kibana_sample_data_ecommerce"
    },
    pivot={
        "group_by": {
            "customer_id": {
                "terms": {
                    "field": "customer_id",
                    "missing_bucket": True
                }
            }
        },
        "aggregations": {
            "max_price": {
                "max": {
                    "field": "taxful_total_price"
                }
            }
        }
    },
)
print(resp)

const response = await client.transform.previewTransform({
  source: {
    index: "kibana_sample_data_ecommerce",
  },
  pivot: {
    group_by: {
      customer_id: {
        terms: {
          field: "customer_id",
          missing_bucket: true,
        },
      },
    },
    aggregations: {
      max_price: {
        max: {
          field: "taxful_total_price",
        },
      },
    },
  },
});
console.log(response);

POST _transform/_preview
{
  "source": {
    "index": "kibana_sample_data_ecommerce"
  },
  "pivot": {
    "group_by": {
      "customer_id": {
        "terms": {
          "field": "customer_id",
          "missing_bucket": true
        }
      }
    },
    "aggregations": {
      "max_price": {
        "max": {
          "field": "taxful_total_price"
        }
      }
    }
  }
}

Данные, возвращаемые для этого примера, следующие:

{
  "preview" : [
    {
      "max_price" : 171.0,
      "customer_id" : "10"
    },
    {
      "max_price" : 233.0,
      "customer_id" : "11"
    },
    {
      "max_price" : 200.0,
      "customer_id" : "12"
    }
    ...
  ],
  "generated_dest_index" : {
    "mappings" : {
      "_meta" : {
        "_transform" : {
          "transform" : "transform-preview",
          "version" : {
            "created" : "7.7.0"
          },
          "creation_date_in_millis" : 1584738236757
        },
        "created_by" : "transform"
      },
      "properties" : {
        "max_price" : {
          "type" : "half_float"
        },
        "customer_id" : {
          "type" : "keyword"
        }
      }
    },
    "settings" : {
      "index" : {
        "number_of_shards" : "1",
        "auto_expand_replicas" : "0-1"
      }
    },
    "aliases" : { }
  }
}

© 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/preview-transform.html