/{db}/_design/{ddoc}/_view/{view}

Параметры представления

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

• local_seq (boolean): Делает локальные номера последовательности документов доступными функциям map (как свойство документа _local_seq)

• include_design (boolean): Позволяет вызывать функции map для документов проекта, а также для обычных документов

Запросы к представлениям и индексам

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

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

Индексы представлений обновляются инкрементально в следующих случаях:

• В базу данных добавлен новый документ.

• Документ удалён из базы данных.

• Документ в базе данных обновлён.

Индексы представления перестраиваются полностью при изменении его определения. Для этого при обновлении документа проекта создаётся fingerprint определения представления. Если отпечаток изменился, индексы представления перестраиваются полностью. Это гарантирует, что изменения определений представлений отражаются в их индексах.

Поскольку представление обновляется при выполнении запроса к нему, при обращении к нему может возникнуть задержка возврата данных, особенно если в базе данных много документов, а индекс представления ещё не создан. Существует несколько способов уменьшить, но не полностью устранить, эти проблемы. К ним относятся:

• Создайте определение представления (и соответствующие документы проекта) в базе данных до того, как разрешить добавление или обновление документов. Если это сделать, пока к представлению обращаются, индекс можно обновлять инкрементально.

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

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

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

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

Например, чтобы обратиться к существующему устаревшему представлению by_recipe в документе проекта recipes:

http://localhost:5984/recipes/_design/recipes/_view/by_recipe?stale=ok

Обращение к устаревшему представлению:

• Не инициирует перестроение индексов представления, даже если после последнего обращения произошли изменения.

• Возвращает текущую версию индекса представления, если она существует.

• Возвращает пустой набор результатов, если указанный индекс представления не существует.

Также можно использовать значение update_after для параметра stale. В этом случае представление возвращается как устаревшее, но процесс обновления запускается после передачи сведений о представлении клиенту.

Помимо устаревших представлений, можно использовать аргумент запроса update_seq. Этот аргумент позволяет получить сведения о представлении, включая последовательность обновлений базы данных, на основе которой оно было создано. Возвращённое значение можно сравнить с текущей последовательностью обновлений, представленной в сведениях о базе данных (возвращаемых запросом GET /{db}).

Сортировка возвращаемых строк

Каждый элемент возвращаемого массива сортируется с использованием встроенной сортировки UTF-8 в соответствии с содержимым части ключа сгенерированных данных. Основной порядок вывода следующий:

• null

• false

• true

• Числа

• Текст (с учётом регистра, сначала строчные буквы)

• Массивы (в соответствии со значениями каждого элемента, по порядку)

• Объекты (в соответствии со значениями ключей, в порядке ключей)

Запрос:

GET /db/_design/test/_view/sorting HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "8LA1LZPQ37B6R9U8BK9BGQH27"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "dummy-doc",
            "key": null,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": false,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": true,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 0,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 1,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 10,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 42,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "10",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "Hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                1,
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {},
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {
                "foo": "bar"
            },
            "value": null
        }
    ],
    "total_rows": 17
}

Порядок возвращаемых данных представления можно изменить на обратный, задав для значения запроса descending значение true:

Запрос:

GET /db/_design/test/_view/sorting?descending=true HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 10:09:25 GMT
ETag: "Z4N468R15JBT98OM0AMNSR8U"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset": 0,
    "rows": [
        {
            "id": "dummy-doc",
            "key": {
                "foo": "bar"
            },
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": {},
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [
                1,
                2,
                3
            ],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": [],
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "\u043f\u0440\u0438\u0432\u0435\u0442",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "Hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "hello",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": "10",
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 42,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 10,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 1,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": 0,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": true,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": false,
            "value": null
        },
        {
            "id": "dummy-doc",
            "key": null,
            "value": null
        }
    ],
    "total_rows": 17
}

GET http://couchdb:5984/recipes/_design/recipes/_view/by_ingredient?startkey="carrots"&endkey="egg" HTTP/1.1
Accept: application/json

GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey="carrots"&endkey="egg" HTTP/1.1
Accept: application/json
Host: localhost:5984

{
    "error": "query_parse_error",
    "reason": "No rows can match your key range, reverse your start_key and end_key or set descending=false",
    "ref": 3986383855
}

GET /recipes/_design/recipes/_view/by_ingredient?descending=true&startkey="egg"&endkey="carrots" HTTP/1.1
Accept: application/json
Host: localhost:5984

$ curl -X POST http://adm:pass@127.0.0.1:5984/db/_bulk_docs \
       -H 'Content-Type: application/json' \
       -d '{"docs":[{"_id":"a","key":"a","value":1},{"_id":"b","key":"b","value":2},{"_id":"c","key":"c","value":3}]}'
$ curl -X POST http://adm:pass@127.0.0.1:5984/db \
       -H 'Content-Type: application/json' \
       -d '{"_id":"_design/ddoc","views":{"reduce":{"map":"function(doc) { emit(doc.key, doc.value) }","reduce":"_sum"}}}'

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?key="a"'
{"rows":[{"key":null,"value":1}]}

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?keys="[\"a\"]"'
{"rows":[{"key":null,"value":1}]}

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?keys=\["a","b"\]'
{"error":"query_parse_error","reason":"Multi-key fetches for reduce views must use `group=true`"}

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?keys=\["a","c"\]&group=true'
{"rows":[{"key":"a","value":1},{"key":"c","value":3}]}

# start_key=a and end_key=b
$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?key="a"&endkey="b"'
{"rows":[{"key":null,"value":3}]}

# start_key=a and end_key=a
$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?endkey="b"&key="a"'
{"rows":[{"key":null,"value":1}]}

# start_key=a and end_key=a
$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?endkey="b"&keys=\["a"\]'
{"rows":[{"key":null,"value":1}]}

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?endkey="b"&keys=\["a","b"\]'
{"error":"query_parse_error","reason":"Multi-key fetches for reduce views must use `group=true`"}

$ curl http://adm:pass@127.0.0.1:5984/db/_design/ddoc/_view/reduce'?endkey="b"&keys=\["a","b"\]&group=true'
{"error":"query_parse_error","reason":"`keys` is incompatible with `key`, `start_key` and `end_key`"}

Использование ограничений и пропуск строк

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

Однако количество строк результата можно сократить, указав параметр запроса limit. Например, запрос списка рецептов с помощью представления by_title с ограничением в 5 вернёт только 5 записей, хотя всего в представлении 2667 записей:

Запрос:

GET /recipes/_design/recipes/_view/by_title?limit=5 HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "9Q6Q2GZKPH8D5F8L7PB6DBSS9"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "offset" : 0,
    "rows" : [
        {
            "id" : "3-tiersalmonspinachandavocadoterrine",
            "key" : "3-tier salmon, spinach and avocado terrine",
            "value" : [
                null,
                "3-tier salmon, spinach and avocado terrine"
            ]
        },
        {
            "id" : "Aberffrawcake",
            "key" : "Aberffraw cake",
            "value" : [
                null,
                "Aberffraw cake"
            ]
        },
        {
            "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
}

Чтобы пропустить некоторые записи, можно использовать параметр запроса skip:

Запрос:

GET /recipes/_design/recipes/_view/by_title?limit=3&skip=2 HTTP/1.1
Accept: application/json
Host: localhost:5984

Ответ:

HTTP/1.1 200 OK
Cache-Control: must-revalidate
Content-Type: application/json
Date: Wed, 21 Aug 2013 09:14:13 GMT
ETag: "H3G7YZSNIVRRHO5FXPE16NJHN"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

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

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

POST /{db}/_design/{ddoc}/_view/{view}/queries

Выполняет несколько указанных запросов к функции представления из указанного документа проекта.

Параметры:

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

• ddoc – Имя документа проекта

• view – Имя функции представления

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

• Content-Type –

  • application/json

• Accept –

  • application/json

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

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

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

• Content-Type –

  • application/json

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

• Transfer-Encoding – chunked

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

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

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

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

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

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

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

• 404 Not Found – Указанная база данных, документ проекта или представление не найдены

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

Запрос:

POST /recipes/_design/recipes/_view/by_title/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 2016 11:17:07 GMT
ETag: "1H8RGBCK3ABY6ACDM7ZSC30QK"
Server: CouchDB (Erlang/OTP)
Transfer-Encoding: chunked

{
    "results" : [
        {
            "offset": 0,
            "rows": [
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "meatballs",
                    "value": 1
                },
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "spaghetti",
                    "value": 1
                },
                {
                    "id": "SpaghettiWithMeatballs",
                    "key": "tomato sauce",
                    "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
        }
    ]
}