Term vectors API

特定のドキュメントのフィールド内の用語に関する情報と統計を取得します。

Python

  1. resp = client.termvectors(
  2.    index="my-index-000001",
  3.    id="1",
  4. )
  5. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   id: 1
  4. )
  5. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   id: 1,
  4. });
  5. console.log(response);

Console

  1. GET /my-index-000001/_termvectors/1

Request

GET /<index>/_termvectors/<_id>

Prerequisites

  • Elasticsearchのセキュリティ機能が有効になっている場合、ターゲットインデックスまたはインデックスエイリアスに対してread インデックス権限を持っている必要があります。

Description

インデックスに保存されているドキュメントや、リクエストのボディに渡された人工ドキュメントの用語ベクトルを取得できます。 

  3. #### Python
  5. ``````python
  6. resp = client.termvectors(
  7.    index="my-index-000001",
  8.    id="1",
  9.    fields="message",
  10. )
  11. print(resp)
  12. `

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   id: 1,
  4.   fields: 'message'
  5. )
  6. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   id: 1,
  4.   fields: "message",
  5. });
  6. console.log(response);

Console

  1. GET /my-index-000001/_termvectors/1?fields=message

フィールドは、マルチマッチクエリのようにワイルドカードを使用して指定できます。

用語ベクトルはデフォルトでリアルタイムであり、ほぼリアルタイムではありません。これは、realtimeパラメータをfalseに設定することで変更できます。

用語情報、用語統計、およびフィールド統計の3種類の値をリクエストできます。デフォルトでは、すべてのフィールドに対してすべての用語情報とフィールド統計が返されますが、用語統計は除外されます。

Term information

  • フィールド内の用語頻度（常に返される）
  • 用語の位置（positions : true）
  • 開始および終了オフセット（offsets : true）
  • 用語ペイロード（payloads : true）、base64エンコードされたバイト

要求された情報がインデックスに保存されていない場合、可能であればその場で計算されます。さらに、インデックスに存在しないドキュメントに対しても用語ベクトルを計算できますが、これはユーザーによって提供されます。

開始および終了オフセットはUTF-16エンコーディングが使用されていると仮定します。このトークンを生成した元のテキストを取得するためにこれらのオフセットを使用したい場合、サブストリングを取得する文字列もUTF-16でエンコードされていることを確認する必要があります。

Term statistics

  2. -  総用語頻度（用語がすべてのドキュメントに出現する回数）  
  3. -  ドキュメント頻度（現在の用語を含むドキュメントの数）
  5. デフォルトでは、これらの値は返されません。用語統計はパフォーマンスに深刻な影響を与える可能性があるためです。
  8. ### Field statistics
  10. `````field_statistics`````を`````false`````に設定すると（デフォルトは`````true`````）、次の項目が省略されます：  
  12. -  ドキュメント数（このフィールドを含むドキュメントの数）  
  13. -  ドキュメント頻度の合計（このフィールド内のすべての用語のドキュメント頻度の合計）  
  14. -  総用語頻度の合計（このフィールド内の各用語の総用語頻度の合計）
  17. ### Terms filtering
  19. `````filter`````パラメータを使用すると、返される用語はtf-idfスコアに基づいてフィルタリングされる可能性があります。これは、ドキュメントの良好な特徴ベクトルを見つけるのに役立ちます。この機能は、[More Like This Query](/read/elasticsearch-8-15/8cd48cd8651d82ff.md)の[第2フェーズ](8cd48cd8651d82ff.md#mlt-query-term-selection)と同様の方法で機能します。使用法については[例5](5cf2fae1b45c0ba1.md#docs-termvectors-terms-filtering)を参照してください。  
  21. 次のサブパラメータがサポートされています：  
  24. |     |     |
  25. | --- | --- |
  26. | `````max_num_terms````` | フィールドごとに返される必要がある最大用語数。デフォルトは`````25`````です。 |
  27. | `````min_term_freq````` | ソースドキュメント内でこの頻度未満の単語を無視します。デフォルトは`````1`````です。 |
  28. | `````max_term_freq````` | ソースドキュメント内でこの頻度を超える単語を無視します。デフォルトは無制限です。 |
  29. | `````min_doc_freq````` | この数のドキュメントに出現しない用語を無視します。デフォルトは`````1`````です。 |
  30. | `````max_doc_freq````` | この数のドキュメントに出現する単語を無視します。デフォルトは無制限です。 |
  31. | `````min_word_length````` | 無視される単語の最小文字数。デフォルトは`````0`````です。 |
  32. | `````max_word_length````` | 無視される単語の最大文字数。デフォルトは無制限（`````0`````）です。 |
  36. ## Behaviour
  38. 用語およびフィールド統計は正確ではありません。削除されたドキュメントは考慮されません。情報は、要求されたドキュメントが存在するシャードのみに取得されます。したがって、用語およびフィールド統計は相対的な尺度としてのみ有用であり、絶対的な数値はこの文脈では意味を持ちません。デフォルトでは、人工ドキュメントの用語ベクトルを要求する際、統計を取得するためのシャードがランダムに選択されます。特定のシャードを指定するには`````routing`````を使用してください。
  41. ## Path parameters
  43. -   `````<index>
  • （必須、文字列）ドキュメントを含むインデックスの名前。
  • <_id>
  • （オプション、文字列）ドキュメントの一意の識別子。

Query parameters

  • 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。

Examples

Returning stored term vectors

まず、用語ベクトル、ペイロードなどを保存するインデックスを作成します：

Python

  1. resp = client.indices.create(
  2.    index="my-index-000001",
  3.    mappings={
  4.    "properties": {
  5.    "text": {
  6.    "type": "text",
  7.    "term_vector": "with_positions_offsets_payloads",
  8.    "store": True,
  9.    "analyzer": "fulltext_analyzer"
  10.    },
  11.    "fullname": {
  12.    "type": "text",
  13.    "term_vector": "with_positions_offsets_payloads",
  14.    "analyzer": "fulltext_analyzer"
  15.    }
  16.    }
  17.    },
  18.    settings={
  19.    "index": {
  20.    "number_of_shards": 1,
  21.    "number_of_replicas": 0
  22.    },
  23.    "analysis": {
  24.    "analyzer": {
  25.    "fulltext_analyzer": {
  26.    "type": "custom",
  27.    "tokenizer": "whitespace",
  28.    "filter": [
  29.    "lowercase",
  30.    "type_as_payload"
  31.    ]
  32.    }
  33.    }
  34.    }
  35.    },
  36. )
  37. print(resp)

Ruby

  1. response = client.indices.create(
  2.   index: 'my-index-000001',
  3.   body: {
  4.    mappings: {
  5.    properties: {
  6.    text: {
  7.    type: 'text',
  8.    term_vector: 'with_positions_offsets_payloads',
  9.    store: true,
  10.    analyzer: 'fulltext_analyzer'
  11.    },
  12.    fullname: {
  13.    type: 'text',
  14.    term_vector: 'with_positions_offsets_payloads',
  15.    analyzer: 'fulltext_analyzer'
  16.    }
  17.    }
  18.    },
  19.    settings: {
  20.    index: {
  21.    number_of_shards: 1,
  22.    number_of_replicas: 0
  23.    },
  24.    analysis: {
  25.    analyzer: {
  26.    fulltext_analyzer: {
  27.    type: 'custom',
  28.    tokenizer: 'whitespace',
  29.    filter: [
  30.    'lowercase',
  31.    'type_as_payload'
  32.    ]
  33.    }
  34.    }
  35.    }
  36.    }
  37.   }
  38. )
  39. puts response

Js

  1. const response = await client.indices.create({
  2.   index: "my-index-000001",
  3.   mappings: {
  4.    properties: {
  5.    text: {
  6.    type: "text",
  7.    term_vector: "with_positions_offsets_payloads",
  8.    store: true,
  9.    analyzer: "fulltext_analyzer",
  10.    },
  11.    fullname: {
  12.    type: "text",
  13.    term_vector: "with_positions_offsets_payloads",
  14.    analyzer: "fulltext_analyzer",
  15.    },
  16.    },
  17.   },
  18.   settings: {
  19.    index: {
  20.    number_of_shards: 1,
  21.    number_of_replicas: 0,
  22.    },
  23.    analysis: {
  24.    analyzer: {
  25.    fulltext_analyzer: {
  26.    type: "custom",
  27.    tokenizer: "whitespace",
  28.    filter: ["lowercase", "type_as_payload"],
  29.    },
  30.    },
  31.    },
  32.   },
  33. });
  34. console.log(response);

Console

  1. PUT /my-index-000001
  2. { "mappings": {
  3.    "properties": {
  4.    "text": {
  5.    "type": "text",
  6.    "term_vector": "with_positions_offsets_payloads",
  7.    "store" : true,
  8.    "analyzer" : "fulltext_analyzer"
  9.    },
  10.    "fullname": {
  11.    "type": "text",
  12.    "term_vector": "with_positions_offsets_payloads",
  13.    "analyzer" : "fulltext_analyzer"
  14.    }
  15.    }
  16.   },
  17.   "settings" : {
  18.    "index" : {
  19.    "number_of_shards" : 1,
  20.    "number_of_replicas" : 0
  21.    },
  22.    "analysis": {
  23.    "analyzer": {
  24.    "fulltext_analyzer": {
  25.    "type": "custom",
  26.    "tokenizer": "whitespace",
  27.    "filter": [
  28.    "lowercase",
  29.    "type_as_payload"
  30.    ]
  31.    }
  32.    }
  33.    }
  34.   }
  35. }

次に、いくつかのドキュメントを追加します：

Python

  1. resp = client.index(
  2.    index="my-index-000001",
  3.    id="1",
  4.    document={
  5.    "fullname": "John Doe",
  6.    "text": "test test test "
  7.    },
  8. )
  9. print(resp)
  11. resp1 = client.index(
  12.    index="my-index-000001",
  13.    id="2",
  14.    refresh="wait_for",
  15.    document={
  16.    "fullname": "Jane Doe",
  17.    "text": "Another test ..."
  18.    },
  19. )
  20. print(resp1)

Ruby

  1. response = client.index(
  2.   index: 'my-index-000001',
  3.   id: 1,
  4.   body: {
  5.    fullname: 'John Doe',
  6.    text: 'test test test '
  7.   }
  8. )
  9. puts response
  11. response = client.index(
  12.   index: 'my-index-000001',
  13.   id: 2,
  14.   refresh: 'wait_for',
  15.   body: {
  16.    fullname: 'Jane Doe',
  17.    text: 'Another test ...'
  18.   }
  19. )
  20. puts response

Js

  1. const response = await client.index({
  2.   index: "my-index-000001",
  3.   id: 1,
  4.   document: {
  5.    fullname: "John Doe",
  6.    text: "test test test ",
  7.   },
  8. });
  9. console.log(response);
  11. const response1 = await client.index({
  12.   index: "my-index-000001",
  13.   id: 2,
  14.   refresh: "wait_for",
  15.   document: {
  16.    fullname: "Jane Doe",
  17.    text: "Another test ...",
  18.   },
  19. });
  20. console.log(response1);

Console

  1. PUT /my-index-000001/_doc/1
  2. {
  3.   "fullname" : "John Doe",
  4.   "text" : "test test test "
  5. }
  7. PUT /my-index-000001/_doc/2?refresh=wait_for
  8. {
  9.   "fullname" : "Jane Doe",
  10.   "text" : "Another test ..."
  11. }

次のリクエストは、ドキュメント1（ジョン・ドー）のフィールドtextに関するすべての情報と統計を返します：

Python

  1. resp = client.termvectors(
  2.    index="my-index-000001",
  3.    id="1",
  4.    fields=[
  5.    "text"
  6.    ],
  7.    offsets=True,
  8.    payloads=True,
  9.    positions=True,
  10.    term_statistics=True,
  11.    field_statistics=True,
  12. )
  13. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   id: 1,
  4.   body: {
  5.    fields: [
  6.    'text'
  7.    ],
  8.    offsets: true,
  9.    payloads: true,
  10.    positions: true,
  11.    term_statistics: true,
  12.    field_statistics: true
  13.   }
  14. )
  15. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   id: 1,
  4.   fields: ["text"],
  5.   offsets: true,
  6.   payloads: true,
  7.   positions: true,
  8.   term_statistics: true,
  9.   field_statistics: true,
  10. });
  11. console.log(response);

Console

  1. GET /my-index-000001/_termvectors/1
  2. {
  3.   "fields" : ["text"],
  4.   "offsets" : true,
  5.   "payloads" : true,
  6.   "positions" : true,
  7.   "term_statistics" : true,
  8.   "field_statistics" : true
  9. }

応答：

Console-Result

  1. {
  2.   "_index": "my-index-000001",
  3.   "_id": "1",
  4.   "_version": 1,
  5.   "found": true,
  6.   "took": 6,
  7.   "term_vectors": {
  8.    "text": {
  9.    "field_statistics": {
  10.    "sum_doc_freq": 4,
  11.    "doc_count": 2,
  12.    "sum_ttf": 6
  13.    },
  14.    "terms": {
  15.    "test": {
  16.    "doc_freq": 2,
  17.    "ttf": 4,
  18.    "term_freq": 3,
  19.    "tokens": [
  20.    {
  21.    "position": 0,
  22.    "start_offset": 0,
  23.    "end_offset": 4,
  24.    "payload": "d29yZA=="
  25.    },
  26.    {
  27.    "position": 1,
  28.    "start_offset": 5,
  29.    "end_offset": 9,
  30.    "payload": "d29yZA=="
  31.    },
  32.    {
  33.    "position": 2,
  34.    "start_offset": 10,
  35.    "end_offset": 14,
  36.    "payload": "d29yZA=="
  37.    }
  38.    ]
  39.    }
  40.    }
  41.    }
  42.   }
  43. }

Generating term vectors on the fly

インデックスに明示的に保存されていない用語ベクトルは、自動的にその場で計算されます。次のリクエストは、ドキュメント1のフィールドに関するすべての情報と統計を返しますが、用語はインデックスに明示的に保存されていません。フィールドtextについては、用語は再生成されません。

Python

  1. resp = client.termvectors(
  2.    index="my-index-000001",
  3.    id="1",
  4.    fields=[
  5.    "text",
  6.    "some_field_without_term_vectors"
  7.    ],
  8.    offsets=True,
  9.    positions=True,
  10.    term_statistics=True,
  11.    field_statistics=True,
  12. )
  13. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   id: 1,
  4.   body: {
  5.    fields: [
  6.    'text',
  7.    'some_field_without_term_vectors'
  8.    ],
  9.    offsets: true,
  10.    positions: true,
  11.    term_statistics: true,
  12.    field_statistics: true
  13.   }
  14. )
  15. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   id: 1,
  4.   fields: ["text", "some_field_without_term_vectors"],
  5.   offsets: true,
  6.   positions: true,
  7.   term_statistics: true,
  8.   field_statistics: true,
  9. });
  10. console.log(response);

Console

  1. GET /my-index-000001/_termvectors/1
  2. {
  3.   "fields" : ["text", "some_field_without_term_vectors"],
  4.   "offsets" : true,
  5.   "positions" : true,
  6.   "term_statistics" : true,
  7.   "field_statistics" : true
  8. }

Artificial documents

用語ベクトルは、インデックスに存在しない人工ドキュメントに対しても生成できます。たとえば、次のリクエストは、例1と同じ結果を返します。使用されるマッピングはindexによって決まります。

動的マッピングがオンになっている場合（デフォルト）、元の
マッピングにないドキュメントフィールドは動的に作成されます。

Python

  1. resp = client.termvectors(
  2.    index="my-index-000001",
  3.    doc={
  4.    "fullname": "John Doe",
  5.    "text": "test test test"
  6.    },
  7. )
  8. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   body: {
  4.    doc: {
  5.    fullname: 'John Doe',
  6.    text: 'test test test'
  7.    }
  8.   }
  9. )
  10. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   doc: {
  4.    fullname: "John Doe",
  5.    text: "test test test",
  6.   },
  7. });
  8. console.log(response);

Console

  1. GET /my-index-000001/_termvectors
  2. {
  3.   "doc" : {
  4.    "fullname" : "John Doe",
  5.    "text" : "test test test"
  6.   }
  7. }

Per-field analyzer

さらに、per_field_analyzerパラメータを使用して、フィールドのものとは異なるアナライザーを提供できます。これは、特に人工ドキュメントを使用する場合に、任意の方法で用語ベクトルを生成するのに役立ちます。用語ベクトルをすでに保存しているフィールドにアナライザーを提供する場合、用語ベクトルは再生成されます。

Python

  1. resp = client.termvectors(
  2.    index="my-index-000001",
  3.    doc={
  4.    "fullname": "John Doe",
  5.    "text": "test test test"
  6.    },
  7.    fields=[
  8.    "fullname"
  9.    ],
  10.    per_field_analyzer={
  11.    "fullname": "keyword"
  12.    },
  13. )
  14. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'my-index-000001',
  3.   body: {
  4.    doc: {
  5.    fullname: 'John Doe',
  6.    text: 'test test test'
  7.    },
  8.    fields: [
  9.    'fullname'
  10.    ],
  11.    per_field_analyzer: {
  12.    fullname: 'keyword'
  13.    }
  14.   }
  15. )
  16. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "my-index-000001",
  3.   doc: {
  4.    fullname: "John Doe",
  5.    text: "test test test",
  6.   },
  7.   fields: ["fullname"],
  8.   per_field_analyzer: {
  9.    fullname: "keyword",
  10.   },
  11. });
  12. console.log(response);

Console

  1. GET /my-index-000001/_termvectors
  2. {
  3.   "doc" : {
  4.    "fullname" : "John Doe",
  5.    "text" : "test test test"
  6.   },
  7.   "fields": ["fullname"],
  8.   "per_field_analyzer" : {
  9.    "fullname": "keyword"
  10.   }
  11. }

応答：

Console-Result

  1. {
  2.   "_index": "my-index-000001",
  3.   "_version": 0,
  4.   "found": true,
  5.   "took": 6,
  6.   "term_vectors": {
  7.    "fullname": {
  8.    "field_statistics": {
  9.    "sum_doc_freq": 2,
  10.    "doc_count": 4,
  11.    "sum_ttf": 4
  12.    },
  13.    "terms": {
  14.    "John Doe": {
  15.    "term_freq": 1,
  16.    "tokens": [
  17.    {
  18.    "position": 0,
  19.    "start_offset": 0,
  20.    "end_offset": 8
  21.    }
  22.    ]
  23.    }
  24.    }
  25.    }
  26.   }
  27. }

Terms filtering

最後に、返される用語はtf-idfスコアに基づいてフィルタリングされる可能性があります。以下の例では、与えられた「プロット」フィールド値を持つ人工ドキュメントから、最も「興味深い」3つのキーワードを取得します。キーワード「トニー」やその他のストップワードは、tf-idfが低すぎるため、応答の一部ではありません。

Python

  1. resp = client.termvectors(
  2.    index="imdb",
  3.    doc={
  4.    "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."
  5.    },
  6.    term_statistics=True,
  7.    field_statistics=True,
  8.    positions=False,
  9.    offsets=False,
  10.    filter={
  11.    "max_num_terms": 3,
  12.    "min_term_freq": 1,
  13.    "min_doc_freq": 1
  14.    },
  15. )
  16. print(resp)

Ruby

  1. response = client.termvectors(
  2.   index: 'imdb',
  3.   body: {
  4.    doc: {
  5.    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.'
  6.    },
  7.    term_statistics: true,
  8.    field_statistics: true,
  9.    positions: false,
  10.    offsets: false,
  11.    filter: {
  12.    max_num_terms: 3,
  13.    min_term_freq: 1,
  14.    min_doc_freq: 1
  15.    }
  16.   }
  17. )
  18. puts response

Js

  1. const response = await client.termvectors({
  2.   index: "imdb",
  3.   doc: {
  4.    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.",
  5.   },
  6.   term_statistics: true,
  7.   field_statistics: true,
  8.   positions: false,
  9.   offsets: false,
  10.   filter: {
  11.    max_num_terms: 3,
  12.    min_term_freq: 1,
  13.    min_doc_freq: 1,
  14.   },
  15. });
  16. console.log(response);

Console

  1. GET /imdb/_termvectors
  2. {
  3.   "doc": {
  4.    "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."
  5.   },
  6.   "term_statistics": true,
  7.   "field_statistics": true,
  8.   "positions": false,
  9.   "offsets": false,
  10.   "filter": {
  11.    "max_num_terms": 3,
  12.    "min_term_freq": 1,
  13.    "min_doc_freq": 1
  14.   }
  15. }

応答：

Console-Result

  1. {
  2.    "_index": "imdb",
  3.    "_version": 0,
  4.    "found": true,
  5.    "term_vectors": {
  6.    "plot": {
  7.    "field_statistics": {
  8.    "sum_doc_freq": 3384269,
  9.    "doc_count": 176214,
  10.    "sum_ttf": 3753460
  11.    },
  12.    "terms": {
  13.    "armored": {
  14.    "doc_freq": 27,
  15.    "ttf": 27,
  16.    "term_freq": 1,
  17.    "score": 9.74725
  18.    },
  19.    "industrialist": {
  20.    "doc_freq": 88,
  21.    "ttf": 88,
  22.    "term_freq": 1,
  23.    "score": 8.590818
  24.    },
  25.    "stark": {
  26.    "doc_freq": 44,
  27.    "ttf": 47,
  28.    "term_freq": 1,
  29.    "score": 9.272792
  30.    }
  31.    }
  32.    }
  33.    }
  34. }