/{db}/_find

POST /{db}/_find

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

Параметры:

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

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

• Content-Type –

  • application/json

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

• selector (object) – Объект JSON с критериями выбора документов. Дополнительные сведения см. в разделе о синтаксисе селектора. Обязательно

• limit (number) – Максимальное количество возвращаемых результатов. Значение по умолчанию: 25. Необязательно

• skip (number) – Пропустить первые «n» результатов, где «n» — указанное значение. Необязательно

• sort (array) – Массив JSON, соответствующий синтаксису сортировки. Необязательно

• fields (array) – Массив JSON с указанием полей каждого объекта, которые следует вернуть. Если параметр опущен, возвращается весь объект. Дополнительные сведения см. в разделе о фильтрации полей. Необязательно

• use_index (string|array) – Запросить использование определённого индекса. Указывается как "<design_document>" или ["<design_document>", "<index_name>"]. Фактическое использование индекса не гарантируется: если индекс не подходит для селектора, выполняется попытка перейти к подходящему индексу. Поэтому этот параметр скорее является подсказкой. Если происходит переключение, подробности указываются в поле warning ответа. Необязательно

• allow_fallback (boolean) – Указывает, разрешено ли переключение на другой подходящий индекс. Это может произойти при выполнении запроса с индексом, указанным в use_index, который признан непригодным, или когда из-за отсутствия индексов, подходящих для запроса, будет выбран только встроенный индекс _all_docs. Отключение этой логики переключения приводит к немедленной ошибке конечной точки в таких случаях. Значение по умолчанию: true. Необязательно

• conflicts (boolean) – Включать документы с конфликтами, если true. Предназначено для быстрого поиска документов с конфликтами без индекса или представления. Значение по умолчанию: false. Необязательно

• r (number) – Кворум чтения, необходимый для получения результата. По умолчанию равен 1; в этом случае возвращается документ, найденный в индексе. Если задано большее значение, каждый документ считывается как минимум с такого количества реплик, прежде чем будет включён в результаты. Это, вероятно, займёт больше времени, чем использование только документа, хранящегося локально вместе с индексом. Необязательно, по умолчанию: 1

• bookmark (string) – Строка, позволяющая указать нужную страницу результатов. Используется для постраничного просмотра наборов результатов. Каждый запрос возвращает непрозрачную строку в ключе bookmark, которую затем можно передать в запросе для получения следующей страницы результатов. Если между запросами изменится какая-либо часть запроса селектора, результаты не определены. Необязательно, по умолчанию: null

• update (boolean) – Следует ли обновить индекс перед возвратом результата. Значение по умолчанию: true. Необязательно

• stable (boolean) – Следует ли возвращать результаты представления из «стабильного» набора шардов. Необязательно

• stale (string) – Сочетание параметров update=false и stable=true. Возможные значения: "ok", false (по умолчанию). Необязательно Обратите внимание, что этот параметр устарел. Вместо него используйте stable и update. Дополнительные сведения см. в разделе Создание представлений.

• execution_stats (boolean) – Включать статистику выполнения в ответ на запрос. Необязательно, по умолчанию: false

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

• Content-Type –

  • application/json

• Transfer-Encoding – chunked

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

• docs (object) – Массив документов, соответствующих поисковому запросу. Для каждого найденного документа перечислены поля, указанные в части тела запроса fields, а также их значения.

• warning (string) – Предупреждения о выполнении

• execution_stats (object) – Статистика выполнения

• bookmark (string) – Непрозрачная строка для постраничного просмотра. Сведения об использовании см. в поле bookmark запроса (выше).

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

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

• 400 Bad Request – Некорректный запрос

• 401 Unauthorized – Требуется разрешение на чтение

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

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

• 500 Internal Server Error – Ошибка выполнения запроса

Значения limit и skip работают именно так, как можно ожидать. Хотя skip существует, он не предназначен для постраничного просмотра. Причина в том, что функция bookmark работает эффективнее.

Запрос:

Пример тела запроса для поиска документов с использованием индекса:

POST /movies/_find HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 168
Host: localhost:5984

{
    "selector": {
        "year": {"$gt": 2010}
    },
    "fields": ["_id", "_rev", "year", "title"],
    "sort": [{"year": "asc"}],
    "limit": 2,
    "skip": 0,
    "execution_stats": true
}

Ответ:

Пример ответа при поиске документов с использованием индекса:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 01 Sep 2016 15:41:53 GMT
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked

{
    "docs": [
        {
            "_id": "176694",
            "_rev": "1-54f8e950cc338d2385d9b0cda2fd918e",
            "year": 2011,
            "title": "The Tragedy of Man"
        },
        {
            "_id": "780504",
            "_rev": "1-5f14bab1a1e9ac3ebdf85905f47fb084",
            "year": 2011,
            "title": "Drive"
        }
    ],
    "execution_stats": {
        "total_keys_examined": 200,
        "total_docs_examined": 200,
        "total_quorum_docs_examined": 0,
        "results_returned": 2,
        "execution_time_ms": 5.52
    }
}

{
    "<fieldname>:string": "asc"
}

{
    "selector": {"Actor_name": "Robert De Niro"},
    "sort": [{"Actor_name": "asc"}, {"Movie_runtime": "asc"}]
}

{
    "selector": { "Actor_name": "Robert De Niro" },
    "fields": ["Actor_name", "Movie_year", "_id", "_rev"]
}

/{db}/_index

Mango — декларативный язык запросов JSON для баз данных CouchDB. Mango поддерживает несколько типов индексов, начиная со встроенного первичного индекса. Индексы Mango типа json создаются с помощью представлений MapReduce.

POST /{db}/_index

Создать новый индекс в базе данных

Параметры:

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

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

• Content-Type –

  • application/json

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

• index (object) – Объект JSON с описанием создаваемого индекса. (Зависит от типа индекса; см. раздел Индексы.)

• ddoc (string) – Имя проектного документа, в котором будет создан индекс. По умолчанию каждый индекс создаётся в отдельном проектном документе. Для повышения эффективности индексы можно объединять в проектные документы. Однако изменение одного индекса в проектном документе сделает недействительными все остальные индексы в этом же документе (аналогично представлениям). Необязательно

• name (string) – Имя индекса. Если имя не указано, оно будет создано автоматически. Необязательно

• type (string) – Может принимать значения "json", "text" (для clouseau) или "nouveau". По умолчанию используется "json". Текстовые индексы и индексы Nouveau относятся к соответствующим функциям и доступны только при их установке. Необязательно

• partitioned (boolean) – Определяет, является ли индекс JSON секционированным или глобальным. Значение по умолчанию для partitioned — свойство partitioned базы данных. Чтобы создать глобальный индекс в секционированной базе данных, укажите false для поля "partitioned". Если указать true для поля "partitioned" в несекционированной базе данных, возникнет ошибка.

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

• Content-Type –

  • application/json

• Transfer-Encoding – chunked

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

• result (string) – Флаг, указывающий, был ли индекс создан или уже существовал. Может принимать значения "created" или "exists".

• id (string) – Идентификатор проектного документа, в котором был создан индекс.

• name (string) – Имя созданного индекса.

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

• 200 OK – Индекс успешно создан или уже существует

• 400 Bad Request – Некорректный запрос

• 401 Unauthorized – Требуется разрешение администратора

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

• 404 Not Found – База данных не найдена

• 500 Internal Server Error – Ошибка выполнения

Пример создания нового индекса для поля с именем foo:

Запрос:

POST /db/_index HTTP/1.1
Content-Type: application/json
Content-Length: 116
Host: localhost:5984

{
    "index": {
        "fields": ["foo"]
    },
    "name" : "foo-index",
    "type" : "json"
}

Возвращённый JSON подтверждает, что индекс создан:

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 96
Content-Type: application/json
Date: Thu, 01 Sep 2016 18:17:48 GMT
Server: CouchDB (Erlang OTP/18)

{
    "result":"created",
    "id":"_design/a5f4711fc9448864a13c81dc71e660b524d7410c",
    "name":"foo-index"
}

Пример создания индекса с использованием всех доступных параметров запроса:

Запрос:

POST /db/_index HTTP/1.1
Content-Type: application/json
Content-Length: 396
Host: localhost:5984

{
    "index": {
        "partial_filter_selector": {
            "year": {
                "$gt": 2010
            },
            "limit": 10,
            "skip": 0
        },
        "fields": [
            "_id",
            "_rev",
            "year",
            "title"
        ]
    },
    "ddoc": "example-ddoc",
    "name": "example-index",
    "type": "json",
    "partitioned": false
}

По умолчанию индекс JSON включает все документы, в которых присутствуют индексируемые поля, в том числе поля со значениями null.

GET /{db}/_index

При выполнении запроса GET к /{db}/_index возвращается список всех индексов базы данных. Помимо сведений, доступных через этот API, индексы также хранятся в проектных документах как представления. Проектные документы — это обычные документы, идентификаторы которых начинаются с _design/. Проектные документы можно получать и изменять так же, как любые другие документы, однако при использовании Mango в этом нет необходимости.

Параметры:

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

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

• Content-Type –

  • application/json

• Transfer-Encoding – chunked

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

• total_rows (number) – Количество индексов.

• indexes (array) – Массив описаний индексов (см. раздел Определения индексов).

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

• 200 OK – Успешно

• 400 Bad Request – Некорректный запрос

• 401 Unauthorized – Требуется разрешение на чтение

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

• 500 Internal Server Error – Ошибка выполнения

Запрос:

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

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 238
Content-Type: application/json
Date: Thu, 01 Sep 2016 18:17:48 GMT
Server: CouchDB (Erlang OTP/18)

{
    "total_rows": 2,
    "indexes": [
    {
        "ddoc": null,
        "name": "_all_docs",
        "type": "special",
        "def": {
            "fields": [
                {
                    "_id": "asc"
                }
            ]
        }
    },
    {
        "ddoc": "_design/a5f4711fc9448864a13c81dc71e660b524d7410c",
        "name": "foo-index",
        "partitioned": false,
        "type": "json",
        "def": {
            "fields": [
                {
                    "foo": "asc"
                }
            ]
        }
    }
  ]
}

DELETE /{db}/_index/{design_doc}/json/{name}

Параметры:

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

• design_doc – Имя проектного документа. Префикс _design/ указывать не требуется.

• name – Имя индекса.

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

• Content-Type –

  • application/json

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

• ok (string) – Значение “true” означает успешное выполнение.

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

• 200 OK – Успешно

• 400 Bad Request – Некорректный запрос

• 401 Unauthorized – Требуется разрешение на запись

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

• 404 Not Found – Индекс не найден

• 500 Internal Server Error – Ошибка выполнения

Запрос:

DELETE /db/_index/_design/a5f4711fc9448864a13c81dc71e660b524d7410c/json/foo-index HTTP/1.1
Accept: */*
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 12
Content-Type: application/json
Date: Thu, 01 Sep 2016 19:21:40 GMT
Server: CouchDB (Erlang OTP/18)

{
    "ok": true
}

POST /{db}/_index/_bulk_delete

Параметры:

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

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

• Content-Type –

  • application/json

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

• docids (array) – Список имён индексов для удаления.

• w (number) – Кворум записи для каждого удаления. Значение по умолчанию: 2. Необязательно

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

• Content-Type –

  • application/json

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

• success (array) – Массив объектов, описывающих успешное удаление каждого индекса. Ключ id содержит имя индекса, а ok указывает, завершена ли операция.

• fail (array) – Массив объектов с описанием неудачных попыток удаления индексов. Ключ id содержит имя соответствующего индекса, а error описывает причину сбоя.

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

• 200 OK – Успешно

• 400 Bad Request – Некорректный запрос

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

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

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

• 500 Internal Server Error – Ошибка выполнения

Запрос:

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

{
    "docids": [
        "_design/example-ddoc",
        "foo-index",
        "nonexistent-index"
    ]
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Length: 94
Content-Type: application/json
Date: Thu, 01 Sep 2016 19:26:59 GMT
Server: CouchDB (Erlang OTP/18)

{
    "success": [
        {
            "id": "_design/example-ddoc",
            "ok": true
        },
        {
            "id": "foo-index",
            "ok": true
        }
    ],
    "fail": [
        {
            "id": "nonexistent-index",
            "error": "not_found"
        }
    ]
}

/{db}/_explain

POST /{db}/_explain

Показывает, какой индекс используется запросом. Параметры такие же, как у _find.

Параметры:

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

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

• Content-Type –

  • application/json

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

• Content-Type –

  • application/json

• Transfer-Encoding – chunked

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

• covering (boolean) – Указывает, можно ли ответить на запрос, используя только данные, хранящиеся в индексе. Если true, документы не извлекаются, что ускоряет ответ.

• dbname (string) – Имя базы данных.

• index (object) – Индекс, использованный для выполнения запроса.

• selector (object) – Использованный селектор запроса.

• opts (object) – Использованные параметры запроса.

• mrargs (object) – Аргументы, переданные базовому представлению.

• limit (number) – Использованное значение параметра limit.

• skip (number) – Использованное значение параметра skip.

• fields (array) – Поля, которые должен вернуть запрос. Значение [] здесь означает все поля, поскольку в этом случае проекция не выполняется.

• partitioned (boolean) – Разделена ли база данных на секции.

• index_candidates (array) – Список всех найденных, но не выбранных для выполнения запроса индексов. Подробности см. в разделе о выборе индекса ниже.

• selector_hints (object) – Дополнительные сведения о селекторе, помогающие оценить его пригодность.

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

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

• 400 Bad Request – Некорректный запрос

• 401 Unauthorized – Требуется разрешение на чтение

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

• 500 Internal Server Error – Ошибка выполнения

Запрос:

POST /movies/_explain HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 168
Host: localhost:5984

{
    "selector": {
        "year": {"$gt": 2010}
    },
    "fields": ["_id", "_rev", "year", "title"],
    "sort": [{"year": "asc"}],
    "limit": 2,
    "skip": 0
}

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Thu, 01 Sep 2016 15:41:53 GMT
Server: CouchDB (Erlang OTP)
Transfer-Encoding: chunked

{
    "dbname": "movies",
    "index": {
        "ddoc": "_design/0d61d9177426b1e2aa8d0fe732ec6e506f5d443c",
        "name": "0d61d9177426b1e2aa8d0fe732ec6e506f5d443c",
        "type": "json",
        "partitioned": false,
        "def": {
            "fields": [
                {
                    "year": "asc"
                }
            ]
        }
    },
    "partitioned": false,
    "selector": {
        "year": {
            "$gt": 2010
        }
    },
    "opts": {
        "use_index": [],
        "bookmark": "nil",
        "limit": 2,
        "skip": 0,
        "sort": {},
        "fields": [
            "_id",
            "_rev",
            "year",
            "title"
        ],
        "partition": "",
        "r": 1,
        "conflicts": false,
        "stale": false,
        "update": true,
        "stable": false,
        "execution_stats": false,
        "allow_fallback": true
    },
    "limit": 2,
    "skip": 0,
    "fields": [
        "_id",
        "_rev",
        "year",
        "title"
    ],
    "mrargs": {
        "include_docs": true,
        "view_type": "map",
        "reduce": false,
        "partition": null,
        "start_key": [
            2010
        ],
        "end_key": [
            "<MAX>"
        ],
        "direction": "fwd",
        "stable": false,
        "update": true,
        "conflicts": "undefined"
    },
    "covering": false
    "index_candidates": [
        {
            "index": {
                "ddoc": null,
                "name": "_all_docs",
                "type": "special",
                "def": {
                    "fields": [
                        {
                            "_id": "asc"
                        }
                    ]
                }
            },
            "analysis": {
                "usable": true,
                "reasons": [
                    {
                        "name": "unfavored_type"
                    }
                ],
                "ranking": 1,
                "covering": null
            }
        }
    ],
    "selector_hints": [
        {
            "type": "json",
            "indexable_fields": [
                "year"
            ],
            "unindexable_fields": []
        }
    ]
}

Выбор индекса

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

Примечание

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

Примечание

Конечные точки _explain и _find используют одну и ту же логику выбора индекса. Однако _explain предоставляет более подробную информацию, поэтому его можно использовать для моделирования и исследования. В выводе сведения об исключении индексов содержатся в поле analysis объектов JSON под index_candidates. В analysis в поле reasons указана точная причина. Каждой причине соответствует определенный код, который будет упомянут в соответствующих подразделах ниже.

Выбор индекса выполняется в несколько этапов.

Сначала собираются все индексы базы данных. В результат всегда входит специальная сущность all docs — первичный индекс по полю _id. Он используется как запасной вариант, если подходящих индексов не найдено, однако его применение не рекомендуется по соображениям производительности.

На следующем этапе исключаются частичные индексы, если только они не указаны в поле use_index объекта запроса.

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

Оставшиеся индексы проходят ряд проверок на пригодность.

Для каждой проверки пригодности предусмотрен собственный код причины. Код field_mismatch используется, если поля индекса не соответствуют полям селектора. Код sort_order_mismatch означает, что запрошенная сортировка не соответствует индексу. Эти проверки зависят от типа индекса.

• "special": индекс пригоден, если в запросе не указан sort или если sort указано только для _id.

• "json": селектор не должен запрашивать полнотекстовый поиск произвольного вида с помощью оператора $text. В противном случае возвращается код причины needs_text_search.

  Все поля индекса должны упоминаться в selector или sort запроса.

  Любой sort, указанный в запросе, должен соответствовать порядку полей в индексе.

• "text": индекс должен содержать поля, на которые ссылается "selector" или "sort" запроса.

  Индексы "text" не работают с пустыми селекторами, и в ответ на такой запрос возвращается код причины empty_selector.

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

Для разных типов индексов существует естественный порядок предпочтения: "json", "text", а затем "special". Пригодные индексы группируются по типам в этом порядке, и поиск сужается до элементов первой группы. Таким образом, даже если имеется индекс "text", подходящий для селектора, он может быть исключен, если найден индекс "json" с подходящими полями. Всем индексам, исключенным на этом этапе, присваивается код причины unfavored_type.

Для каждой базы данных может существовать только один индекс "text" и один индекс "special", поэтому в этих случаях выбор завершается на этом этапе. Для индексов "json" выполняется дополнительный этап, на котором выбирается оптимальный индекс.

Планировщик запросов анализирует селектор и находит индекс, поля и операторы которого наиболее точно соответствуют использованным в запросе. Это обозначается кодом причины less_overlap. Если подходят два или более индекса типа "json", предпочтение отдается индексу с наименьшим количеством полей. Это отмечается кодом причины too_many_fields. Если после этого остается два или более индекса-кандидата, выбирается индекс с первым по алфавиту именем. Это отражается кодом причины alphabetically_comes_after.

Код причины	Тип индекса	Описание
alphabetically_comes_after	json	Существует другой подходящий индекс, имя которого предшествует имени этого индекса.
empty_selector	text	Индексы "text" не поддерживают запросы с пустыми селекторами.
excluded_by_user	any	Для указания индекса вручную использовался use_index.
field_mismatch	any	Поля в "selector" запроса не соответствуют полям, доступным в индексе.
is_partial	json, text	Частичные индексы можно выбрать только вручную.
less_overlap	json	В индексах имеется индекс с более подходящим набором полей для запроса.
needs_text_search	json	Для использования оператора $text требуется индекс "text".
scope_mismatch	json	Область действия запроса не совпадает с областью действия индекса.
sort_order_mismatch	json, special	Поля в "sort" запроса не соответствуют полям, доступным в индексе.
too_many_fields	json	В индексе больше полей, чем в выбранном индексе.
unfavored_type	any	Тип индекса не является предпочтительным.

В выводе _explain также можно найти дополнительную информацию об индексах-кандидатах в объекте analysis.

• Атрибут ranking (number) задает приблизительный порядок элементов списка, который можно использовать для их упорядочивания. Это положительное целое число; чем оно больше, тем ниже индекс находится в очереди. Выбранный индекс всегда имеет ранг 0, а все остальные располагаются после него. Ранг отражает итоговую позицию данного индекса-кандидата в описанном выше отборе.

• Атрибут usable (Boolean) указывает, пригоден ли индекс. Это позволяет разделить индексы-кандидаты по их пригодности для данного селектора.

• Атрибут covering (Boolean) указывает, является ли индекс покрывающим. Это свойство вычисляется только для индексов "json", а во всех остальных случаях имеет значение null.