/{db}/_purge

POST /{db}/_purge

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

Запрос на очистку должен содержать идентификаторы документов, а для каждого идентификатора документа — одну или несколько ревизий, которые необходимо очистить. Документы могли быть удалены ранее, но это необязательно. Ревизии должны быть конечными.

Ответ будет содержать список успешно очищенных идентификаторов документов и ревизий.

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

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

• object – Соответствие идентификатора документа списку ревизий для очистки

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

• purge_seq (string) – Строка последовательности очистки

• purged (object) – Соответствие идентификатора документа списку очищенных ревизий

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

• 201 Created – Запрос успешно выполнен

• 202 Accepted – Запрос принят и успешно выполнен как минимум на одной реплике, но кворум не достигнут.

• 400 Bad Request – Недопустимое имя базы данных или полезная нагрузка JSON

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

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

• 415 Unsupported Media Type – Недопустимое значение Content-Type

• 500 Internal Server Error – Внутренняя ошибка сервера или превышено время ожидания

Запрос:

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

{
    "c6114c65e295552ab1019e2b046b10e": [
        "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
        "3-c50a32451890a3f1c3e423334cc92745"
    ]
}

Ответ:

HTTP/1.1 201 Created
Cache-Control: must-revalidate
Content-Length: 107
Content-Type: application/json
Date: Fri, 02 Jun 2017 18:55:54 GMT
Server: CouchDB/2.0.0-2ccd4bf (Erlang OTP/18)

{
  "purge_seq": null,
  "purged": {
    "c6114c65e295552ab1019e2b046b10e": [
        "3-c50a32451890a3f1c3e423334cc92745"
      ]
  }
}

Например, если имеется приведённое выше дерево очистки и отправлен приведённый выше запрос на очистку, весь документ будет очищен, поскольку он содержит только одну ветвь с конечной ревизией 3-c50a32451890a3f1c3e423334cc92745, которая будет очищена. В результате этой операции очистки документ с _id:c6114c65e295552ab1019e2b046b10e будет полностью удалён из b+-дерева документов и b+-дерева последовательностей базы данных. Он будет недоступен через конечные точки _all_docs или _changes, как если бы этот документ никогда не существовал. Кроме того, в результате операции очистки значения purge_seq и update_seq базы данных увеличатся.

Обратите внимание, что ревизия 3-b06fcd1c1c9e0ec7c480ee8aa467bf3b была проигнорирована. В запросе на очистку игнорируются уже очищенные ревизии и не конечные ревизии.

Если документ имеет две конфликтующие ревизии со следующей историей ревизий:

приведённый выше запрос на очистку очистит только одну ветвь, оставив в дереве ревизий документа только одну ветвь:

В результате этой операции очистки обновлённая версия документа станет доступна в _all_docs и _changes, а в _changes будет создана новая запись. Значения purge_seq и update_seq базы данных увеличатся.

/{db}/_purged_infos

GET /{db}/_purged_infos

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

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

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

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

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

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

Запрос:

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

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 75
Content-Type: application/json
Date: Thu, 24 Aug 2023 20:56:06 GMT
Server: CouchDB (Erlang/OTP)

{
  "purged_infos": [
    {
      "id": "doc_id",
      "revs": [
        "1-85cfcb946ba8fea03ba81ec38a7a9998",
        "2-c6548393a891f2cec9c7755832ff9d6f"
      ]
    }
  ]
}

/{db}/_purged_infos_limit

GET /{db}/_purged_infos_limit

Возвращает текущее значение настройки purged_infos_limit (лимит очищенных документов) — максимальное число записей об исторических операциях очистки (идентификаторы очищенных документов и их ревизии), которые могут храниться в базе данных.

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

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

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

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

Запрос:

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

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 5
Content-Type: application/json
Date: Wed, 14 Jun 2017 14:43:42 GMT
Server: CouchDB (Erlang/OTP)

1000

PUT /{db}/_purged_infos_limit

Устанавливает максимальное число операций очистки (запрошенные идентификаторы очищенных документов и их ревизии), сведения о которых будут отслеживаться в базе данных даже после компактизации. Чтобы задать лимит очищенных документов для базы данных, передайте в теле запроса целое число — желаемое значение лимита.

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

Этот запрос задаёт мягкий лимит для хранимых записей об операциях очистки. Во время компактизации CouchDB попытается оставить в базе данных только _purged_infos_limit записей об операциях очистки, однако иногда их число может превысить это значение. Если база данных ещё не завершила синхронизацию операций очистки с активными индексами или активными внутренними репликациями, в ней может временно храниться больше записей об исторических операциях очистки.

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

• ok (boolean) – Состояние операции

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

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

• 400 Bad Request – Недопустимые данные JSON

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

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

Запрос:

PUT /db/_purged_infos_limit HTTP/1.1
Accept: application/json
Content-Length: 4
Content-Type: application/json
Host: localhost:5984

1500

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Wed, 14 Jun 2017 14:45:34 GMT
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}

/{db}/_missing_revs

POST /{db}/_missing_revs

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

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

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

• object – Сопоставление идентификаторов документов со списками ревизий для поиска

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

• missing_revs (object) – Сопоставление идентификаторов документов со списками отсутствующих ревизий

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

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

• 400 Bad Request – Недопустимое имя базы данных или данные JSON

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

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

Запрос:

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

{
    "c6114c65e295552ab1019e2b046b10e": [
        "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b",
        "3-0e871ef78849b0c206091f1a7af6ec41"
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 64
Content-Type: application/json
Date: Mon, 12 Aug 2013 10:53:24 GMT
Server: CouchDB (Erlang/OTP)

{
    "missing_revs":{
        "c6114c65e295552ab1019e2b046b10e": [
            "3-b06fcd1c1c9e0ec7c480ee8aa467bf3b"
        ]
    }
}

/{db}/_revs_diff

POST /{db}/_revs_diff

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

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

Тела и запроса, и ответа представляют собой объекты JSON с идентификаторами документов в качестве ключей, но значения имеют разную структуру:

• В запросе значение — это массив идентификаторов ревизий для данного документа.

• В ответе значение — это объект с ключом missing, значение которого представляет собой список идентификаторов ревизий для данного документа (тех, которые не хранятся в базе данных), и, необязательно, ключом possible_ancestors, значение которого представляет собой массив идентификаторов ревизий, которые могут быть предками отсутствующих ревизий.

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

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

• object – Сопоставление идентификаторов документов со списками ревизий для поиска

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

• missing (array) – Список отсутствующих ревизий указанного документа

• possible_ancestors (array) – Список ревизий, которые могут быть предками указанного документа и его текущей ревизии в запрошенной базе данных

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

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

• 400 Bad Request – Недопустимое имя базы данных или данные JSON

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

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

Запрос:

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

{
    "190f721ca3411be7aa9477db5f948bbb": [
        "3-bb72a7682290f94a985f7afac8b27137",
        "4-10265e5a26d807a3cfa459cf1a82ef2e",
        "5-067a00dff5e02add41819138abb3284d"
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 88
Content-Type: application/json
Date: Mon, 12 Aug 2013 16:56:02 GMT
Server: CouchDB (Erlang/OTP)

{
    "190f721ca3411be7aa9477db5f948bbb": {
        "missing": [
            "3-bb72a7682290f94a985f7afac8b27137",
            "5-067a00dff5e02add41819138abb3284d"
        ],
        "possible_ancestors": [
            "4-10265e5a26d807a3cfa459cf1a82ef2e"
        ]
    }
}

/{db}/_revs_limit

GET /{db}/_revs_limit

Возвращает текущее значение настройки revs_limit (ограничение числа ревизий).

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

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

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

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

Запрос:

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

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 5
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:27:30 GMT
Server: CouchDB (Erlang/OTP)

1000

PUT /{db}/_revs_limit

Задаёт максимальное число ревизий документа, которые будут отслеживаться CouchDB даже после выполнения компактизации. Чтобы задать ограничение числа ревизий для базы данных, передайте в теле запроса скалярное целое число, указывающее нужное значение ограничения.

Параметры:

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

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

• Accept –

  • application/json

  • text/plain

• Content-Type – application/json

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

• Content-Type –

  • application/json

  • text/plain; charset=utf-8

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

• ok (boolean) – Статус операции

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

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

• 400 Bad Request – Недопустимые данные JSON

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

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

Запрос:

PUT /db/_revs_limit HTTP/1.1
Accept: application/json
Content-Length: 5
Content-Type: application/json
Host: localhost:5984

1000

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Mon, 12 Aug 2013 17:47:52 GMT
Server: CouchDB (Erlang/OTP)

{
    "ok": true
}