› ›

API поиска в графе

API поиска в графе позволяет извлечь и обобщить информацию о документах и терминах в вашем индексе Elasticsearch.

Самый простой способ понять работу этого API — использовать графический интерфейс Kibana для исследования связей. Вы можете просмотреть последний запрос, отправленный на конечную точку _explore, в панели Последний запрос. Дополнительную информацию см. в Руководстве по началу работы с графами.

Дополнительную информацию о работе с API поиска см. в разделах по отладке поиска в графе и ограничениях.

API поиска в графе включен по умолчанию. Чтобы отключить доступ к API поиска в графе и графическому интерфейсу Kibana Graph UI, добавьте xpack.graph.enabled: false в elasticsearch.yml.

Запрос

POST <index>/_graph/explore

Описание

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

Тело запроса

query

Запрос-семя, который определяет интересующие документы. Может быть любым корректным запросом Elasticsearch. Например:

"query": {
  "bool": {
    "must": {
      "match": {
        "query.raw": "midi"
      }
    },
    "filter": [
      {
        "range": {
          "query_time": {
            "gte": "2015-10-01 00:00:00"
          }
        }
      }
    ]
  }
}

vertices

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

"vertices": [
  {
    "field": "product"
    }
]

Свойства для vertices

field: Идентифицирует поле в интересующих документах.
include: Идентифицирует интересующие термины, являющиеся начальными точками для распространения поиска. Вы не обязаны указывать запрос-семя, если вы указываете условие включения. Условие включения неявно выполняет запрос на документы, содержащие любой из перечисленных терминов. Кроме указания простого массива строк, вы также можете передать объекты со значениями term и boost для повышения совпадений по определённым терминам.
exclude: Условие exclude предотвращает включение указанных терминов в результаты.
size: Указывает максимальное количество терминов вершин, возвращаемых для каждого поля. По умолчанию 5.
min_doc_count: Указывает, сколько документов должно содержать пару терминов, прежде чем она будет считаться полезной связью. Эта настройка действует как порог достоверности. По умолчанию 3.
shard_min_doc_count: Эта расширенная настройка контролирует, сколько документов на конкретном фрагменте должно содержать пару терминов, прежде чем соединение будет возвращено для глобального рассмотрения. По умолчанию 2.

connections

Указывает одно или несколько полей, из которых вы хотите извлечь термины, связанные с указанными вершинами. Например:

"connections": {  
  "vertices": [
    {
      "field": "query.raw"
    }
  ]
}

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

Свойства для connections

query

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

vertices

Содержит поля, которые вас интересуют. Например:

"vertices": [
  {
    "field": "query.raw",
    "size": 5,
    "min_doc_count": 10,
    "shard_min_doc_count": 3
  }
]

controls

Направляет API графа, как строить граф.

Свойства для controls

use_significance

Флаг use_significance фильтрует связанные термины, так что включаются только те, которые существенно связаны с вашим запросом. Подробности об алгоритме вычисления значимости см. в significant_terms агрегации. По умолчанию true.

sample_size

Каждый шаг рассматривает выборку наиболее соответствующих документов на каждом фрагменте. Использование выборок увеличивает скорость выполнения и сохраняет исследование, сосредоточенное на осмысленно связанных терминах. Очень маленькие значения (меньше 50) могут не обеспечить достаточной доказательной базы для выявления значимых связей между терминами. Очень большие размеры выборок могут разбавить качество результатов и увеличить время выполнения. По умолчанию 100 документов.

timeout

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

sample_diversity

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

"sample_diversity": {
  "field": "category.raw",
  "max_docs_per_value": 500
}

Примеры

Основной поиск в графе

Начальный поиск обычно начинается с запроса для идентификации тесно связанных терминов.

POST clicklogs/_graph/explore
{
  "query": {                  
    "match": {
      "query.raw": "midi"
    }
  },
  "vertices": [               
    {
      "field": "product"
    }
  ],
  "connections": {            
    "vertices": [
      {
        "field": "query.raw"
      }
    ]
  }
}

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

Ответ от API поиска в графе выглядит следующим образом:

{
   "took": 0,
   "timed_out": false,
   "failures": [],
   "vertices": [ 
      {
         "field": "query.raw",
         "term": "midi cable",
         "weight": 0.08745858139552132,
         "depth": 1
      },
      {
         "field": "product",
         "term": "8567446",
         "weight": 0.13247784285434397,
         "depth": 0
      },
      {
         "field": "product",
         "term": "1112375",
         "weight": 0.018600718471158982,
         "depth": 0
      },
      {
         "field": "query.raw",
         "term": "midi keyboard",
         "weight": 0.04802242866755111,
         "depth": 1
      }
   ],
   "connections": [ 
      {
         "source": 0,
         "target": 1,
         "weight": 0.04802242866755111,
         "doc_count": 13
      },
      {
         "source": 2,
         "target": 3,
         "weight": 0.08120623870976627,
         "doc_count": 23
      }
   ]
}

Массив всех обнаруженных вершин. Вершина — это индексированный термин, поэтому предоставляются поле и значение термина. Атрибут weight указывает значение значимости. Атрибут depth указывает уровень шага, на котором термин был впервые обнаружен.

Связи между вершинами в массиве. Свойства source и target индексируются в массиве вершин и указывают, какой термин вершины привёл к другому в ходе поиска. Значение doc_count указывает, сколько документов в наборе выборки содержат эту пару терминов (это не глобальное количество для всех документов в индексе).

Дополнительные параметры

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

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

POST clicklogs/_graph/explore
{
  "query": {
    "match": {
      "query.raw": "midi"
    }
  },
  "controls": {
    "use_significance": false,        
    "sample_size": 2000,              
    "timeout": 2000,                  
    "sample_diversity": {             
      "field": "category.raw",
      "max_docs_per_value": 500
    }
  },
  "vertices": [
    {
      "field": "product",
      "size": 5,                      
      "min_doc_count": 10,            
      "shard_min_doc_count": 3        
    }
  ],
  "connections": {
    "query": {                        
      "bool": {
        "filter": [
          {
            "range": {
              "query_time": {
                "gte": "2015-10-01 00:00:00"
              }
            }
          }
        ]
      }
    },
    "vertices": [
      {
        "field": "query.raw",
        "size": 5,
        "min_doc_count": 10,
        "shard_min_doc_count": 3
      }
    ]
  }
}

	Отключите `use_significance`, чтобы включить все связанные термины, а не только те, которые существенно связаны с запросом.
	Увеличьте размер выборки, чтобы рассмотреть больший набор документов на каждом фрагменте.
	Ограничьте время выполнения запроса графа перед возвратом результатов.
	Обеспечьте разнообразие в выборке, установив ограничение на количество документов на значение в определённом поле с единственным значением, например, поле категории.
	Управляйте максимальным количеством вершинных терминов, возвращаемых для каждого поля.
	Установите порог достоверности, который определяет, сколько документов должны содержать пару терминов, прежде чем мы рассмотрим её как полезную связь.
	Укажите, сколько документов на фрагменте должны содержать пару терминов, прежде чем соединение будет возвращено для глобального рассмотрения.
	Ограничьте, какие документы рассматриваются при исследовании связанных терминов.

Операции по построению паутины

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

Для построения паутины вам необходимо указать две вещи:

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

Вы указываете эту информацию, используя include`and `exclude-строки. Например, следующий запрос начинается с продукта 1854873 и строит паутину, чтобы найти дополнительные поисковые термины, связанные с этим продуктом. Термины "midi", "midi keyboard" и "synth" исключаются из результатов.

POST clicklogs/_graph/explore
{
   "vertices": [
      {
         "field": "product",
         "include": [ "1854873" ] 
      }
   ],
   "connections": {
      "vertices": [
         {
            "field": "query.raw",
            "exclude": [ 
               "midi keyboard",
               "midi",
               "synth"
            ]
         }
      ]
   }
}

	Вершины, с которых вы хотите начать, указываются как массив терминов в `include`-строке.
	`exclude`-строка предотвращает включение в результаты терминов, о которых вы уже знаете.

© 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/graph-explore-api.html