Перейти к основному содержимому

Справочник по Elasticsearch

СПРАВОЧНИК

Назначение​

CLI, конфигурация и типовые сценарии Elasticsearch (DevOps, CI/CD, инфраструктура). Учебный курс: [раздел](/encyclopedia/8-infra-security/8.04. DevOps, CI-CD/intro).

Краткое пояснение​

Elasticsearch предоставляет три уровня управления конфигурацией:

Быстрый старт​

ЗадачаПодсказка
Установкаофициальная документация Elasticsearch
Типовая командасм. таблицы CLI ниже
CIпеременные окружения и секреты в pipeline

Справочные таблицы​

Содержание справочника​

Общая архитектура и уровни настроек​

Elasticsearch предоставляет три уровня управления конфигурацией:

  • Конфигурационные файлы — постоянные настройки, задаваемые в elasticsearch.yml (основной файл), jvm.options, log4j2.properties.
  • Кластерные настройки — динамически изменяемые параметры через Cluster Settings API, разделённые на:
    • Persistent — сохраняются после перезапуска кластера.
    • Transient — действуют до перезапуска узла или кластера.
  • Настройки индекса — применяются к отдельным индексам или шаблонам индексов, включают маппинг и параметры хранения.

Все эти уровни могут взаимодействовать: например, кластерные настройки переопределяют значения из elasticsearch.yml, а настройки индекса — поведение по умолчанию для конкретных данных.

Основные категории настроек​

1. Настройки узла и кластера​

Эти параметры определяют идентификацию, сетевое взаимодействие и поведение узлов в кластере.

  • cluster.name — имя кластера; все узлы с одинаковым именем объединяются в один кластер.
  • node.name — уникальное имя узла внутри кластера.
  • node.roles — список ролей узла, например:
    • master — участие в выборах лидера и управление состоянием кластера.
    • Данные — хранение и обработка данных.
    • ingest — предварительная обработка входящих документов.
    • ml — выполнение задач машинного обучения.
    • remote_cluster_client — подключение к удалённым кластерам.
  • path.Данные — каталоги для хранения данных индексов.
  • path.logs — каталог для логов.
  • bootstrap.memory_lock — блокировка памяти в RAM, предотвращающая свопинг.
  • Сеть.host — IP-адрес или интерфейс, на котором узел принимает соединения.
  • http.port — порт для HTTP-интерфейса (по умолчанию 9200).
  • transport.port — порт для внутреннего транспортного протокола между узлами (по умолчанию 9300).

2. Настройки производительности и ресурсов​

  • indices.memory.index_buffer_size — доля heap-памяти, выделяемая для буферизации индексируемых документов (по умолчанию 10%).
  • thread_pool.* — параметры пулов потоков для различных операций:
    • write — индексация и обновление.
    • search — выполнение поисковых запросов.
    • get — получение документов по ID.
    • bulk — массовые операции.
    • Каждый пул имеет подпараметры: size, queue_size, keep_alive.
  • indices.fielddata.cache.size — максимальный размер кэша fielddata (устаревший механизм, заменён на doc_values).
  • search.max_buckets — ограничение на количество агрегационных бакетов в одном запросе (по умолчанию 10 000).
  • action.destructive_requires_name — требует явного указания имени индекса при удалении, запрещая использование _all.

3. Настройки отказоустойчивости и безопасности​

  • discovery.seed_hosts — список хостов для начального обнаружения других узлов.
  • cluster.initial_master_nodes — список узлов, участвующих в первоначальном формировании кластера (требуется при первом запуске).
  • xpack.Безопасность.enabled — включение модуля безопасности (аутентификация, авторизация, TLS).
  • xpack.monitoring.enabled — сбор метрик мониторинга.
  • xpack.watcher.enabled — включение Watcher для реакции на события.
  • xpack.ml.enabled — активация функций машинного обучения.

Настройки индекса (Index Settings)​

Каждый индекс имеет два типа настроек:

  • Static settings — задаются при создании индекса и не могут быть изменены без пересоздания.
  • Dynamic settings — можно менять в любой момент через Update Index Settings API.

Static settings​

  • index.number_of_shards — количество первичных шардов; фиксируется при создании индекса.
  • index.number_of_routing_shards — базовое число шардов для будущего масштабирования (например, split).
  • index.codec — алгоритм сжатия данных (например, default, best_compression).
  • index.routing.allocation.include/exclude/require — правила размещения шардов на узлах по атрибутам (_name, _ip, _host, пользовательские теги).
  • index.soft_deletes.enabled — включение механизма мягких удалений (по умолчанию включено с версии 7.0).
  • index.hidden — скрытие индекса из обычных операций (используется системными индексами).

Dynamic settings​

  • index.number_of_replicas — количество реплик для каждого шарда.
  • index.refresh_interval — интервал автообновления индекса (по умолчанию 1s). Значение -1 отключает автообновление.
  • index.max_result_window — максимальное значение from + size в поисковых запросах (по умолчанию 10 000).
  • index.max_inner_result_window — аналогично для вложенных агрегаций.
  • index.max_rescore_window — ограничение на rescore запросы.
  • index.max_docvalue_fields_search — максимум полей docvalue_fields в одном запросе.
  • index.max_script_fields — максимум полей, вычисляемых скриптами.
  • index.max_ngram_diff — разница между max_gram и min_gram в анализаторах ngram.
  • index.max_shingle_diff — аналогично для shingle-анализаторов.
  • index.blocks.read_only — перевод индекса в режим «только чтение».
  • index.blocks.read — полная блокировка чтения.
  • index.blocks.write — блокировка записи.
  • index.blocks.metadata — блокировка изменения метаданных.

Маппинг (Mapping)​

Маппинг определяет структуру документов в индексе: типы полей, анализаторы, индексацию.

Основные поля маппинга​

  • type — тип данных:
    • text — полнотекстовый поиск с анализом.
    • keyword — точное совпадение, агрегации, сортировка.
    • long, integer, short, byte — целые числа.
    • double, float, half_float, scaled_float — числа с плавающей точкой.
    • date — дата и время.
    • boolean — логическое значение.
    • binary — закодированные в base64 данные.
    • object — вложенный объект.
    • nested — массив объектов с независимым контекстом.
    • geo_point, geo_shape — географические данные.
    • ip — IP-адрес.
    • completion — автозаполнение.
    • flattened — динамический объект без строгого маппинга.
    • rank_feature, rank_features — для ранжирования.
    • constant_keyword — поле с фиксированным значением.
    • alias — псевдоним для другого поля.
    • histogram — статистические гистограммы.

Параметры полей​

  • index — индексировать ли поле (true/false).
  • analyzer — анализатор для text-полей.
  • search_analyzer — анализатор, используемый только при поиске.
  • norms — хранить ли нормализационные факторы для ранжирования.
  • doc_values — использовать ли колоночное хранение для сортировки и агрегаций.
  • store — хранить ли исходное значение отдельно от _source.
  • fielddata — загружать ли данные в память для сортировки text-полей (не рекомендуется).
  • format — формат даты (например, yyyy-MM-dd).
  • ignore_malformed — пропускать некорректные значения вместо ошибки.
  • null_value — значение по умолчанию для null.
  • copy_to — копирование значения в другое поле.
  • enabled — отключает индексацию для object или всего документа.
  • dynamic — поведение при появлении новых полей:
    • true — автоматически добавлять.
    • runtime — создавать runtime-поле.
    • strict — выдавать ошибку.
    • false — игнорировать.

Анализаторы (Analyzers)​

Анализаторы преобразуют входной текст в токены, которые индексируются и используются при поиске. Каждый text-поле может иметь собственный анализатор или использовать значение по умолчанию.

Стандартные анализаторы​

  • standard — анализатор по умолчанию:
    • Разбивает текст по пробелам и пунктуации.
    • Приводит к нижнему регистру.
    • Поддерживает Unicode.
  • simple — разбивает по не-буквенным символам, приводит к нижнему регистру.
  • whitespace — разбивает только по пробелам.
  • keyword — не разбивает текст, сохраняет как единый токен.
  • pattern — разбивает по регулярному выражению.
  • stop — как simple, но удаляет стоп-слова.
  • language — морфологические анализаторы для конкретных языков (english, russian, french и др.).

Компоненты анализаторов​

Анализатор состоит из:

  • Tokenizer — обязательный компонент, разбивающий строку на токены.
  • Token filters — необязательные фильтры, преобразующие токены:
    • lowercase — приведение к нижнему регистру.
    • asciifolding — замена диакритических знаков.
    • stemmer — стемминг (например, porter_stem).
    • snowball — морфологический стемминг.
    • synonym — замена синонимов.
    • stop — удаление стоп-слов.
    • ngram, edge_ngram — генерация n-грамм.
  • Char filters — предварительная обработка символов:
    • html_strip — удаление HTML-тегов.
    • mapping — замена отдельных символов.
    • pattern_replace — замена по регулярному выражению.

Настройка пользовательского анализатора​

Пример определения в маппинге:

{
  "settings": {
    "analysis": {
      "analyzer": {
        "my_russian_analyzer": {
          "type": "custom",
          "tokenizer": "standard",
          "filter": ["lowercase", "russian_morphology"]
        }
      }
    }
  }
}

Запросы (Queries)​

Elasticsearch Query DSL — декларативный язык запросов, основанный на JSON.

Основные типы запросов​

  • match — полнотекстовый поиск с анализом.
  • match_phrase — фразовый поиск.
  • term — точное совпадение (для keyword, чисел, дат).
  • terms — совпадение с одним из значений списка.
  • range — диапазон значений (gte, lte, gt, lt).
  • exists — проверка наличия поля.
  • prefix, wildcard, regexp — поиск по шаблону.
  • fuzzy — нечёткий поиск (Levenshtein distance).
  • bool — комбинирование запросов:
    • must — обязательные условия.
    • should — альтернативные условия.
    • must_not — исключения.
    • filter — условия без влияния на релевантность.
  • multi_match — поиск по нескольким полям.
  • query_string — синтаксис Lucene в строке.
  • simple_query_string — упрощённый синтаксис без ошибок разбора.
  • nested — запрос к вложенным объектам.
  • has_child, has_parent — связь между родительскими и дочерними документами.
  • geo_distance, geo_bounding_box, geo_polygon — геопространственные запросы.

Параметры поиска​

  • from, size — пагинация.
  • _source — фильтрация возвращаемых полей.
  • sort — сортировка по полю, скрипту или геодистанции.
  • highlight — подсветка совпадений.
  • aggregations — аналитические группировки.
  • explain — детализация расчёта релевантности.
  • track_total_hits — управление точностью общего числа результатов.
  • min_score — минимальный порог релевантности.
  • timeout — ограничение времени выполнения.

Агрегации (Aggregations)​

Агрегации позволяют выполнять аналитику поверх данных: группировки, статистика, гистограммы.

Типы агрегаций​

  • Bucket aggregations — создают корзины (группы):
    • terms — группировка по значениям поля.
    • date_histogram — временные интервалы.
    • range — числовые диапазоны.
    • histogram — числовые бакеты фиксированного размера.
    • filters — несколько условий одновременно.
    • geohash_grid — географическая сетка.
    • children, parent, nested — агрегации по иерархии.
  • Metric aggregations — вычисляют метрики:
    • avg, sum, min, max, stats, extended_stats.
    • cardinality — приблизительное число уникальных значений.
    • percentiles, percentile_ranks.
    • top_hits — наиболее релевантные документы в бакете.
  • Pipeline aggregations — работают с результатами других агрегаций:
    • derivative — производная.
    • moving_avg — скользящее среднее.
    • cumulative_sum — накопительная сумма.
    • bucket_script — произвольные вычисления через скрипты.

Параметры агрегаций​

  • size — количество возвращаемых бакетов.
  • shard_size — количество бакетов на шард (для повышения точности).
  • min_doc_count — минимальное число документов в бакете.
  • order — сортировка бакетов.
  • missing — значение по умолчанию для отсутствующих полей.
  • collect_mode — стратегия сбора данных (depth_first, breadth_first).

Runtime-поля (Runtime Fields)​

Runtime-поля вычисляются при запросе, не хранятся на диске.

Особенности​

  • Определяются в маппинге или в теле запроса.
  • Используют Painless-скрипты.
  • Могут ссылаться на другие поля, включая _source.
  • Поддерживают все типы данных, кроме text (но можно создать keyword на основе текста).
  • Увеличивают время выполнения запроса, но экономят место на диске.

Пример​

{
  "runtime_mappings": {
    "day_of_week": {
      "type": "keyword",
      "script": {
        "source": "emit(doc['timestamp'].value.dayOfWeekEnum.toString())"
      }
    }
  }
}

Searchable Snapshots​

Searchable Snapshots позволяют выполнять поиск непосредственно по данным в репозитории снапшотов, без полной загрузки в кластер.

Режимы​

  • Cold tier — частичная загрузка: только метаданные и индексные структуры.
  • Frozen tier — минимальная загрузка: только при необходимости чтения данных.

Преимущества​

  • Снижение затрат на хранение горячих данных.
  • Возможность анализа архивных данных без восстановления.

Ограничения​

  • Медленный поиск.
  • Нет поддержки update, delete, reindex.

Использование​

POST /_snapshot/my_repo/my_snapshot/_mount?wait_for_completion=true
{
  "index": "logs-2020",
  "renamed_index": "logs-2020-frozen",
  "index_settings": {
    "index.number_of_replicas": 0
  },
  "ignore_index_settings": ["index.refresh_interval"]
}

Асинхронный поиск позволяет выполнять длительные запросы без таймаута.

Особенности​

  • Запрос возвращается немедленно с ID.
  • Результаты можно получать частями.
  • Поддерживает пагинацию и отмену.

API​

  • POST /_async_search — запуск.
  • GET /_async_search/{id} — получение результата.
  • DELETE /_async_search/{id} — отмена.

Параметры​

  • keep_alive — время хранения результата (по умолчанию 5d).
  • wait_for_completion_timeout — максимальное время синхронного ожидания.

SQL over Elasticsearch​

Elasticsearch предоставляет SQL-интерфейс для выполнения запросов через REST API.

Поддерживаемые операции​

  • SELECT
  • SHOW TABLES, SHOW COLUMNS
  • DESCRIBE

Ограничения​

  • Нет поддержки JOIN, SUBQUERY, UNION.
  • Нет DDL/DML (CREATE, INSERT, UPDATE).

Пример​

POST /_sql
{
  "query": "SELECT avg(price) FROM sales WHERE region = 'EU' GROUP BY product"
}

Также доступен JDBC-драйвер и CLI-клиент.

Event Query Language (EQL)​

EQL — язык для поиска последовательностей событий во временных рядах.

Особенности​

  • Поддержка sequence, join, pipe.
  • Оптимизирован для безопасности и логов.

Пример​

POST /my-logs/_eql/search
{
  "query": """
    sequence by process_id
      [process where event_type == "start"]
      [process where event_type == "stop"]
  """
}

Поддержка поиска по векторным представлениям (embedding).

Тип поля​

  • dense_vector — фиксированной длины массив чисел.
  • sparse_vector — разреженный вектор (начиная с 8.10).

Настройки​

  • index — true/false.
  • similarity — l2_norm, dot_product, cosine.
  • index_options — ef_construction, m.

Поиск​

  • knn — k-nearest neighbors.
  • script_score — кастомные функции расстояния.

Пример​

PUT my-index
{
  "mappings": {
    "properties": {
      "embedding": { "type": "dense_vector", "dims": 768, "index": true, "similarity": "cosine" }
    }
  }
}

POST my-index/_search
{
  "knn": {
    "field": "embedding",
    "query_vector": [...],
    "k": 5,
    "num_candidates": 10
  }
}

Enrich Processors​

Обогащение документов данными из других индексов при индексации.

Типы политик​

  • match — точное совпадение.
  • geo_match — географическое совпадение.

Этапы​

  1. Создание политики обогащения.
  2. Выполнение enrich.execute_policy.
  3. Использование процессора enrich в ingest pipeline.

Пример​

PUT /_enrich/policy/user_lookup
{
  "match": {
    "indices": ["users"],
    "match_field": "email",
    "enrich_fields": ["name", "department"]
  }
}

POST /_enrich/policy/user_lookup/_execute

PUT _ingest/pipeline/enrich_user
{
  "processors": [
    {
      "enrich": {
        "policy_name": "user_lookup",
        "field": "user_email",
        "target_field": "user_info"
      }
    }
  ]
}

Система Indices​

Системные индексы начинаются с точки (.) и используются внутренними функциями.

Примеры​

  • .Безопасность-* — пользователи, роли.
  • .watches, .triggered_watches — Watcher.
  • .ml-* — Machine Learning.
  • .transform-* — Transform jobs.
  • .monitoring-* — мониторинг.
  • .kibana_* — данные Kibana.

Управление​

  • Скрыты по умолчанию.
  • Не удаляются обычными командами.
  • Имеют специальные права доступа.

Cluster Coordination​

Механизм выбора лидера и согласования состояния кластера.

Компоненты​

  • Master-eligible nodes — участвуют в выборах.
  • Voting configuration — набор узлов, имеющих право голоса.
  • Quorum — большинство голосов для принятия решений.

Настройки​

  • cluster.initial_master_nodes — обязательна при первом запуске.
  • discovery.seed_hosts — список узлов для обнаружения.
  • cluster.routing.allocation.enable — управление размещением шардов.

Проблемы​

  • Split-brain — разделение кластера на части.
  • Master flapping — частая смена лидера.

Recovery и Allocation​

Процессы восстановления и размещения шардов.

Recovery Types​

  • Peer recovery — между узлами.
  • Snapshot recovery — из снапшота.
  • Local recovery — после перезапуска узла.

Allocation Settings​

  • cluster.routing.allocation.enable — all, primaries, new_primaries, none.
  • index.routing.allocation.* — правила размещения по атрибутам.
  • cluster.routing.allocation.disk.* — пороги использования диска.

Мониторинг​

  • _cat/recovery
  • _cluster/allocation/explain

Shard Management​

Управление шардами: количество, размер, балансировка.

Рекомендации​

  • Шард не должен превышать 50 ГБ.
  • Избегать слишком большого числа шардов (>1000 на узел).
  • Использовать shrink и split для изменения количества.

API​

  • _shrink — уменьшение числа шардов.
  • _split — увеличение (требует index.number_of_routing_shards).
  • _rollover — создание нового индекса по условию.

Plugins​

Расширения функциональности Elasticsearch.

Типы​

  • Core plugins — встроены (например, ingest-attachment, analysis-icu).
  • Community plugins — сторонние (например, elasticsearch-sql).

Управление​

  • bin/elasticsearch-plugin list
  • bin/elasticsearch-plugin install name
  • bin/elasticsearch-plugin remove name

REST API Reference​

Основные категории API:

  • Document APIs: index, get, delete, update, bulk.
  • Search APIs: search, scroll, msearch, explain, validate.
  • Index APIs: create, delete, close, open, refresh, flush.
  • Cluster APIs: health, state, stats, pending_tasks, reroute.
  • Cat APIs: человекочитаемые таблицы (_cat/indices, _cat/nodes).
  • Задачи API: управление фоновыми задачами.
  • Scripts API: управление скриптами.

Painless Scripting​

Встроенный язык скриптов, безопасный и быстрый.

Контексты​

  • Ingest — при обработке документа.
  • Update — при обновлении.
  • Score — при ранжировании.
  • Aggregation — в bucket_script и scripted_metric.

Особенности​

  • Строгая типизация.
  • Нет доступа к файловой системе или сети.
  • Автоматическая компиляция и кэширование.

Пример​

if (doc['price'].value > 100) {
  emit('expensive');
} else {
  emit('cheap');
}

Performance Tuning​

Heap​

  • Не более 50% RAM, максимум 32 ГБ.
  • Отключить свопинг (bootstrap.memory_lock: true).

Storage​

  • SSD предпочтительны.
  • Отдельный диск для данных и логов.

Indexing​

  • Использовать bulk-запросы.
  • Отключить refresh_interval при массовой загрузке.
  • Увеличить translog.flush_threshold_size.

Searching​

  • Ограничивать size и from.
  • Использовать filter вместо must при возможности.
  • Избегать script_fields в production.

Troubleshooting​

Частые проблемы​

  • Yellow/Red cluster status — недостающие реплики или первичные шарды.
  • High CPU — сложные скрипты, агрегации, поиск.
  • Disk watermark — нехватка места на диске.
  • Thread pool rejections — перегрузка пулов потоков.

Инструменты​

  • _cluster/health
  • _nodes/stats
  • _tasks
  • _cat/thread_pool
  • Slow logs (index.search.slowlog.threshold.query.warn)

Ошибки​

СитуацияЧто проверить
Команда не найденаPATH, установка пакета, alias
Permission deniedпользователь, группа, sudo, ACL
Неверная версиясм. «Совместимость», --version

Совместимость​

ОбластьПримечание
Версииактуальные LTS/стабильные релизы Elasticsearch
Платформыофициальная матрица поддержки вендора
СтандартыRFC, ISO, спецификация API — см. таблицы выше

См. также

Другие статьи этого же раздела в боковом меню (как на странице «О разделе»).

Ещё 28 статей в разделе

Освоение главы0%