› › ›

Предлагаемые значения

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

POST my-index-000001/_search
{
  "query" : {
    "match": {
      "message": "tring out Elasticsearch"
    }
  },
  "suggest" : {
    "my-suggestion" : {
      "text" : "tring out Elasticsearch",
      "term" : {
        "field" : "message"
      }
    }
  }
}

Запрос

Функция предложения предлагает похожие по написанию термины, основанные на предоставленном тексте, используя предложенный механизм. Часть запроса на предложение определяется наряду с частью запроса в запросе _search. Если часть запроса опущена, возвращаются только предложения.

Примеры

Несколько предложений могут быть указаны в запросе. Каждое предложение идентифицируется произвольным именем. В примере ниже запрошены два предложения. Оба предложения my-suggest-1 и my-suggest-2 используют механизм term, но имеют различное text.

POST _search
{
  "suggest": {
    "my-suggest-1" : {
      "text" : "tring out Elasticsearch",
      "term" : {
        "field" : "message"
      }
    },
    "my-suggest-2" : {
      "text" : "kmichy",
      "term" : {
        "field" : "user.id"
      }
    }
  }
}

Пример ответа на запрос о предложении включает ответ на предложение для my-suggest-1 и my-suggest-2. Каждая часть предложения содержит записи. Каждая запись фактически является токеном из предложенного текста и содержит текст записи предложения, исходный начальный смещение и длину в предложенном тексте и, если найдено, произвольное количество вариантов.

{
  "_shards": ...
  "hits": ...
  "took": 2,
  "timed_out": false,
  "suggest": {
    "my-suggest-1": [ {
      "text": "tring",
      "offset": 0,
      "length": 5,
      "options": [ {"text": "trying", "score": 0.8, "freq": 1 } ]
    }, {
      "text": "out",
      "offset": 6,
      "length": 3,
      "options": []
    }, {
      "text": "elasticsearch",
      "offset": 10,
      "length": 13,
      "options": []
    } ],
    "my-suggest-2": ...
  }
}

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

Глобальный предложенный текст

Чтобы избежать повторения предложенного текста, можно определить глобальный текст. В примере ниже предложенный текст определен глобально и применяется к предложениям my-suggest-1 и my-suggest-2.

POST _search
{
  "suggest": {
    "text" : "tring out Elasticsearch",
    "my-suggest-1" : {
      "term" : {
        "field" : "message"
      }
    },
    "my-suggest-2" : {
       "term" : {
        "field" : "user"
       }
    }
  }
}

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

Механизм предложений терминов

Механизм предложений term предлагает термины на основе расстояния редактирования. Предоставленный предложенный текст анализируется перед предложением терминов. Предлагаемые термины предоставляются по анализируемому токену предложенного текста. Механизм предложений term не учитывает запрос, который является частью запроса.

Общие параметры предложений:

`text`	Текст предложения. Текст предложения является обязательным параметром, который необходимо установить глобально или по предложению.
`field`	Поле для извлечения кандидатских предложений. Это обязательный параметр, который необходимо установить либо глобально, либо по предложению.
`analyzer`	Анализатор для анализа предложенного текста. По умолчанию используется анализатор поиска для поля предложений.
`size`	Максимальное количество исправлений, возвращаемых по каждому токену предложенного текста.
`sort`	Определяет, как должны сортироваться предложения по каждому термину предложенного текста. Два возможных значения: `score`: Сортировка по оценке сначала, затем по частоте в документах, а затем по самому термину. `frequency`: Сортировка по частоте в документах сначала, затем по оценке сходства, а затем по самому термину.
`suggest_mode`	Режим предложений управляет включением или исключением предложений или управляет тем, для каких токенов предложенного текста должны быть предложены предложения. Можно указать три возможных значения: `missing`: Предлагать предложения только для токенов предложенного текста, отсутствующих в индексе. Это значение по умолчанию. `popular`: Предлагать только предложения, встречающиеся в большем количестве документов, чем исходный термин предложенного текста. `always`: Предлагать любые совпадающие предложения, основанные на терминах в предложенном тексте.

Другие параметры предложений терминов:

`max_edits`	Максимальное расстояние редактирования, которое могут иметь кандидаты предложений, чтобы считаться предложением. Может принимать значения от 1 до 2. Любое другое значение приводит к ошибке плохого запроса. По умолчанию 2.
`prefix_length`	Количество минимальных префиксных символов, которые должны совпадать, чтобы стать кандидатом на предложение. По умолчанию 1. Увеличение этого значения повышает производительность проверки орфографии. Обычно ошибки в написании не встречаются в начале терминов.
`min_word_length`	Минимальная длина токена предложенного текста, которая должна быть для включения. По умолчанию `4`.
`shard_size`	Устанавливает максимальное количество предложений, которые необходимо извлечь из каждого отдельного фрагмента. На этапе сворачивания возвращаются только лучшие N предложений, основанные на параметре `size`. По умолчанию значение параметра `size`. Установка этого значения выше, чем параметр `size`, может быть полезно для получения более точной частоты в документах для исправлений орфографии за счет производительности. Из-за того, что термины распределены по фрагментам, частоты в документах на уровне фрагмента для исправлений орфографии могут быть неточными. Увеличение этого значения сделает эти частоты более точными.
`max_inspections`	Коэффициент, который используется для умножения на `shards_size`, чтобы просмотреть больше кандидатских исправлений орфографии на уровне фрагмента. Может улучшить точность за счет производительности. По умолчанию 5.
`min_doc_freq`	Минимальный порог количества документов, в которых должно появляться предложение. Может быть указано как абсолютное число или как относительный процент от количества документов. Это может улучшить качество, предлагая только термины с высокой частотой. По умолчанию 0f и отключен. Если указано значение больше 1, оно не может быть дробным. Для этого параметра используются частоты документов на уровне фрагмента.
`max_term_freq`	Максимальный порог количества документов, в которых может присутствовать токен предложенного текста, чтобы быть включенным. Может быть относительным процентным числом (например, 0,4) или абсолютным числом для представления частоты в документах. Если указано значение больше 1, оно не может быть дробным. По умолчанию 0.01f. Это может быть использовано для исключения терминов с высокой частотой — которые обычно написаны правильно — из проверки орфографии. Это также повышает производительность проверки орфографии. Для этого параметра используются частоты документов на уровне фрагмента.
`string_distance`	Реализация алгоритма вычисления расстояния между строками, которая должна использоваться для сравнения сходства предложенных терминов. Можно указать пять возможных значений: `internal`: По умолчанию, основанный на damerau_levenshtein, но сильно оптимизирован для сравнения расстояния между строками для терминов внутри индекса. `damerau_levenshtein`: Алгоритм вычисления расстояния между строками, основанный на алгоритме Дамерау-Левенштейна. `levenshtein`: Алгоритм вычисления расстояния между строками, основанный на алгоритме Левенштейна. `jaro_winkler`: Алгоритм вычисления расстояния между строками, основанный на алгоритме Яро-Винклера. `ngram`: Алгоритм вычисления расстояния между строками, основанный на n-граммах символов.

Предлагатель фраз

Предлагатель term предоставляет очень удобный API для доступа к альтернативам слов на основе каждого токена в пределах определённого расстояния по строкам. API позволяет получить доступ к каждому токену в потоке индивидуально, а выбор предложений остаётся на усмотрение потребителя API. Однако часто требуется предварительно выбранные предложения для отображения пользователю. Предлагатель phrase добавляет дополнительную логику поверх предлагателя term, чтобы выбрать целые исправленные фразы вместо отдельных токенов, взвешенных на основе моделей ngram-language. На практике этот предлагатель сможет принимать лучшие решения о выборе токенов на основе совместного появления и частот.

Пример API

В общем случае, для работы предлагателю phrase требуется специальное отображение заранее. Примеры предлагателя phrase на этой странице требуют следующего отображения для работы. Анализатор reverse используется только в последнем примере.

PUT test
{
  "settings": {
    "index": {
      "number_of_shards": 1,
      "analysis": {
        "analyzer": {
          "trigram": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["lowercase","shingle"]
          },
          "reverse": {
            "type": "custom",
            "tokenizer": "standard",
            "filter": ["lowercase","reverse"]
          }
        },
        "filter": {
          "shingle": {
            "type": "shingle",
            "min_shingle_size": 2,
            "max_shingle_size": 3
          }
        }
      }
    }
  },
  "mappings": {
    "properties": {
      "title": {
        "type": "text",
        "fields": {
          "trigram": {
            "type": "text",
            "analyzer": "trigram"
          },
          "reverse": {
            "type": "text",
            "analyzer": "reverse"
          }
        }
      }
    }
  }
}
POST test/_doc?refresh=true
{"title": "noble warriors"}
POST test/_doc?refresh=true
{"title": "nobel prize"}

После настройки анализаторов и отображений вы можете использовать предлагатель phrase в том же месте, где вы бы использовали предлагатель term:

POST test/_search
{
  "suggest": {
    "text": "noble prize",
    "simple_phrase": {
      "phrase": {
        "field": "title.trigram",
        "size": 1,
        "gram_size": 3,
        "direct_generator": [ {
          "field": "title.trigram",
          "suggest_mode": "always"
        } ],
        "highlight": {
          "pre_tag": "<em>",
          "post_tag": "</em>"
        }
      }
    }
  }
}

Ответ содержит предложения, упорядоченные по наиболее вероятной орфографической правке. В данном случае мы получили ожидаемую правку «нобелевская премия».

{
  "_shards": ...
  "hits": ...
  "timed_out": false,
  "took": 3,
  "suggest": {
    "simple_phrase" : [
      {
        "text" : "noble prize",
        "offset" : 0,
        "length" : 11,
        "options" : [ {
          "text" : "nobel prize",
          "highlighted": "<em>nobel</em> prize",
          "score" : 0.48614594
        }]
      }
    ]
  }
}

Основные параметры API для предложения фраз

`field`	Название поля, используемого для поиска n-грамм в модели языка; предлагатель будет использовать это поле для получения статистики для оценки исправлений. Это поле является обязательным.
`gram_size`	Устанавливает максимальный размер n-грамм (шингелов) в `field`. Если поле не содержит n-грамм (шингелов), это следует опустить или установить значение `1`. Обратите внимание, что Elasticsearch пытается определить размер граммы на основе указанного `field`. Если поле использует фильтр `shingle`, `gram_size` устанавливается в значение `max_shingle_size`, если не задано явно.
`real_word_error_likelihood`	Вероятность того, что термин написан неверно, даже если термин существует в словаре. По умолчанию это `0.95`, что означает, что 5% реальных слов написаны неправильно.
`confidence`	Уровень доверия определяет коэффициент, применяемый к оценке входных фраз, который используется в качестве порога для других кандидатов на предложение. Будут включены только кандидаты, чья оценка выше порога. Например, уровень доверия `1.0` вернёт только предложения, чья оценка выше оценки входной фразы. Если установлено значение `0.0`, возвращаются верхние N кандидатов. По умолчанию это `1.0`.
`max_errors`	Максимальный процент терминов, рассматриваемых как ошибки написания для формирования исправления. Этот метод принимает значение с плавающей точкой в диапазоне `[0..1)` в качестве доли фактических терминов запроса или числовое значение `>=1` в качестве абсолютного числа терминов запроса. По умолчанию установлено значение `1.0`, что означает, что возвращаются только исправления с не более чем одним неправильно написанным термином. Обратите внимание, что установка этого значения слишком высокой может негативно повлиять на производительность. Рекомендуются низкие значения, такие как `1` или `2`; в противном случае время, затраченное на вызовы предложения, может превысить время, затраченное на выполнение запроса.
`separator`	Разделитель, используемый для разделения терминов в поле биграмм. Если не указан, пробел используется в качестве разделителя.
`size`	Количество кандидатов, генерируемых для каждого отдельного термина запроса. Низкие значения, такие как `3` или `5`, обычно дают хорошие результаты. Повышение этого значения может привести к появлению терминов с большей дистанцией редактирования. По умолчанию это `5`.
`analyzer`	Устанавливает анализатор для анализа текста предложения. По умолчанию используется анализатор поиска поля предложения, переданного через `field`.
`shard_size`	Устанавливает максимальное количество предложенных терминов, которые должны быть получены с каждого отдельного фрагмента. Во время фазы уменьшения возвращаются только лучшие N предложений на основе параметра `size`. По умолчанию это `5`.
`text`	Устанавливает текст/запрос для генерации предложений.
`highlight`	Устанавливает выделение предложений. Если не указано, поле `highlighted` не возвращается. Если указано, должно содержать ровно `pre_tag` и `post_tag`, которые обрамляют изменённые токены. Если несколько токенов подряд изменены, вместо каждого токена обрамляется вся фраза изменённых токенов.
`collate`	Проверяет каждое предложение на соответствие указанному `query` для удаления предложений, для которых не существует соответствующих документов в индексе. Запрос collate для предложения выполняется только на локальном фрагменте, из которого было сгенерировано предложение. `query` должен быть указан и может быть шаблоном. См. Шаблоны поиска. Текущее предложение автоматически доступно как переменная `{{suggestion}}`, которую следует использовать в вашем запросе. Вы всё ещё можете указать свой собственный шаблон `params` — значение `suggestion` будет добавлено к переменным, которые вы указали. Кроме того, вы можете указать `prune` для управления возвращением всех предложений фразы; при установке значения `true` предложения будут иметь дополнительный параметр `collate_match`, который будет `true`, если для фразы были найдены соответствующие документы, и `false` в противном случае. Значение по умолчанию для `prune` — `false`.

POST test/_search
{
  "suggest": {
    "text" : "noble prize",
    "simple_phrase" : {
      "phrase" : {
        "field" :  "title.trigram",
        "size" :   1,
        "direct_generator" : [ {
          "field" :            "title.trigram",
          "suggest_mode" :     "always",
          "min_word_length" :  1
        } ],
        "collate": {
          "query": { 
            "source" : {
              "match": {
                "{{field_name}}" : "{{suggestion}}" 
              }
            }
          },
          "params": {"field_name" : "title"}, 
          "prune": true 
        }
      }
    }
  }
}

	Этот запрос будет выполняться один раз для каждого предложения.
	Переменная `{{suggestion}}` будет заменена текстом каждого предложения.
	Дополнительная переменная `field_name` была указана в `params` и используется в запросе `match`.
	Все предложения будут возвращены с дополнительным параметром `collate_match`, указывающим, совпадает ли сгенерированная фраза с каким-либо документом.

Модели сглаживания

Предлагатель phrase поддерживает несколько моделей сглаживания для балансировки весов между редкими граммами (граммы (шингелы) отсутствуют в индексе) и частыми граммами (появляются как минимум один раз в индексе). Модель сглаживания может быть выбрана, установив параметр smoothing на одно из следующих значений. Каждая модель сглаживания поддерживает определённые свойства, которые можно настроить.

`stupid_backoff`	Простая модель отката, которая откатывается к моделям n-грамм более низкого порядка, если счётчик более высокого порядка `0`, и дисконтирует модель n-грамм более низкого порядка на постоянный коэффициент. Значение по умолчанию `discount` равно `0.4`. Модель Stupid Backoff является моделью по умолчанию.
`laplace`	Модель сглаживания, которая использует сглаживание с добавлением константы (обычно `1.0` или меньше) ко всем счётам для балансировки весов. Значение по умолчанию `alpha` равно `0.5`.
`linear_interpolation`	Модель сглаживания, которая берёт взвешенное среднее арифметическое униграмм, биграмм и триграмм на основе предоставленных пользователем весов (лямбда). Линейная интерполяция не имеет значений по умолчанию. Все параметры (`trigram_lambda`, `bigram_lambda`, `unigram_lambda`) должны быть указаны.

POST test/_search
{
  "suggest": {
    "text" : "obel prize",
    "simple_phrase" : {
      "phrase" : {
        "field" : "title.trigram",
        "size" : 1,
        "smoothing" : {
          "laplace" : {
            "alpha" : 0.7
          }
        }
      }
    }
  }
}

Генераторы кандидатов

Предлагатель phrase использует генераторы кандидатов для создания списка возможных терминов для каждого термина в заданном тексте. Один генератор кандидатов аналогичен предлагателю term, вызываемому для каждого отдельного термина в тексте. Результаты генераторов впоследствии оцениваются совместно с кандидатами от других терминов для кандидатов предложений.

В настоящее время поддерживается только один тип генератора кандидатов — direct_generator. API предложений фраз принимает список генераторов по ключу direct_generator; каждый генератор в списке вызывается для каждого термина в исходном тексте.

Прямые генераторы

Прямые генераторы поддерживают следующие параметры:

`field`	Поле для извлечения предложений-кандидатов. Это обязательный параметр, который должен быть задан либо глобально, либо для каждого предложения.
`size`	Максимальное количество исправлений, возвращаемых на один токен текста предложения.
`suggest_mode`	Режим предложений контролирует, какие предложения включаются в предложения, сгенерированные на каждом фрагменте. Все значения, кроме `always`, можно рассматривать как оптимизацию для генерации меньшего количества предложений для проверки на каждом фрагменте, и они не проверяются повторно при объединении предложений, сгенерированных на каждом фрагменте. Таким образом, `missing` сгенерирует предложения для терминов на фрагментах, которые их не содержат, даже если другие фрагменты содержат их. Их следует отфильтровать с помощью `confidence`. Можно указать три возможных значения: `missing`: Генерировать предложения только для терминов, которые отсутствуют на фрагменте. Это значение по умолчанию. `popular`: Предлагать только термины, которые встречаются в документе на фрагменте чаще, чем исходный термин. `always`: Предложить любые подходящие предложения на основе терминов в тексте предложения.
`max_edits`	Максимальное расстояние редактирования, которое могут иметь предложения-кандидаты, чтобы быть рассмотренными как предложение. Может принимать значения от 1 до 2. Любое другое значение приводит к ошибке запроса. По умолчанию 2.
`prefix_length`	Количество минимальных символов префикса, которые должны совпадать, чтобы быть кандидатом в предложения. По умолчанию 1. Увеличение этого значения улучшает производительность проверки правописания. Ошибки в написании, как правило, не возникают в начале терминов.
`min_word_length`	Минимальная длина термина предложения, необходимая для включения. По умолчанию 4.
`max_inspections`	Коэффициент, который используется для умножения на `shards_size`, чтобы проверить больше предложений-кандидатов на уровне фрагмента. Может улучшить точность за счет производительности. По умолчанию 5.
`min_doc_freq`	Минимальный порог количества документов, в которых должно появляться предложение. Это может быть указано как абсолютное число или как относительный процент от количества документов. Это может повысить качество, предлагая только термины с высокой частотой. По умолчанию 0f и не включено. Если указано значение больше 1, то число не может быть дробным. Для этого параметра используются частоты документов на уровне фрагмента.
`max_term_freq`	Максимальный порог количества документов, в которых может находиться токен предложения, для включения. Может быть относительным процентным числом (например, 0,4) или абсолютным числом для представления частот документов. Если указано значение больше 1, то дробное значение не может быть указано. По умолчанию 0,01f. Это может использоваться для исключения терминов с высокой частотой — которые, как правило, написаны правильно — из проверки орфографии. Это также улучшает производительность проверки орфографии. Для этого параметра используются частоты документов на уровне фрагмента.
`pre_filter`	Фильтр (анализатор), который применяется к каждому из токенов, переданных этому генератору кандидатов. Этот фильтр применяется к исходному токену до генерации кандидатов.
`post_filter`	Фильтр (анализатор), который применяется к каждому из сгенерированных токенов перед передачей их фактическому оценщику фраз.

Следующий пример показывает вызов предложения phrase с двумя генераторами: первый использует поле, содержащее обычные индексированные термины, а второй — поле, в котором термины индексируются с помощью фильтра reverse (токены индексируются в обратном порядке). Это используется для преодоления ограничения прямых генераторов, требующих постоянного префикса для предоставления предложений высокой производительности. Параметры pre_filter и post_filter принимают обычные имена анализаторов.

POST test/_search
{
  "suggest": {
    "text" : "obel prize",
    "simple_phrase" : {
      "phrase" : {
        "field" : "title.trigram",
        "size" : 1,
        "direct_generator" : [ {
          "field" : "title.trigram",
          "suggest_mode" : "always"
        }, {
          "field" : "title.reverse",
          "suggest_mode" : "always",
          "pre_filter" : "reverse",
          "post_filter" : "reverse"
        } ]
      }
    }
  }
}

pre_filter и post_filter также могут использоваться для вставки синонимов после генерации кандидатов. Например, для запроса captain usq мы можем сгенерировать кандидата usa для термина usq, который является синонимом america. Это позволяет нам предоставить captain america пользователю, если эта фраза достаточно хорошо набирает оценки.

Предлагатель завершения

Предлагатель completion предоставляет функциональность автозаполнения/поиска по мере ввода текста. Это навигационная функция, которая помогает пользователям находить релевантные результаты по мере ввода, повышая точность поиска. Она не предназначена для исправления орфографических ошибок или функции "возможно вы имели в виду", как предлагатели term или phrase.

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

Сопоставление

Для использования этой функции, укажите специальное сопоставление для этого поля, которое индексирует значения поля для быстрого автозаполнения.

PUT music
{
  "mappings": {
    "properties": {
      "suggest": {
        "type": "completion"
      },
      "title": {
        "type": "keyword"
      }
    }
  }
}

Сопоставление поддерживает следующие параметры:

`analyzer`	Анализатор индекса, используемый по умолчанию, — `simple`.
`search_analyzer`	Анализатор поиска, используемый по умолчанию, — значение `analyzer`.
`preserve_separators`	Сохраняет разделители, по умолчанию — `true`. Если отключено, вы можете найти поле, начинающееся с `Foo Fighters`, если вы предлагаете `foof`.
`preserve_position_increments`	Включает приращения позиций, по умолчанию — `true`. Если отключено и используется анализатор стоп-слов, вы можете получить поле, начинающееся с `The Beatles`, если вы предлагаете `b`. Примечание : Это также можно достичь, индексируя два входа, `Beatles` и `The Beatles`, без необходимости изменения простого анализатора, если вы можете обогатить свои данные.
`max_input_length`	Ограничивает длину одного входа, по умолчанию — `50` кодовых точек UTF-16. Это ограничение используется только во время индексирования для уменьшения общего количества символов на входную строку, чтобы предотвратить раздутие структуры данных большими входами. Большинство случаев не будут затронуты значением по умолчанию, так как префиксные завершения редко растут за пределы префиксов длиной более нескольких символов.

Индексирование

Вы индексируете предложения, как и любое другое поле. Предложение состоит из input и необязательного атрибута weight. input — ожидаемый текст, который должен совпадать с запросом предложения, а weight определяет, как будут ранжироваться предложения. Индексирование предложения выполняется следующим образом:

PUT music/_doc/1?refresh
{
  "suggest" : {
    "input": [ "Nevermind", "Nirvana" ],
    "weight" : 34
  }
}

Поддерживаются следующие параметры:

input

Ввод для хранения, это может быть массив строк или просто строка. Это поле обязательно.

Это значение не может содержать следующие управляющие символы UTF-16:

\u0000 (null)
\u001f (разделитель информации один)
\u001e (разделитель информации два)

weight

Положительное целое число или строка, содержащая положительное целое число, которое определяет вес и позволяет ранжировать ваши предложения. Это поле необязательно.

Вы можете индексировать несколько предложений для документа следующим образом:

PUT music/_doc/1?refresh
{
  "suggest": [
    {
      "input": "Nevermind",
      "weight": 10
    },
    {
      "input": "Nirvana",
      "weight": 3
    }
  ]
}

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

PUT music/_doc/1?refresh
{
  "suggest" : [ "Nevermind", "Nirvana" ]
}

Запросы

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

POST music/_search?pretty
{
  "suggest": {
    "song-suggest": {
      "prefix": "nir",        
      "completion": {         
          "field": "suggest"  
      }
    }
  }
}

	Префикс, используемый для поиска предложений
	Тип предложений
	Имя поля для поиска предложений

возвращает этот ответ:

{
  "_shards" : {
    "total" : 1,
    "successful" : 1,
    "skipped" : 0,
    "failed" : 0
  },
  "hits": ...
  "took": 2,
  "timed_out": false,
  "suggest": {
    "song-suggest" : [ {
      "text" : "nir",
      "offset" : 0,
      "length" : 3,
      "options" : [ {
        "text" : "Nirvana",
        "_index": "music",
        "_type": "_doc",
        "_id": "1",
        "_score": 1.0,
        "_source": {
          "suggest": ["Nevermind", "Nirvana"]
        }
      } ]
    } ]
  }
}

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

Назначенный вес предложения возвращается как _score. Поле text использует input вашего индексированного предложения. Предложения возвращают весь документ _source по умолчанию. Размер _source может влиять на производительность из-за извлечения данных с диска и сетевой передачи. Чтобы сэкономить сетевые ресурсы, отфильтруйте нежелательные поля из _source, используя фильтрацию источника, чтобы минимизировать размер _source. Обратите внимание, что конечная точка _suggest не поддерживает фильтрацию источника, но использование suggest на конечной точке _search поддерживает:

POST music/_search
{
  "_source": "suggest",     
  "suggest": {
    "song-suggest": {
      "prefix": "nir",
      "completion": {
        "field": "suggest", 
        "size": 5           
      }
    }
  }
}

	Фильтр источника для возврата только поля `suggest`
	Имя поля для поиска предложений
	Количество возвращаемых предложений

Что должно выглядеть так:

{
  "took": 6,
  "timed_out": false,
  "_shards": {
    "total": 1,
    "successful": 1,
    "skipped": 0,
    "failed": 0
  },
  "hits": {
    "total": {
      "value": 0,
      "relation": "eq"
    },
    "max_score": null,
    "hits": []
  },
  "suggest": {
    "song-suggest": [ {
        "text": "nir",
        "offset": 0,
        "length": 3,
        "options": [ {
            "text": "Nirvana",
            "_index": "music",
            "_type": "_doc",
            "_id": "1",
            "_score": 1.0,
            "_source": {
              "suggest": [ "Nevermind", "Nirvana" ]
            }
          } ]
      } ]
  }
}

Основные запросы предлагателя завершения поддерживают следующие параметры:

`field`	Имя поля, на котором нужно выполнить запрос (необходимо).
`size`	Количество предложений для возврата (по умолчанию — `5`).
`skip_duplicates`	Нужно ли отфильтровывать дублируемые предложения (по умолчанию — `false`).

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

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

Пропуск дублируемых предложений

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

POST music/_search?pretty
{
  "suggest": {
    "song-suggest": {
      "prefix": "nor",
      "completion": {
        "field": "suggest",
        "skip_duplicates": true
      }
    }
  }
}

При установке в значение true, этот параметр может замедлить поиск, так как нужно посетить больше предложений, чтобы найти верхние N.

Нечётные запросы

Предлагатель завершений также поддерживает нечётные запросы — это означает, что вы можете иметь ошибку в своём поиске и всё равно получить результаты.

POST music/_search?pretty
{
  "suggest": {
    "song-suggest": {
      "prefix": "nor",
      "completion": {
        "field": "suggest",
        "fuzzy": {
          "fuzziness": 2
        }
      }
    }
  }
}

Предложения, которые делят самый длинный префикс с запросом prefix, будут иметь более высокий рейтинг.

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

`fuzziness`	Фактор нечёткости, по умолчанию равен `AUTO`. Смотрите Нечёткость для разрешённых настроек.
`transpositions`	Если установлено значение `true`, транспозиции считаются как одна замена вместо двух, по умолчанию `true`
`min_length`	Минимальная длина входных данных перед возвращением нечётных предложений, по умолчанию `3`
`prefix_length`	Минимальная длина входных данных, которая не проверяется на нечётные альтернативы, по умолчанию `1`
`unicode_aware`	Если `true`, все измерения (например, нечёткое расстояние редактирования, транспозиции и длины) измеряются в кодовых точках Юникода вместо байтов. Это немного медленнее, чем сырые байты, поэтому по умолчанию установлено `false`.

Если вы хотите использовать значения по умолчанию, но всё равно использовать нечёткость, вы можете использовать fuzzy: {} или fuzzy: true.

Запросы с использованием регулярных выражений

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

POST music/_search?pretty
{
  "suggest": {
    "song-suggest": {
      "regex": "n[ever|i]r",
      "completion": {
        "field": "suggest"
      }
    }
  }
}

Запрос с использованием регулярных выражений может принимать специфические параметры регулярных выражений. Поддерживаются следующие параметры:

flags

Возможные флаги: ALL (по умолчанию), ANYSTRING, COMPLEMENT, EMPTY, INTERSECTION, INTERVAL или NONE. См. regexp-syntax для их значения.

max_determinized_states

Регулярные выражения опасны, потому что легко случайно создать кажущееся безобидным выражение, для выполнения которого Lucene требует экспоненциального количества внутренних состояний детерминированного автомата (и соответствующего объёма оперативной памяти и ЦП). Lucene предотвращает это, используя настройку max_determinized_states (по умолчанию 10000). Вы можете повысить этот предел, чтобы разрешить выполнение более сложных регулярных выражений.

Предлагатель контекста

Предлагатель завершений учитывает все документы в индексе, но часто желательно предоставлять предложения, отфильтрованные и/или усиленные по каким-либо критериям. Например, вы хотите предлагать названия песен, отфильтрованные по определённым исполнителям, или хотите усиливать предложения названий песен на основе их жанра.

Для достижения фильтрации и/или усиления предложений вы можете добавить соответствия контексту при настройке поля завершения. Вы можете определить несколько соответствий контексту для поля завершения. Каждое соответствие контексту имеет уникальное имя и тип. Существует два типа: category и geo. Соответствия контексту настраиваются в параметре contexts в сопоставлении полей.

Необходимо предоставить контекст при индексировании и запросе поля завершения, включенного в контекст.

Ниже определены типы, каждый с двумя соответствиями контексту для поля завершения:

PUT place
{
  "mappings": {
    "properties": {
      "suggest": {
        "type": "completion",
        "contexts": [
          {                                 
            "name": "place_type",
            "type": "category"
          },
          {                                 
            "name": "location",
            "type": "geo",
            "precision": 4
          }
        ]
      }
    }
  }
}
PUT place_path_category
{
  "mappings": {
    "properties": {
      "suggest": {
        "type": "completion",
        "contexts": [
          {                           
            "name": "place_type",
            "type": "category",
            "path": "cat"
          },
          {                           
            "name": "location",
            "type": "geo",
            "precision": 4,
            "path": "loc"
          }
        ]
      },
      "loc": {
        "type": "geo_point"
      }
    }
  }
}

	Определяет контекст `category` с именем place_type, где категории должны отправляться вместе с предложениями.
	Определяет контекст `geo` с именем location, где категории должны отправляться вместе с предложениями.
	Определяет контекст `category` с именем place_type, где категории считываются из поля `cat`.
	Определяет контекст `geo` с именем location, где категории считываются из поля `loc`.

Добавление соответствий контексту увеличивает размер индекса для поля завершения. Индекс завершения полностью находится в оперативной памяти; вы можете отслеживать размер индекса поля завершения, используя статистику индексов.

Контекст категории

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

Сопоставления настроены как поля place_type выше. Если определено path, то категории считываются из этого пути в документе, иначе они должны отправляться в поле suggest следующим образом:

PUT place/_doc/1
{
  "suggest": {
    "input": [ "timmy's", "starbucks", "dunkin donuts" ],
    "contexts": {
      "place_type": [ "cafe", "food" ]                    
    }
  }
}

Эти предложения будут связаны с категорией cafe и food.

Если в сопоставлении был указан path, то следующего запроса индекса будет достаточно для добавления категорий:

PUT place_path_category/_doc/1
{
  "suggest": ["timmy's", "starbucks", "dunkin donuts"],
  "cat": ["cafe", "food"] 
}

Эти предложения будут связаны с категорией cafe и food.

Если соответствие контексту ссылается на другое поле и категории явно индексируются, предложения индексируются с обоими наборами категорий.

Запрос категории

Предложения могут быть отфильтрованы по одной или нескольким категориям. Следующий запрос фильтрует предложения по нескольким категориям:

POST place/_search?pretty
{
  "suggest": {
    "place_suggestion": {
      "prefix": "tim",
      "completion": {
        "field": "suggest",
        "size": 10,
        "contexts": {
          "place_type": [ "cafe", "restaurants" ]
        }
      }
    }
  }
}

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

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

POST place/_search?pretty
{
  "suggest": {
    "place_suggestion": {
      "prefix": "tim",
      "completion": {
        "field": "suggest",
        "size": 10,
        "contexts": {
          "place_type": [                             
            { "context": "cafe" },
            { "context": "restaurants", "boost": 2 }
          ]
        }
      }
    }
  }
}

Запрос контекста фильтрует предложения, связанные с категориями cafe и restaurants и повышает предложения, связанные с restaurants, на множитель 2

Помимо принятия значений категорий, запрос контекста может состоять из нескольких пунктов контекста категории. Для пункта контекста category поддерживаются следующие параметры:

`context`	Значение категории для фильтрации/усиления. Это обязательно.
`boost`	Множитель, на который должна быть повышена оценка предложения. Оценка вычисляется путём умножения множителя на вес предложения, по умолчанию `1`
`prefix`	Должно ли значение категории обрабатываться как префикс. Например, если установлено `true`, вы можете отфильтровать категории type1, type2 и так далее, указав префикс категории type. По умолчанию `false`

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

Контекст геолокации

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

Внутренне геоточки кодируются как геохеши с указанной точностью.

Геосопоставление

Помимо настройки path, соответствие контексту geo принимает следующие настройки:

precision

Это определяет точность геохеша, который необходимо индексировать, и может быть указан как значение расстояния (5m, 10km и т.д.), или как точность геохеша в сыром виде (1..12). По умолчанию используется значение точности геохеша в сыром виде 6.

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

Индексирование геоконтекстов

Контексты geo могут быть явно заданы с предложениями или индексированы из поля геоточки в документе через параметр path, аналогично контекстам category. Связывание нескольких контекстов геолокации с предложением будет индексировать предложение для каждой геолокации. Следующее индексирует предложение с двумя геоконтекстами:

PUT place/_doc/1
{
  "suggest": {
    "input": "timmy's",
    "contexts": {
      "location": [
        {
          "lat": 43.6624803,
          "lon": -79.3863353
        },
        {
          "lat": 43.6624718,
          "lon": -79.3873227
        }
      ]
    }
  }
}

Запрос геолокации

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

POST place/_search
{
  "suggest": {
    "place_suggestion": {
      "prefix": "tim",
      "completion": {
        "field": "suggest",
        "size": 10,
        "contexts": {
          "location": {
            "lat": 43.662,
            "lon": -79.380
          }
        }
      }
    }
  }
}

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

Предложения, которые находятся в области, представленной геохешем, также могут быть повышены выше других, как показано ниже:

POST place/_search?pretty
{
  "suggest": {
    "place_suggestion": {
      "prefix": "tim",
      "completion": {
        "field": "suggest",
        "size": 10,
        "contexts": {
          "location": [             
                      {
              "lat": 43.6624803,
              "lon": -79.3863353,
              "precision": 2
            },
            {
              "context": {
                "lat": 43.6624803,
                "lon": -79.3863353
              },
              "boost": 2
            }
          ]
        }
      }
    }
  }
}

Запрос контекста фильтрует предложения, которые попадают в геолокацию, представленную геохешем (43.662, -79.380) с точностью 2, и усиливает предложения, которые попадают в геохеш представления (43.6624803, -79.3863353) с точностью по умолчанию 6 на множитель 2.

Помимо принятия значений контекста, запрос контекста может состоять из нескольких пунктов контекста. Для пункта контекста geo поддерживаются следующие параметры:

`context`	Объект гео-точки или строка гео-хеша для фильтрации или повышения оценки предложения. Обязательное поле.
`boost`	Коэффициент, на который нужно повысить оценку предложения. Оценка вычисляется путем умножения коэффициента на вес предложения, по умолчанию `1`
`precision`	Точность геохеша для кодирования гео-точки запроса. Может быть указана как значение расстояния (`5m`, `10km` и т.д.), или как точность геохеша в сыром виде (`1`..`12`). По умолчанию используется точность, установленная во время индексации.
`neighbours`	Принимает массив значений точности, на которых следует учитывать соседние геохеши. Значение точности может быть значением расстояния (`5m`, `10km` и т.д.) или точностью геохеша в сыром виде (`1`..`12`). По умолчанию генерируются соседи для уровня точности, установленного во время индексации.

Возвращение типа суггестера

Иногда вам необходимо знать точный тип суггестера, чтобы обработать его результаты. Параметр typed_keys может быть использован для изменения имени суггестера в ответе, чтобы оно предварялось его типом.

Рассмотрим пример с двумя суггестерами term и phrase:

POST _search?typed_keys
{
  "suggest": {
    "text" : "some test mssage",
    "my-first-suggester" : {
      "term" : {
        "field" : "message"
      }
    },
    "my-second-suggester" : {
      "phrase" : {
        "field" : "message"
      }
    }
  }
}

В ответе имена суггестеров будут изменены соответственно на term#my-first-suggester и phrase#my-second-suggester, отражая типы каждого предложения:

{
  "suggest": {
    "term#my-first-suggester": [ 
      {
        "text": "some",
        "offset": 0,
        "length": 4,
        "options": []
      },
      {
        "text": "test",
        "offset": 5,
        "length": 4,
        "options": []
      },
      {
        "text": "mssage",
        "offset": 10,
        "length": 6,
        "options": [
          {
            "text": "message",
            "score": 0.8333333,
            "freq": 4
          }
        ]
      }
    ],
    "phrase#my-second-suggester": [ 
      {
        "text": "some test mssage",
        "offset": 0,
        "length": 16,
        "options": [
          {
            "text": "some test message",
            "score": 0.030227963
          }
        ]
      }
    ]
  },
  ...
}

	Имя `my-first-suggester` теперь содержит префикс `term`.
	Имя `my-second-suggester` теперь содержит префикс `phrase`.

© 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/7.17/search-suggesters.html