Spec-Zone.ru › CouchDB 3.5

/{db}/_all_docs

GET /{db}/_all_docs

Выполняет встроенное _all_docs представление, возвращая все документы из базы данных. За исключением параметров URL (описанных ниже), эта конечная точка работает так же, как и любое другое представление. Полное описание доступных параметров запроса и формата возвращаемых данных см. в документации конечной точки представления.

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Content-Type – application/json

Заголовки ответа:

  • Content-Type –

    • application/json

Коды состояния:

  • 200 ОК – Запрос успешно выполнен

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Запрошенная база данных не найдена

Запрос:

GET /db/_all_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 10 Aug 2013 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "16e458537602f5ef2a710089dffd9453",
            "key": "16e458537602f5ef2a710089dffd9453",
            "value": {
                "rev": "1-967a00dff5e02add41819138abb3284d"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c431114001aff",
            "key": "a4c51cdfa2069f3e905c431114001aff",
            "value": {
                "rev": "1-967a00dff5e02add41819138abb3284d"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c4311140034aa",
            "key": "a4c51cdfa2069f3e905c4311140034aa",
            "value": {
                "rev": "5-6182c9c954200ab5e3c6bd5e76a1549f"
            }
        },
        {
            "id": "a4c51cdfa2069f3e905c431114003597",
            "key": "a4c51cdfa2069f3e905c431114003597",
            "value": {
                "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
            }
        },
        {
            "id": "f4ca7773ddea715afebc4b4b15d4f0b3",
            "key": "f4ca7773ddea715afebc4b4b15d4f0b3",
            "value": {
                "rev": "2-7051cbe5c8faecd085a3fa619e6e6337"
            }
        }
    ],
    "total_rows": 5
}
POST /{db}/_all_docs

Функция POST _all_docs поддерживает те же параметры и поведение, что и API GET /{db}/_all_docs, но позволяет передавать параметры строки запроса в виде ключей JSON-объекта в теле запроса POST.

Запрос:

POST /db/_all_docs HTTP/1.1
Accept: application/json
Content-Length: 70
Content-Type: application/json
Host: localhost:5984

{
    "keys" : [
        "Zingylemontart",
        "Yogurtraita"
    ]
}

Ответ:

{
    "total_rows" : 2666,
    "rows" : [
        {
            "value" : {
                "rev" : "1-a3544d296de19e6f5b932ea77d886942"
            },
            "id" : "Zingylemontart",
            "key" : "Zingylemontart"
        },
        {
            "value" : {
                "rev" : "1-91635098bfe7d40197a1b98d7ee085fc"
            },
            "id" : "Yogurtraita",
            "key" : "Yogurtraita"
        }
    ],
    "offset" : 0
}

/{db}/_design_docs

Добавлено в версии 2.2.

GET /{db}/_design_docs

Возвращает структуру JSON со всеми документами дизайна в указанной базе данных. Информация возвращается в виде структуры JSON, содержащей метаданные о структуре ответа, включая список всех документов дизайна и их основные данные: идентификатор, ревизию и ключ. Ключ — это _id документа дизайна.

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Accept –

    • application/json

    • text/plain

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

  • conflicts (boolean) – Включает сведения о conflicts в ответ. Игнорируется, если include_docs не равен true. По умолчанию — false.

  • descending (boolean) – Возвращать документы дизайна в порядке убывания ключа. По умолчанию — false.

  • endkey (string) – Прекратить возвращать записи при достижении указанного ключа. Необязательный параметр.

  • end_key (string) – Псевдоним параметра endkey.

  • endkey_docid (string) – Прекратить возвращать записи при достижении указанного идентификатора документа дизайна. Необязательный параметр.

  • end_key_doc_id (string) – Псевдоним параметра endkey_docid.

  • include_docs (boolean) – Включать полный текст документов дизайна в ответ. По умолчанию — false.

  • inclusive_end (boolean) – Указывает, следует ли включать указанный конечный ключ в результат. По умолчанию — true.

  • key (string) – Возвращать только документы дизайна, соответствующие указанному ключу. Необязательный параметр.

  • keys (string) – Возвращать только документы дизайна, соответствующие указанным ключам. Необязательный параметр.

  • limit (number) – Ограничить количество возвращаемых документов дизайна указанным числом. Необязательный параметр.

  • skip (number) – Пропустить указанное количество записей перед началом возврата результатов. По умолчанию — 0.

  • startkey (string) – Возвращать записи, начиная с указанного ключа. Необязательный параметр.

  • start_key (string) – Псевдоним параметра startkey.

  • startkey_docid (string) – Возвращать записи, начиная с указанного идентификатора документа дизайна. Необязательный параметр.

  • start_key_doc_id (string) – Псевдоним параметра startkey_docid.

  • update_seq (boolean) – Ответ содержит значение update_seq, указывающее, какой идентификатор последовательности базовой базы данных отражает представление. По умолчанию — false.

Заголовки ответа:

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  • ETag – Подпись ответа

Объект JSON ответа:

  • offset (number) – Смещение, с которого начинается список документов дизайна

  • rows (array) – Массив объектов строк представления. По умолчанию возвращаемые данные содержат только идентификатор и ревизию документа дизайна.

  • total_rows (number) – Количество документов дизайна в базе данных. Обратите внимание, что это не количество строк, возвращённых фактическим запросом.

  • update_seq (number) – Текущая последовательность обновлений базы данных

Коды состояния:

  • 200 ОК – Запрос успешно выполнен

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Запрошенная база данных не найдена

Запрос:

GET /db/_design_docs HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Sat, 23 Dec 2017 16:22:56 GMT
ETag: "1W2DJUZFZSZD9K78UFA3GZWB4"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "_design/ddoc01",
            "key": "_design/ddoc01",
            "value": {
                "rev": "1-7407569d54af5bc94c266e70cbf8a180"
            }
        },
        {
            "id": "_design/ddoc02",
            "key": "_design/ddoc02",
            "value": {
                "rev": "1-d942f0ce01647aa0f46518b213b5628e"
            }
        },
        {
            "id": "_design/ddoc03",
            "key": "_design/ddoc03",
            "value": {
                "rev": "1-721fead6e6c8d811a225d5a62d08dfd0"
            }
        },
        {
            "id": "_design/ddoc04",
            "key": "_design/ddoc04",
            "value": {
                "rev": "1-32c76b46ca61351c75a84fbcbceece2f"
            }
        },
        {
            "id": "_design/ddoc05",
            "key": "_design/ddoc05",
            "value": {
                "rev": "1-af856babf9cf746b48ae999645f9541e"
            }
        }
    ],
    "total_rows": 5
}
POST /{db}/_design_docs

Функция POST _design_docs поддерживает те же параметры и поведение, что и API GET /{db}/_design_docs, но позволяет передавать параметры строки запроса в виде ключей JSON-объекта в теле запроса POST.

Запрос:

POST /db/_design_docs HTTP/1.1
Accept: application/json
Content-Length: 70
Content-Type: application/json
Host: localhost:5984

{
    "keys" : [
        "_design/ddoc02",
        "_design/ddoc05"
    ]
}

Возвращаемый JSON имеет структуру всех документов, но в выходных данных содержит только выбранные ключи:

Ответ:

{
    "total_rows" : 5,
    "rows" : [
        {
            "value" : {
                "rev" : "1-d942f0ce01647aa0f46518b213b5628e"
            },
            "id" : "_design/ddoc02",
            "key" : "_design/ddoc02"
        },
        {
            "value" : {
                "rev" : "1-af856babf9cf746b48ae999645f9541e"
            },
            "id" : "_design/ddoc05",
            "key" : "_design/ddoc05"
        }
    ],
    "offset" : 0
}

Отправка нескольких запросов к базе данных

/{db}/_all_docs/queries

Добавлено в версии 2.2.

POST /{db}/_all_docs/queries

Выполняет несколько указанных запросов к встроенному представлению всех документов этой базы данных. Это позволяет запрашивать несколько результатов одним запросом вместо нескольких запросов POST /{db}/_all_docs.

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Content-Type –

    • application/json

  • Accept –

    • application/json

Объект JSON запроса:

  • queries – Массив объектов запросов с полями, задающими параметры каждого отдельного запроса к представлению. Имена полей и их значения совпадают с параметрами запроса обычного запроса _all_docs.

Заголовки ответа:

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  • ETag – Подпись ответа

  • Transfer-Encoding – chunked

Объект JSON ответа:

  • results (array) – Массив объектов результатов — по одному для каждого запроса. Каждый объект результата содержит те же поля, что и ответ на обычный запрос _all_docs.

Коды состояния:

  • 200 ОК – Запрос успешно выполнен

  • 400 Неверный запрос – Недопустимый запрос

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Указанная база данных отсутствует

  • 500 Внутренняя ошибка сервера – Ошибка выполнения запроса

Запрос:

POST /db/_all_docs/queries HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:5984

{
    "queries": [
        {
            "keys": [
                "meatballs",
                "spaghetti"
            ]
        },
        {
            "limit": 3,
            "skip": 2
        }
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 20 Dec 2017 11:17:07 GMT
ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "results" : [
        {
            "rows": [
                {
                    "id": "meatballs",
                    "key": "meatballs",
                    "value": 1
                },
                {
                    "id": "spaghetti",
                    "key": "spaghetti",
                    "value": 1
                }
            ],
            "total_rows": 3
        },
        {
            "offset" : 2,
            "rows" : [
                {
                    "id" : "Adukiandorangecasserole-microwave",
                    "key" : "Aduki and orange casserole - microwave",
                    "value" : [
                        null,
                        "Aduki and orange casserole - microwave"
                    ]
                },
                {
                    "id" : "Aioli-garlicmayonnaise",
                    "key" : "Aioli - garlic mayonnaise",
                    "value" : [
                        null,
                        "Aioli - garlic mayonnaise"
                    ]
                },
                {
                    "id" : "Alabamapeanutchicken",
                    "key" : "Alabama peanut chicken",
                    "value" : [
                        null,
                        "Alabama peanut chicken"
                    ]
                }
            ],
            "total_rows" : 2667
        }
    ]
}

Примечание

Несколько запросов также поддерживаются в /{db}/_local_docs/queries и /{db}/_design_docs/queries (аналогично /{db}/_all_docs/queries).

/{db}/_design_docs/queries

POST /{db}/_design_docs/queries

Запрос с указанным keys вернёт только документы дизайна. Можно также объединять keys с другими параметрами запроса, например limit и skip.

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Content-Type –

    • application/json

  • Accept –

    • application/json

Объект JSON запроса:

  • queries – Массив объектов запросов с полями, задающими параметры каждого отдельного запроса к представлению. Имена полей и их значения совпадают с параметрами запроса обычного запроса _design_docs.

Заголовки ответа:

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

  • Transfer-Encoding – chunked

Объект JSON ответа:

  • results (array) – Массив объектов результатов — по одному для каждого запроса. Каждый объект результата содержит те же поля, что и ответ на обычный запрос _design_docs.

Коды состояния:

  • 200 ОК – Запрос успешно выполнен

  • 400 Неверный запрос – Недопустимый запрос

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Указанная база данных отсутствует

  • 500 Внутренняя ошибка сервера – Ошибка выполнения запроса

Запрос:

POST /db/_design_docs/queries HTTP/1.1
Content-Type: application/json
Accept: application/json
Host: localhost:5984

{
    "queries": [
        {
            "keys": [
                "_design/recipe",
                "_design/not-exist",
                "spaghetti"
            ]
        }
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 20 Jul 2023 20:06:44 GMT
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "results": [
        {
            "total_rows": 1,
            "offset": null,
            "rows": [
                {
                    "id": "_design/recipe",
                    "key": "_design/recipe",
                    "value": {
                        "rev": "1-ad0e29fe6b473658514742a7c2317766"
                    }
                },
                {
                    "key": "_design/not-exist",
                    "error": "not_found"
                }
            ]
        }
    ]
}

Примечание

/{db}/_design_docs/queries с ключами возвращает только документы дизайна или "error": "not_found", если документ дизайна не существует. Если key не является идентификатором документа дизайна, он не будет включён в ответ.

/{db}/_bulk_get

POST /{db}/_bulk_get

Этот метод можно использовать для пакетного запроса нескольких документов. Он хорошо подходит для получения определённой ревизии документов, например при репликации, а также для получения истории ревизий. Полное описание доступных параметров запроса см. в документации конечной точки документа.

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Accept –

    • application/json

    • multipart/related

    • multipart/mixed

  • Content-Type – application/json

Объект JSON запроса:

  • docs (array) – Список объектов документов с id и необязательными rev и atts_since

Заголовки ответа:

  • Content-Type –

    • application/json

Объект JSON ответа:

  • results (object) – массив результатов для каждой запрошенной пары документ/ревизия. Ключ id содержит запрошенный идентификатор документа, docs содержит массив из одного элемента с объектом, в котором есть либо ключ error и значение с описанием ошибки, либо ключ ok и соответствующее значение запрошенного документа, а также дополнительное свойство _revisions со списком родительских ревизий, если revs=true.

Коды состояния:

  • 200 ОК – Запрос успешно выполнен

  • 400 Неверный запрос – В запросе переданы недопустимые данные JSON или недопустимый параметр запроса

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Недопустимое имя базы данных

  • 415 Неподдерживаемый тип медиа – Недопустимое значение Content-Type

Запрос:

POST /db/_bulk_get HTTP/1.1
Accept: application/json
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "id": "foo"
            "rev": "4-753875d51501a6b1883a9d62b4d33f91",
        },
        {
            "id": "foo"
            "rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
        },
        {
            "id": "bar"
        }
        {
            "id": "baz"
        }
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 19 Mar 2018 15:27:34 GMT
Server: CouchDB (Erlang/OTP)

{
  "results": [
    {
      "id": "foo",
      "docs": [
        {
          "ok": {
            "_id": "foo",
            "_rev": "4-753875d51501a6b1883a9d62b4d33f91",
            "value": "this is foo",
            "_revisions": {
              "start": 4,
              "ids": [
                "753875d51501a6b1883a9d62b4d33f91",
                "efc54218773c6acd910e2e97fea2a608",
                "2ee767305024673cfb3f5af037cd2729",
                "4a7e4ae49c4366eaed8edeaea8f784ad"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "foo",
      "docs": [
        {
          "ok": {
            "_id": "foo",
            "_rev": "1-4a7e4ae49c4366eaed8edeaea8f784ad",
            "value": "this is the first revision of foo",
            "_revisions": {
              "start": 1,
              "ids": [
                "4a7e4ae49c4366eaed8edeaea8f784ad"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "bar",
      "docs": [
        {
          "ok": {
            "_id": "bar",
            "_rev": "2-9b71d36dfdd9b4815388eb91cc8fb61d",
            "baz": true,
            "_revisions": {
              "start": 2,
              "ids": [
                "9b71d36dfdd9b4815388eb91cc8fb61d",
                "309651b95df56d52658650fb64257b97"
              ]
            }
          }
        }
      ]
    },
    {
      "id": "baz",
      "docs": [
        {
          "error": {
            "id": "baz",
            "rev": "undefined",
            "error": "not_found",
            "reason": "missing"
          }
        }
      ]
    }
  ]
}

Пример ответа с конфликтующим документом:

Запрос:

POST /db/_bulk_get HTTP/1.1
Accept: application/json
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "id": "a"
        }
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 19 Mar 2018 15:27:34 GMT
Server: CouchDB (Erlang/OTP)

{
  "results": [
    {
      "id": "a",
      "docs": [
        {
          "ok": {
            "_id": "a",
            "_rev": "1-23202479633c2b380f79507a776743d5",
            "a": 1
          }
        },
        {
          "ok": {
            "_id": "a",
            "_rev": "1-967a00dff5e02add41819138abb3284d"
          }
        }
      ]
    }
  ]
}

/{db}/_bulk_docs

POST /{db}/_bulk_docs

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

При создании новых документов идентификатор документа (_id) указывать необязательно.

Для обновления существующих документов необходимо указать идентификатор документа, данные о ревизии (_rev) и новые значения документа.

При пакетном удалении документов необходимо указать все поля: идентификатор документа, данные о ревизии и статус удаления (_deleted).

Параметры:

  • db – Имя базы данных

Заголовки запроса:

  • Accept –

    • application/json

    • text/plain

  • Content-Type – application/json

Объект JSON запроса:

  • docs (array) – Список объектов документов

  • new_edits (boolean) – Если false, база данных не будет назначать им новые идентификаторы ревизий. По умолчанию — true. Необязательно

Заголовки ответа:

  • Content-Type –

    • application/json

    • text/plain; charset=utf-8

Массив объектов JSON в ответе:

  • id (string) – Идентификатор документа

  • rev (string) – Новый токен ревизии документа. Доступен, если документ сохранён без ошибок. Необязательно

  • error (string) – Тип ошибки. Необязательно

  • reason (string) – Причина ошибки. Необязательно

Коды состояния:

  • 201 Создано – Документы созданы или обновлены

  • 400 Неверный запрос – В запросе переданы недопустимые данные JSON

  • 401 Не авторизован – Неавторизованный запрос к защищённому API

  • 403 Доступ запрещён – Недостаточно прав / Слишком много запросов с недействительными учётными данными

  • 404 Не найдено – Запрошенная база данных не найдена

Запрос:

POST /db/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 109
Content-Type:application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew"
        },
        {
            "_id": "LambStew",
            "_rev": "2-0786321986194c92dd3b57dfbfc741ce",
            "_deleted": true
        }
    ]
}

Ответ:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 144
Content-Type: application/json
Date: Mon, 12 Aug 2013 00:15:05 GMT
Server: CouchDB (Erlang/OTP)

[
    {
        "ok": true,
        "id": "FishStew",
        "rev":" 1-967a00dff5e02add41819138abb3284d"
    },
    {
        "ok": true,
        "id": "LambStew",
        "rev": "3-f9c62b2169d0999103e9f41949090807"
    }
]

Пакетная вставка документов

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

Она не предназначена для выполнения в CouchDB транзакций, подобных транзакциям ACID: единственная граница транзакции в CouchDB — это одно обновление одной базы данных. Ограничения подробно описаны в разделе Семантика транзакций при пакетной обработке документов.

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

Например, следующий запрос вставляет три новых документа: для двух указаны идентификаторы, а для одного идентификатор будет сгенерирован:

POST /source/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 323
Content-Type: application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew",
            "servings": 4,
            "subtitle": "Delicious with freshly baked bread",
            "title": "FishStew"
        },
        {
            "_id": "LambStew",
            "servings": 6,
            "subtitle": "Serve with a whole meal scone topping",
            "title": "LambStew"
        },
        {
            "servings": 8,
            "subtitle": "Hand-made dumplings make a great accompaniment",
            "title": "BeefStew"
        }
    ]
}

В ответ на пакетную вставку возвращается тип 201 Создано; содержимое возвращённой структуры указывает на успех или ошибку для каждого документа.

Возвращённая структура из приведённого выше примера содержит список созданных документов, здесь — сочетание их идентификаторов и идентификаторов ревизий:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 215
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:10:39 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "FishStew",
        "ok": true,
        "rev": "1-6a466d5dfda05e613ba97bd737829d67"
    },
    {
        "id": "LambStew",
        "ok": true,
        "rev": "1-648f1b989d52b8e43f05aa877092cc7c"
    },
    {
        "id": "00a271787f89c0ef2e10e88a0c0003f0",
        "ok": true,
        "rev": "1-e4602845fc4c99674f50b1d5a804fdfa"
    }
]

Подробное описание семантики и структуры возвращаемого JSON см. в разделе Семантика транзакций при пакетной обработке документов. Конфликты и ошибки проверки при пакетном обновлении документов необходимо обрабатывать отдельно; см. раздел Проверка документов при пакетной обработке и ошибки конфликтов.

Пакетное обновление документов

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

Например, можно отправить следующий запрос:

POST /recipes/_bulk_docs HTTP/1.1
Accept: application/json
Content-Length: 464
Content-Type: application/json
Host: localhost:5984

{
    "docs": [
        {
            "_id": "FishStew",
            "_rev": "1-6a466d5dfda05e613ba97bd737829d67",
            "servings": 4,
            "subtitle": "Delicious with freshly baked bread",
            "title": "FishStew"
        },
        {
            "_id": "LambStew",
            "_rev": "1-648f1b989d52b8e43f05aa877092cc7c",
            "servings": 6,
            "subtitle": "Serve with a whole meal scone topping",
            "title": "LambStew"
        },
        {
            "_id": "BeefStew",
            "_rev": "1-e4602845fc4c99674f50b1d5a804fdfa",
            "servings": 8,
            "subtitle": "Hand-made dumplings make a great accompaniment",
            "title": "BeefStew"
        }
    ]
}

Возвращённая структура содержит JSON обновлённых документов с информацией о новых ревизиях и идентификаторах:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 215
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:10:39 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "FishStew",
        "ok": true,
        "rev": "2-2bff94179917f1dec7cd7f0209066fb8"
    },
    {
        "id": "LambStew",
        "ok": true,
        "rev": "2-6a7aae7ac481aa98a2042718d09843c4"
    },
    {
        "id": "BeefStew",
        "ok": true,
        "rev": "2-9801936a42f06a16f16c30027980d96f"
    }
]

Во время пакетного обновления можно удалить документы, добавив поле _deleted со значением true для каждой пары идентификатора документа и ревизии в отправляемой структуре JSON.

В ответ на пакетную вставку возвращается тип 201 Создано; содержимое возвращённой структуры указывает на успех или ошибку для каждого документа.

Содержимое и структура возвращаемого JSON зависят от семантики транзакций, используемой для пакетного обновления; дополнительную информацию см. в разделе Семантика транзакций при пакетной обработке документов. Конфликты и ошибки проверки при пакетном обновлении документов необходимо обрабатывать отдельно; см. раздел Проверка документов при пакетной обработке и ошибки конфликтов.

Семантика транзакций при пакетной обработке документов

Операции пакетной обработки документов неатомарны. Это означает, что CouchDB не гарантирует сохранение какого-либо отдельного документа, включённого в пакетное обновление (или вставку), после отправки запроса. В ответе будет содержаться список документов, успешно вставленных или обновлённых в ходе операции. В случае сбоя некоторые документы могут быть успешно сохранены, а остальные — потеряны.

В структуре ответа будет указано, был ли документ обновлён: для этого передаётся новый параметр _rev, указывающий на создание новой ревизии документа. Если обновление не удалось, будет возвращён error типа conflict. Например:

[
    {
        "id" : "FishStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    },
    {
        "id" : "LambStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    },
    {
        "id" : "BeefStew",
        "error" : "conflict",
        "reason" : "Document update conflict."
    }
]

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

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

Проверка документов при пакетной обработке и ошибки конфликтов

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

Если документ (или ревизия документа) не был корректно сохранён в базе данных из-за ошибки, проверьте поле error, чтобы определить тип ошибки и необходимые действия. Возможны следующие типы ошибок:

  • conflict

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

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

  • forbidden

    Записи с этим типом ошибки указывают на то, что процедура проверки, применённая к документу при отправке, вернула ошибку.

    Например, если ваша процедура проверки содержит следующий код:

    throw({forbidden: 'invalid recipe ingredient'});

    Возвращённый ответ с ошибкой будет выглядеть так:

    HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 80
Content-Type: application/json
Date: Sat, 26 Oct 2013 00:05:17 GMT
Server: CouchDB (Erlang OTP)

[
    {
        "id": "LambStew",
        "error": "forbidden",
        "reason": "invalid recipe ingredient"
    }
]

Copyright © 2025 The Apache Software Foundation — Licensed under the Apache License 2.0
https://docs.couchdb.org/en/3.5.1/api/database/bulk-api.html

Spec-Zone.ru

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