› › ›

API mget (многократный запрос по документам)

Извлекает несколько JSON документов по ID.

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

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

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

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

Запрос

GET /_mget

GET /<index>/_mget

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

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

Описание

Вы используете mget для извлечения нескольких документов из одного или нескольких индексов. Если вы указываете индекс в URI запроса, вам нужно указать только идентификаторы документов в теле запроса.

Безопасность

См. Управление доступом через URL.

Частичные ответы

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

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

<index>: (Необязательно, строка) Имя индекса, из которого извлекаются документы, когда ids указаны, или когда документ в массиве docs не указывает индекс.

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

preference

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

realtime

(Необязательно, логическое значение) Если true, запрос является реальным, а не почти реальным. По умолчанию true. См. Реальное время.

refresh

(Необязательно, логическое значение) Если true, запрос обновляет соответствующие фрагменты перед извлечением документов. По умолчанию false.

routing

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

stored_fields

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

_source

(Необязательно, строка) Значение True или False для возвращения поля _source или его списка.

_source_excludes

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

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

Если параметр _source равен false, этот параметр игнорируется.

_source_includes

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

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

Если параметр _source равен false, этот параметр игнорируется.

Тело запроса

docs

(Необязательно, массив) Документы, которые вы хотите извлечь. Требуется, если индекс не указан в URI запроса. Вы можете указать следующие атрибуты для каждого документа:

_id

(Обязательно, строка) Уникальный идентификатор документа.

_index

(Необязательно, строка) Индекс, содержащий документ. Требуется, если индекс не указан в URI запроса.

routing

(Необязательно, строка) Ключ первичного фрагмента, на котором находится документ. Требуется, если при индексировании используется маршрутизация.

_source

(Необязательно, логическое значение) Если false, исключаются все поля _source. По умолчанию true.

source_include: (Необязательно, массив) Поля для извлечения и возвращения из поля _source.
source_exclude: (Необязательно, массив) Поля для исключения из возвращаемого поля _source.

_stored_fields

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

ids

(Необязательно, массив) Идентификаторы документов, которые вы хотите получить. Разрешено, когда индекс указан в URI запроса.

Тело ответа

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

Примеры

Получение документов по ID

Если вы указываете индекс в запросе URI, в теле запроса требуются только идентификаторы документов:

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

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

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

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

Вы можете использовать элемент ids для упрощения запроса:

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

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

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

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

Фильтрация полей источника

По умолчанию поле _source возвращается для каждого документа (если оно хранится). Используйте атрибуты _source и _source_include или source_exclude для фильтрации возвращаемых полей конкретного документа. Вы можете включить параметры запроса _source, _source_includes и _source_excludes в URI запроса, чтобы указать значения по умолчанию для случаев, когда нет инструкций для каждого документа.

Например, следующий запрос устанавливает _source в false для документа 1, чтобы исключить источник полностью, извлекает field3 и field4 из документа 2 и извлекает поле user из документа 3, но фильтрует поле user.location.

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)

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

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);

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" ]
      }
    }
  ]
}

Получение сохранённых полей

Используйте атрибут stored_fields для указания набора сохранённых полей, которые вы хотите получить. Любые запрошенные поля, которые не хранятся, игнорируются. Вы можете включить параметр запроса stored_fields в URI запроса для указания значений по умолчанию, если нет инструкций для каждого документа.

Например, следующий запрос извлекает field1 и field2 из документа 1 и field3 и field4 из документа 2:

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

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

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);

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

Следующий запрос извлекает field1 и field2 по умолчанию из всех документов. Эти поля по умолчанию возвращаются для документа 1, но переопределяются для возврата field3 и field4 для документа 2.

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

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

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

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

Указание маршрутизации документов

Если маршрутизация используется во время индексирования, вам необходимо указать значение маршрутизации для извлечения документов. Например, следующий запрос извлекает test/_doc/2 из фрагмента, соответствующего ключу маршрутизации key1, и извлекает test/_doc/1 из фрагмента, соответствующего ключу маршрутизации key2.

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

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

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

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

© 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-multi-get.html