Локальные (нереплицируемые) документы

Интерфейс локальных (нереплицируемых) документов позволяет создавать локальные документы, которые не реплицируются в другие базы данных. Эти документы можно использовать для хранения конфигурации или другой информации, необходимой конкретно для локального экземпляра CouchDB.

Локальные документы имеют следующие ограничения:

Локальные документы не реплицируются в другие базы данных.
Локальные документы не выводятся представлениями или представлением /{db}/_all_docs.

Начиная с CouchDB 2.0, локальные документы можно получить списком с помощью конечной точки /{db}/_local_docs.

Локальные документы можно использовать для хранения конфигурации или другой информации для текущего (локального) экземпляра определённой базы данных.

Ниже приведён список доступных методов и путей URL:

Метод	Путь	Описание
GET, POST	/{db}/_local_docs	Возвращает список всех нереплицируемых документов в базе данных
POST	/{db}/_local_docs/queries	Возвращает список указанных нереплицируемых документов в базе данных
GET	/{db}/_local/{docid}	Возвращает последнюю ревизию нереплицируемого документа
PUT	/{db}/_local/{docid}	Вставляет новую версию нереплицируемого документа
DELETE	/{db}/_local/{docid}	Удаляет нереплицируемый документ
COPY	/{db}/_local/{docid}	Копирует нереплицируемый документ

`/{db}/_local_docs`

GET /{db}/_local_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

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

offset (number) – Смещение, с которого начинается список локальных документов
rows (array) – Массив объектов строк представления. По умолчанию возвращаемая информация содержит только идентификатор и ревизию локального документа.
total_rows (number) – Количество локальных документов в базе данных. Обратите внимание: это не количество строк, возвращённых фактическим запросом.
update_seq (number) – Текущая последовательность обновлений базы данных

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

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

Запрос:

GET /db/_local_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
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": null,
    "rows": [
        {
            "id": "_local/localdoc01",
            "key": "_local/localdoc01",
            "value": {
                "rev": "0-1"
            }
        },
        {
            "id": "_local/localdoc02",
            "key": "_local/localdoc02",
            "value": {
                "rev": "0-1"
            }
        },
        {
            "id": "_local/localdoc03",
            "key": "_local/localdoc03",
            "value": {
                "rev": "0-1"
            }
        },
        {
            "id": "_local/localdoc04",
            "key": "_local/localdoc04",
            "value": {
                "rev": "0-1"
            }
        },
        {
            "id": "_local/localdoc05",
            "key": "_local/localdoc05",
            "value": {
                "rev": "0-1"
            }
        }
    ],
    "total_rows": null
}

POST /{db}/_local_docs

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

Параметры:

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

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

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

Запрос:

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

{
    "keys" : [
        "_local/localdoc02",
        "_local/localdoc05"
    ]
}

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

Ответ:

{
    "total_rows" : null,
    "rows" : [
        {
            "value" : {
                "rev" : "0-1"
            },
            "id" : "_local/localdoc02",
            "key" : "_local/localdoc02"
        },
        {
            "value" : {
                "rev" : "0-1"
            },
            "id" : "_local/localdoc05",
            "key" : "_local/localdoc05"
        }
    ],
    "offset" : null
}

`/{db}/_local_docs/queries`

POST /{db}/_local_docs/queries

Запрос с указанными keys возвращает только локальные документы. Можно также сочетать keys с другими параметрами запроса, такими как limit и skip.

Параметры:

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

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

Content-Type –
- application/json
Accept –
- application/json

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

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

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

Content-Type –
- application/json
- text/plain; charset=utf-8
Transfer-Encoding – chunked

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

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

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

200 OK – Запрос успешно выполнен
400 Bad Request – Недопустимый запрос
401 Unauthorized – Неавторизованный запрос к защищённому API
403 Forbidden – Недостаточно прав / Слишком много запросов с недействительными учётными данными
404 Not Found – Указанная база данных отсутствует
500 Internal Server Error – Ошибка выполнения запроса

Запрос:

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

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

Ответ:

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

{
    "results": [
        {
            "total_rows": null,
            "offset": null,
            "rows": [
                {
                    "id": "_local/localdoc05",
                    "key": "_local/localdoc05",
                    "value": {
                      "rev": "0-1"
                    }
                },
                {
                    "key": "_local/not-exist",
                    "error": "not_found"
                }
            ]
        },
        {
            "total_rows": null,
            "offset": null,
            "rows": [
                {
                  "id": "_local/localdoc04",
                  "key": "_local/localdoc04",
                  "value": {
                      "rev": "0-1"
                    }
                }
            ]
        }
    ]
}

Примечание

Как и _design_docs/queries, /{db}/_local_docs/queries возвращает только локальные документы. Отличие заключается в том, что total_rows и offset всегда равны null.

`/{db}/_local/{docid}`

GET /{db}/_local/{docid}

Получает указанный локальный документ. Семантика идентична получению стандартного документа из указанной базы данных, за исключением того, что документ не реплицируется. См. GET /{db}/{docid}.

Параметры:

db – Имя базы данных
docid – Идентификатор документа

PUT /{db}/_local/{docid}

Сохраняет указанный локальный документ. Семантика идентична сохранению стандартного документа в указанной базе данных, за исключением того, что документ не реплицируется. См. PUT /{db}/{docid}.

Параметры:

db – Имя базы данных
docid – Идентификатор документа

DELETE /{db}/_local/{docid}: Удаляет указанный локальный документ. Семантика идентична удалению стандартного документа из указанной базы данных, за исключением того, что документ не реплицируется. См. DELETE /{db}/{docid}.

COPY /{db}/_local/{docid}: Копирует указанный локальный документ. Семантика идентична копированию стандартного документа в указанной базе данных, за исключением того, что документ не реплицируется. См. COPY /{db}/{docid}.