ドキュメントAPI - マルチ取得（Multi get） - 《Elasticsearchガイドv8.15》日本語

Multi get (mget) API
Request
Prerequisites
Description
Query parameters
Request body
Response body
Examples

Multi get (mget) API

IDによって複数のJSONドキュメントを取得します。

Python

resp = client.mget(
   docs=[
   {
   "_index": "my-index-000001",
   "_id": "1"
   },
   {
   "_index": "my-index-000001",
   "_id": "2"
   }
   ],
)
print(resp)

Ruby

response = client.mget(
  body: {
   docs: [
   {
   _index: 'my-index-000001',
   _id: '1'
   },
   {
   _index: 'my-index-000001',
   _id: '2'
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  docs: [
   {
   _index: "my-index-000001",
   _id: "1",
   },
   {
   _index: "my-index-000001",
   _id: "2",
   },
  ],
});
console.log(response);

Console

GET /_mget
{
  "docs": [
   {
   "_index": "my-index-000001",
   "_id": "1"
   },
   {
   "_index": "my-index-000001",
   "_id": "2"
   }
  ]
}

Request

GET /_mget

GET /<index>/_mget

Prerequisites

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

Description


### Security
[URLベースのアクセス制御](b10cb0563daae284.md#api-url-access-control)を参照してください。
### Partial responses
迅速な応答を確保するために、マルチゲットAPIは1つ以上のシャードが失敗した場合、部分的な結果で応答します。詳細については[シャードの失敗](83d4872de54fc54b.md#shard-failures)を参照してください。
## Path parameters
-   `````<index>

(オプション、文字列) idsが指定されている場合、またはdocs配列内のドキュメントがインデックスを指定していない場合に、ドキュメントを取得するインデックスの名前。

Query parameters

preference
(オプション、文字列) 操作を実行するノードまたはシャードを指定します。デフォルトではランダムです。
realtime
(オプション、ブール値) trueの場合、リクエストはリアルタイムであり、近リアルタイムではありません。デフォルトはtrueです。リアルタイムを参照してください。
refresh
(オプション、ブール値) trueの場合、リクエストはドキュメントを取得する前に関連するシャードを更新します。デフォルトはfalseです。
routing
(オプション、文字列) 操作を特定のシャードにルーティングするために使用されるカスタム値。
stored_fields
(オプション、文字列) 応答に含めるstored fieldsのカンマ区切りリスト。
_source
(オプション、文字列) _sourceフィールドを返すかどうか、または返すフィールドのリスト。
_source_excludes
(オプション、文字列) 応答から除外する@source fieldsのカンマ区切りリスト。
このパラメータを使用して、_source_includesクエリパラメータで指定されたサブセットからフィールドを除外することもできます。
_sourceパラメータがfalseの場合、このパラメータは無視されます。
_source_includes
(オプション、文字列) 応答に含める@source fieldsのカンマ区切りリスト。
このパラメータが指定されている場合、これらのソースフィールドのみが返されます。このサブセットからフィールドを除外するには、_source_excludesクエリパラメータを使用できます。
_sourceパラメータがfalseの場合、このパラメータは無視されます。

Request body

docs
(オプション、配列) 取得したいドキュメント。リクエストURIにインデックスが指定されていない場合は必須です。各ドキュメントに対して次の属性を指定できます:
- _id
- (必須、文字列) 一意のドキュメントID。
- _index
- (オプション、文字列) ドキュメントを含むインデックス。リクエストURIにインデックスが指定されていない場合は必須です。
- routing
- (オプション、文字列) ドキュメントが存在するプライマリシャードのキー。インデックス時にルーティングが使用される場合は必須です。
- _source
- (オプション、ブール値) falseの場合、すべての_sourceフィールドを除外します。デフォルトはtrueです。
  - source_include
  - (オプション、配列) _sourceフィールドから抽出して返すフィールド。
  - source_exclude
  - (オプション、配列) 返される_sourceフィールドから除外するフィールド。
- _stored_fields
- (オプション、配列) 取得したい保存されたフィールド。
ids
(オプション、配列) 取得したいドキュメントのID。リクエストURIにインデックスが指定されている場合に許可されます。

Response body

応答には、リクエストで指定された順序でドキュメントを含むdocs配列が含まれます。返されるドキュメントの構造は、get APIによって返されるものに似ています。特定のドキュメントを取得する際に失敗があった場合、エラーはドキュメントの代わりに含まれます。

Examples

Get documents by ID

リクエストURIにインデックスを指定した場合、リクエストボディにはドキュメントIDのみが必要です:

Python

resp = client.mget(
   index="my-index-000001",
   docs=[
   {
   "_id": "1"
   },
   {
   "_id": "2"
   }
   ],
)
print(resp)

Ruby

response = client.mget(
  index: 'my-index-000001',
  body: {
   docs: [
   {
   _id: '1'
   },
   {
   _id: '2'
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  index: "my-index-000001",
  docs: [
   {
   _id: "1",
   },
   {
   _id: "2",
   },
  ],
});
console.log(response);

Console

GET /my-index-000001/_mget
{
  "docs": [
   {
   "_id": "1"
   },
   {
   "_id": "2"
   }
  ]
}


#### Python
``````python
resp = client.mget(
   index="my-index-000001",
   ids=[
   "1",
   "2"
   ],
)
print(resp)
`

Ruby

response = client.mget(
  index: 'my-index-000001',
  body: {
   ids: [
   '1',
   '2'
   ]
  }
)
puts response

Js

const response = await client.mget({
  index: "my-index-000001",
  ids: ["1", "2"],
});
console.log(response);

Console

GET /my-index-000001/_mget
{
  "ids" : ["1", "2"]
}

Filter source fields

デフォルトでは、すべてのドキュメントに対して_sourceフィールドが返されます（保存されている場合）。_sourceおよび_source_includeまたはsource_exclude属性を使用して、特定のドキュメントに対して返されるフィールドをフィルタリングできます。_source、_source_includes、および_source_excludesクエリパラメータをリクエストURIに含めて、個別のドキュメント指示がない場合に使用するデフォルトを指定できます。

たとえば、次のリクエストは、ドキュメント1の_sourceをfalseに設定してソースを完全に除外し、ドキュメント2からfield3およびfield4を取得し、ドキュメント3からuserフィールドを取得しますが、user.locationフィールドをフィルタリングします。

Python

resp = client.mget(
   docs=[
   {
   "_index": "test",
   "_id": "1",
   "_source": False
   },
   {
   "_index": "test",
   "_id": "2",
   "_source": [
   "field3",
   "field4"
   ]
   },
   {
   "_index": "test",
   "_id": "3",
   "_source": {
   "include": [
   "user"
   ],
   "exclude": [
   "user.location"
   ]
   }
   }
   ],
)
print(resp)

Ruby

response = client.mget(
  body: {
   docs: [
   {
   _index: 'test',
   _id: '1',
   _source: false
   },
   {
   _index: 'test',
   _id: '2',
   _source: [
   'field3',
   'field4'
   ]
   },
   {
   _index: 'test',
   _id: '3',
   _source: {
   include: [
   'user'
   ],
   exclude: [
   'user.location'
   ]
   }
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  docs: [
   {
   _index: "test",
   _id: "1",
   _source: false,
   },
   {
   _index: "test",
   _id: "2",
   _source: ["field3", "field4"],
   },
   {
   _index: "test",
   _id: "3",
   _source: {
   include: ["user"],
   exclude: ["user.location"],
   },
   },
  ],
});
console.log(response);

Console

GET /_mget
{
  "docs": [
   {
   "_index": "test",
   "_id": "1",
   "_source": false
   },
   {
   "_index": "test",
   "_id": "2",
   "_source": [ "field3", "field4" ]
   },
   {
   "_index": "test",
   "_id": "3",
   "_source": {
   "include": [ "user" ],
   "exclude": [ "user.location" ]
   }
   }
  ]
}

Get stored fields


たとえば、次のリクエストは、ドキュメント1から`````field1`````および`````field2`````を取得し、ドキュメント2から`````field3`````および`````field4`````を取得します:
#### Python
``````python
resp = client.mget(
   docs=[
   {
   "_index": "test",
   "_id": "1",
   "stored_fields": [
   "field1",
   "field2"
   ]
   },
   {
   "_index": "test",
   "_id": "2",
   "stored_fields": [
   "field3",
   "field4"
   ]
   }
   ],
)
print(resp)
`

Ruby

response = client.mget(
  body: {
   docs: [
   {
   _index: 'test',
   _id: '1',
   stored_fields: [
   'field1',
   'field2'
   ]
   },
   {
   _index: 'test',
   _id: '2',
   stored_fields: [
   'field3',
   'field4'
   ]
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  docs: [
   {
   _index: "test",
   _id: "1",
   stored_fields: ["field1", "field2"],
   },
   {
   _index: "test",
   _id: "2",
   stored_fields: ["field3", "field4"],
   },
  ],
});
console.log(response);

Console

GET /_mget
{
  "docs": [
   {
   "_index": "test",
   "_id": "1",
   "stored_fields": [ "field1", "field2" ]
   },
   {
   "_index": "test",
   "_id": "2",
   "stored_fields": [ "field3", "field4" ]
   }
  ]
}

次のリクエストは、デフォルトでfield1およびfield2をすべてのドキュメントから取得します。これらのデフォルトフィールドはドキュメント1に対して返されますが、ドキュメント2に対してfield3およびfield4を返すように上書きされます。

Python

resp = client.mget(
   index="test",
   stored_fields="field1,field2",
   docs=[
   {
   "_id": "1"
   },
   {
   "_id": "2",
   "stored_fields": [
   "field3",
   "field4"
   ]
   }
   ],
)
print(resp)

Ruby

response = client.mget(
  index: 'test',
  stored_fields: 'field1,field2',
  body: {
   docs: [
   {
   _id: '1'
   },
   {
   _id: '2',
   stored_fields: [
   'field3',
   'field4'
   ]
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  index: "test",
  stored_fields: "field1,field2",
  docs: [
   {
   _id: "1",
   },
   {
   _id: "2",
   stored_fields: ["field3", "field4"],
   },
  ],
});
console.log(response);

Console

GET /test/_mget?stored_fields=field1,field2
{
  "docs": [
   {
   "_id": "1"
   },
   {
   "_id": "2",
   "stored_fields": [ "field3", "field4" ]
   }
  ]
}

Specify document routing

インデックス時にルーティングが使用される場合、ドキュメントを取得するためにルーティング値を指定する必要があります。たとえば、次のリクエストは、ルーティングキーkey1に対応するシャードからtest/_doc/2を取得し、ルーティングキーkey2に対応するシャードからtest/_doc/1を取得します。

Python

resp = client.mget(
   routing="key1",
   docs=[
   {
   "_index": "test",
   "_id": "1",
   "routing": "key2"
   },
   {
   "_index": "test",
   "_id": "2"
   }
   ],
)
print(resp)

Ruby

response = client.mget(
  routing: 'key1',
  body: {
   docs: [
   {
   _index: 'test',
   _id: '1',
   routing: 'key2'
   },
   {
   _index: 'test',
   _id: '2'
   }
   ]
  }
)
puts response

Js

const response = await client.mget({
  routing: "key1",
  docs: [
   {
   _index: "test",
   _id: "1",
   routing: "key2",
   },
   {
   _index: "test",
   _id: "2",
   },
  ],
});
console.log(response);

Console

GET /_mget?routing=key1
{
  "docs": [
   {
   "_index": "test",
   "_id": "1",
   "routing": "key2"
   },
   {
   "_index": "test",
   "_id": "2"
   }
  ]
}