Spec-Zone.ru › Elasticsearch 8
›Руководство по Elasticsearch [8.17] ›REST API ›API документов

API получения терм-векторов

Новая справка по API

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

Получает информацию и статистику по терминам в полях конкретного документа.

resp = client.termvectors(
    index="my-index-000001",
    id="1",
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  id: 1
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  id: 1,
});
console.log(response);
GET /my-index-000001/_termvectors/1

Запрос

GET /<index>/_termvectors/<_id>

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

  • Если включены функции безопасности Elasticsearch, у вас должна быть read привилегия index для целевого индекса или алиаса индекса.

Описание

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

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

resp = client.termvectors(
    index="my-index-000001",
    id="1",
    fields="message",
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  id: 1,
  fields: 'message'
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  id: 1,
  fields: "message",
});
console.log(response);
GET /my-index-000001/_termvectors/1?fields=message

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

Терм-векторы по умолчанию являются режим реального времени, а не близким к реальному времени. Это можно изменить, установив параметр realtime на значение false.

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

Информация о терминах

  • частота термина в поле (всегда возвращается)
  • позиции термина (positions : true)
  • начальные и конечные смещения (offsets : true)
  • данные термина (payloads : true), в кодировке base64

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

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

Статистика по терминам

Установив параметр term_statistics на значение true (по умолчанию false), будет возвращено:

  • общая частота термина (как часто встречается термин во всех документах)
  • частота документа (количество документов, содержащих текущий термин)

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

Статистика по полям

Установив параметр field_statistics на значение false (по умолчанию true), будет исключено:

  • количество документов (сколько документов содержат это поле)
  • сумма частот документов (сумма частот документов для всех терминов в этом поле)
  • сумма общих частот терминов (сумма общих частот каждого термина в этом поле)

Фильтрация терминов

С помощью параметра filter возвращаемые термины также могут быть отфильтрованы на основе их значений tf-idf. Это может быть полезно для определения хорошего характерного вектора документа. Данная функция работает аналогично второй фазе запроса More Like This. См. пример 5 для использования.

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

max_num_terms

Максимальное количество возвращаемых терминов на поле. По умолчанию 25.

min_term_freq

Игнорировать слова с частотой меньше, чем указано, в исходном документе. По умолчанию 1.

max_term_freq

Игнорировать слова с частотой больше, чем указано, в исходном документе. По умолчанию безгранично.

min_doc_freq

Игнорировать термины, которые не встречаются как минимум в указанном количестве документов. По умолчанию 1.

max_doc_freq

Игнорировать слова, которые встречаются более чем в указанном количестве документов. По умолчанию безгранично.

min_word_length

Минимальная длина слова, ниже которой слова будут игнорироваться. По умолчанию 0.

max_word_length

Максимальная длина слова, выше которой слова будут игнорироваться. По умолчанию безгранично (0).

Поведение

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

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

<index>
(Обязательно, строка) Название индекса, содержащего документ.
<_id>
(Необязательно, строка) Уникальный идентификатор документа.

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

fields

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

Используется в качестве списка по умолчанию, если в параметрах completion_fields или fielddata_fields не указан конкретный список полей.

field_statistics
(Необязательно, логическое значение) Если true, ответ включает количество документов, сумму частот документов и сумму общих частот терминов. По умолчанию true.
<offsets>
(Необязательно, логическое значение) Если true, ответ включает смещения терминов. По умолчанию true.
payloads
(Необязательно, логическое значение) Если true, ответ включает данные терминов. По умолчанию true.
positions
(Необязательно, логическое значение) Если true, ответ включает позиции терминов. По умолчанию true.
preference
(Необязательно, строка) Указывает узел или фрагмент, на котором должно выполняться действие. По умолчанию случайный.
routing
(Необязательно, строка) Пользовательское значение, используемое для маршрутизации операций к определенному фрагменту.
realtime
(Необязательно, логическое значение) Если true, запрос выполняется в режиме реального времени, а не в режиме близком к реальному времени. По умолчанию true. См. Режим реального времени.
term_statistics
(Необязательно, логическое значение) Если true, ответ включает частоту термина и частоту документа. По умолчанию false.
version
(Необязательно, логическое значение) Если true, возвращает версию документа в составе результата.
version_type
(Необязательно, перечисление) Конкретный тип версии: external, external_gte.

Примеры

Возвращение хранимых векторных представлений терминов

Сначала создаем индекс, хранящий векторные представления терминов, платные данные и т. д.:

resp = client.indices.create(
    index="my-index-000001",
    mappings={
        "properties": {
            "text": {
                "type": "text",
                "term_vector": "with_positions_offsets_payloads",
                "store": True,
                "analyzer": "fulltext_analyzer"
            },
            "fullname": {
                "type": "text",
                "term_vector": "with_positions_offsets_payloads",
                "analyzer": "fulltext_analyzer"
            }
        }
    },
    settings={
        "index": {
            "number_of_shards": 1,
            "number_of_replicas": 0
        },
        "analysis": {
            "analyzer": {
                "fulltext_analyzer": {
                    "type": "custom",
                    "tokenizer": "whitespace",
                    "filter": [
                        "lowercase",
                        "type_as_payload"
                    ]
                }
            }
        }
    },
)
print(resp)
response = client.indices.create(
  index: 'my-index-000001',
  body: {
    mappings: {
      properties: {
        text: {
          type: 'text',
          term_vector: 'with_positions_offsets_payloads',
          store: true,
          analyzer: 'fulltext_analyzer'
        },
        fullname: {
          type: 'text',
          term_vector: 'with_positions_offsets_payloads',
          analyzer: 'fulltext_analyzer'
        }
      }
    },
    settings: {
      index: {
        number_of_shards: 1,
        number_of_replicas: 0
      },
      analysis: {
        analyzer: {
          fulltext_analyzer: {
            type: 'custom',
            tokenizer: 'whitespace',
            filter: [
              'lowercase',
              'type_as_payload'
            ]
          }
        }
      }
    }
  }
)
puts response
const response = await client.indices.create({
  index: "my-index-000001",
  mappings: {
    properties: {
      text: {
        type: "text",
        term_vector: "with_positions_offsets_payloads",
        store: true,
        analyzer: "fulltext_analyzer",
      },
      fullname: {
        type: "text",
        term_vector: "with_positions_offsets_payloads",
        analyzer: "fulltext_analyzer",
      },
    },
  },
  settings: {
    index: {
      number_of_shards: 1,
      number_of_replicas: 0,
    },
    analysis: {
      analyzer: {
        fulltext_analyzer: {
          type: "custom",
          tokenizer: "whitespace",
          filter: ["lowercase", "type_as_payload"],
        },
      },
    },
  },
});
console.log(response);
PUT /my-index-000001
{ "mappings": {
    "properties": {
      "text": {
        "type": "text",
        "term_vector": "with_positions_offsets_payloads",
        "store" : true,
        "analyzer" : "fulltext_analyzer"
       },
       "fullname": {
        "type": "text",
        "term_vector": "with_positions_offsets_payloads",
        "analyzer" : "fulltext_analyzer"
      }
    }
  },
  "settings" : {
    "index" : {
      "number_of_shards" : 1,
      "number_of_replicas" : 0
    },
    "analysis": {
      "analyzer": {
        "fulltext_analyzer": {
          "type": "custom",
          "tokenizer": "whitespace",
          "filter": [
            "lowercase",
            "type_as_payload"
          ]
        }
      }
    }
  }
}

Затем добавляем некоторые документы:

resp = client.index(
    index="my-index-000001",
    id="1",
    document={
        "fullname": "John Doe",
        "text": "test test test "
    },
)
print(resp)

resp1 = client.index(
    index="my-index-000001",
    id="2",
    refresh="wait_for",
    document={
        "fullname": "Jane Doe",
        "text": "Another test ..."
    },
)
print(resp1)
response = client.index(
  index: 'my-index-000001',
  id: 1,
  body: {
    fullname: 'John Doe',
    text: 'test test test '
  }
)
puts response

response = client.index(
  index: 'my-index-000001',
  id: 2,
  refresh: 'wait_for',
  body: {
    fullname: 'Jane Doe',
    text: 'Another test ...'
  }
)
puts response
const response = await client.index({
  index: "my-index-000001",
  id: 1,
  document: {
    fullname: "John Doe",
    text: "test test test ",
  },
});
console.log(response);

const response1 = await client.index({
  index: "my-index-000001",
  id: 2,
  refresh: "wait_for",
  document: {
    fullname: "Jane Doe",
    text: "Another test ...",
  },
});
console.log(response1);
PUT /my-index-000001/_doc/1
{
  "fullname" : "John Doe",
  "text" : "test test test "
}

PUT /my-index-000001/_doc/2?refresh=wait_for
{
  "fullname" : "Jane Doe",
  "text" : "Another test ..."
}

Следующий запрос возвращает всю информацию и статистику для поля text в документе 1 (John Doe):

resp = client.termvectors(
    index="my-index-000001",
    id="1",
    fields=[
        "text"
    ],
    offsets=True,
    payloads=True,
    positions=True,
    term_statistics=True,
    field_statistics=True,
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  id: 1,
  body: {
    fields: [
      'text'
    ],
    offsets: true,
    payloads: true,
    positions: true,
    term_statistics: true,
    field_statistics: true
  }
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  id: 1,
  fields: ["text"],
  offsets: true,
  payloads: true,
  positions: true,
  term_statistics: true,
  field_statistics: true,
});
console.log(response);
GET /my-index-000001/_termvectors/1
{
  "fields" : ["text"],
  "offsets" : true,
  "payloads" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}

Ответ:

{
  "_index": "my-index-000001",
  "_id": "1",
  "_version": 1,
  "found": true,
  "took": 6,
  "term_vectors": {
    "text": {
      "field_statistics": {
        "sum_doc_freq": 4,
        "doc_count": 2,
        "sum_ttf": 6
      },
      "terms": {
        "test": {
          "doc_freq": 2,
          "ttf": 4,
          "term_freq": 3,
          "tokens": [
            {
              "position": 0,
              "start_offset": 0,
              "end_offset": 4,
              "payload": "d29yZA=="
            },
            {
              "position": 1,
              "start_offset": 5,
              "end_offset": 9,
              "payload": "d29yZA=="
            },
            {
              "position": 2,
              "start_offset": 10,
              "end_offset": 14,
              "payload": "d29yZA=="
            }
          ]
        }
      }
    }
  }
}

Генерация векторных представлений терминов на лету

Векторные представления терминов, которые не явно хранятся в индексе, автоматически вычисляются на лету. Следующий запрос возвращает всю информацию и статистику для полей в документе 1, даже если термины не были явно сохранены в индексе. Обратите внимание, что для поля text термины не перегенерируются.

resp = client.termvectors(
    index="my-index-000001",
    id="1",
    fields=[
        "text",
        "some_field_without_term_vectors"
    ],
    offsets=True,
    positions=True,
    term_statistics=True,
    field_statistics=True,
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  id: 1,
  body: {
    fields: [
      'text',
      'some_field_without_term_vectors'
    ],
    offsets: true,
    positions: true,
    term_statistics: true,
    field_statistics: true
  }
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  id: 1,
  fields: ["text", "some_field_without_term_vectors"],
  offsets: true,
  positions: true,
  term_statistics: true,
  field_statistics: true,
});
console.log(response);
GET /my-index-000001/_termvectors/1
{
  "fields" : ["text", "some_field_without_term_vectors"],
  "offsets" : true,
  "positions" : true,
  "term_statistics" : true,
  "field_statistics" : true
}

Искусственные документы

Векторные представления терминов также могут быть сгенерированы для искусственных документов, то есть для документов, отсутствующих в индексе. Например, следующий запрос вернёт такие же результаты, как и в примере 1. Используемая схема сопоставления определяется параметром index.

Если динамическое сопоставление включено (по умолчанию), поля документа, отсутствующие в исходной схеме, будут динамически созданы.

resp = client.termvectors(
    index="my-index-000001",
    doc={
        "fullname": "John Doe",
        "text": "test test test"
    },
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  body: {
    doc: {
      fullname: 'John Doe',
      text: 'test test test'
    }
  }
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  doc: {
    fullname: "John Doe",
    text: "test test test",
  },
});
console.log(response);
GET /my-index-000001/_termvectors
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  }
}
Анализатор на уровне поля

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

resp = client.termvectors(
    index="my-index-000001",
    doc={
        "fullname": "John Doe",
        "text": "test test test"
    },
    fields=[
        "fullname"
    ],
    per_field_analyzer={
        "fullname": "keyword"
    },
)
print(resp)
response = client.termvectors(
  index: 'my-index-000001',
  body: {
    doc: {
      fullname: 'John Doe',
      text: 'test test test'
    },
    fields: [
      'fullname'
    ],
    per_field_analyzer: {
      fullname: 'keyword'
    }
  }
)
puts response
const response = await client.termvectors({
  index: "my-index-000001",
  doc: {
    fullname: "John Doe",
    text: "test test test",
  },
  fields: ["fullname"],
  per_field_analyzer: {
    fullname: "keyword",
  },
});
console.log(response);
GET /my-index-000001/_termvectors
{
  "doc" : {
    "fullname" : "John Doe",
    "text" : "test test test"
  },
  "fields": ["fullname"],
  "per_field_analyzer" : {
    "fullname": "keyword"
  }
}

Ответ:

{
  "_index": "my-index-000001",
  "_version": 0,
  "found": true,
  "took": 6,
  "term_vectors": {
    "fullname": {
       "field_statistics": {
          "sum_doc_freq": 2,
          "doc_count": 4,
          "sum_ttf": 4
       },
       "terms": {
          "John Doe": {
             "term_freq": 1,
             "tokens": [
                {
                   "position": 0,
                   "start_offset": 0,
                   "end_offset": 8
                }
             ]
          }
       }
    }
  }
}

Фильтрация терминов

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

resp = client.termvectors(
    index="imdb",
    doc={
        "plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
    },
    term_statistics=True,
    field_statistics=True,
    positions=False,
    offsets=False,
    filter={
        "max_num_terms": 3,
        "min_term_freq": 1,
        "min_doc_freq": 1
    },
)
print(resp)
response = client.termvectors(
  index: 'imdb',
  body: {
    doc: {
      plot: 'When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil.'
    },
    term_statistics: true,
    field_statistics: true,
    positions: false,
    offsets: false,
    filter: {
      max_num_terms: 3,
      min_term_freq: 1,
      min_doc_freq: 1
    }
  }
)
puts response
const response = await client.termvectors({
  index: "imdb",
  doc: {
    plot: "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil.",
  },
  term_statistics: true,
  field_statistics: true,
  positions: false,
  offsets: false,
  filter: {
    max_num_terms: 3,
    min_term_freq: 1,
    min_doc_freq: 1,
  },
});
console.log(response);
GET /imdb/_termvectors
{
  "doc": {
    "plot": "When wealthy industrialist Tony Stark is forced to build an armored suit after a life-threatening incident, he ultimately decides to use its technology to fight against evil."
  },
  "term_statistics": true,
  "field_statistics": true,
  "positions": false,
  "offsets": false,
  "filter": {
    "max_num_terms": 3,
    "min_term_freq": 1,
    "min_doc_freq": 1
  }
}

Ответ:

{
   "_index": "imdb",
   "_version": 0,
   "found": true,
   "term_vectors": {
      "plot": {
         "field_statistics": {
            "sum_doc_freq": 3384269,
            "doc_count": 176214,
            "sum_ttf": 3753460
         },
         "terms": {
            "armored": {
               "doc_freq": 27,
               "ttf": 27,
               "term_freq": 1,
               "score": 9.74725
            },
            "industrialist": {
               "doc_freq": 88,
               "ttf": 88,
               "term_freq": 1,
               "score": 8.590818
            },
            "stark": {
               "doc_freq": 44,
               "ttf": 47,
               "term_freq": 1,
               "score": 9.272792
            }
         }
      }
   }
}

© 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/docs-termvectors.html

END_OF_DOCUMENT_MARKER

Spec-Zone.ru

Настройки Оффлайн Что нового Помощь О нас
Spec-Zone .ru
спецификации, руководства, описания, API