Проектные документы
В этом разделе мы покажем, как писать проектные документы, используя встроенный сервер запросов JavaScript.
Но прежде чем приступить к созданию первого документа, давайте рассмотрим список распространённых объектов, которые будут использоваться в ходе работы с кодом: мы будем широко применять их в каждой функции.
Создание и структура
Проектные документы содержат такие функции, как функции представлений и обновления. Эти функции выполняются по запросу.
Проектные документы обозначаются полем id в формате _design/{name}. Их структура соответствует приведённому ниже примеру.
Пример:
{
"_id": "_design/example",
"views": {
"view-number-one": {
"map": "function (doc) {/* function code here - see below */}"
},
"view-number-two": {
"map": "function (doc) {/* function code here - see below */}",
"reduce": "function (keys, values, rereduce) {/* function code here - see below */}"
}
},
"updates": {
"updatefun1": "function(doc,req) {/* function code here - see below */}",
"updatefun2": "function(doc,req) {/* function code here - see below */}"
},
"filters": {
"filterfunction1": "function(doc, req){ /* function code here - see below */ }"
},
"validate_doc_update": "function(newDoc, oldDoc, userCtx, secObj) { /* function code here - see below */ }",
"language": "javascript"
} Как видите, проектный документ может включать несколько функций одного типа. В примере определены два представления, каждое из которых содержит функцию map, а одно из них — функцию reduce. Также определены две функции обновления и одна функция фильтра. Функция проверки обновления документа является особым случаем: каждый проектный документ может содержать не более одной такой функции.
Функции представлений
Представления — основной инструмент для запросов к базам данных CouchDB и создания по ним отчётов.
Функции map
-
mapfun(doc) -
- Аргументы:
-
doc — обрабатываемый документ
Функции map принимают в качестве аргумента один документ и (необязательно) создают пары ключ/значение с помощью emit(), которые сохраняются в представлении.
function (doc) {
if (doc.type === 'post' && doc.tags && Array.isArray(doc.tags)) {
doc.tags.forEach(function (tag) {
emit(tag.toLowerCase(), 1);
});
}
} В этом примере для каждого значения в массиве tags документа с типом post создаётся пара ключ/значение. Обратите внимание: emit() можно вызвать несколько раз для одного документа, поэтому один и тот же документ может быть доступен по нескольким различным ключам.
Также имейте в виду, что каждый документ запечатан, чтобы предотвратить ситуацию, в которой одна функция map изменяет состояние документа, а другая получает его изменённую версию.
Для повышения эффективности документы передаются группе функций map: каждый документ обрабатывается группой функций map из всех представлений связанного проектного документа. Это означает, что если вы запускаете обновление индекса для одного представления в проектном документе, обновятся и все остальные.
Начиная с версии 1.1.0, map поддерживает модули CommonJS и функцию require().
Функции reduce и rereduce
-
redfun(keys, values[, rereduce]) -
- Аргументы:
-
keys — массив пар ключ-документ для результатов соответствующей функции map. Всегда
nullпри выполнении rereduce (имеет значениеtrue).values — массив значений, полученных функцией map.
rereduce — логический флаг, указывающий на выполнение rereduce.
- Возвращает:
-
Сокращает values
Функции reduce принимают два обязательных аргумента — списки ключей и значений, полученные в результате работы соответствующей функции map, — и необязательный третий аргумент, указывающий, активен ли режим rereduce. Rereduce используется для дополнительного списка значений reduce, поэтому при значении true сведения о соответствующих keys отсутствуют (первый аргумент равен null).
Обратите внимание: если результат функции reduce длиннее исходного списка значений, будет выдана ошибка сервера запросов. Однако это поведение можно отключить, установив параметр конфигурации reduce_limit в значение false:
[query_server_config] reduce_limit = false
Отключение reduce_limit может быть полезно для отладки, однако помните, что основная задача функций reduce — сокращать результат map, а не увеличивать его. Как правило, функция reduce должна быстро сходиться к одному значению, которым может быть массив или похожий объект.
Установите reduce_limit в значение log, чтобы представления, которые завершились бы с ошибкой при значении true, вместо этого возвращали результат и записывали предупреждение уровня info.
Встроенные функции reduce
Кроме того, в CouchDB есть набор встроенных функций reduce. Они реализованы на Erlang и выполняются внутри CouchDB, поэтому работают намного быстрее эквивалентных функций JavaScript.
-
_first
Добавлено в версии 3.5.
Возвращает значение первой строки в группе. Например, для представления вида [a,1] : x, [a,2] : y при запросе с помощью group_level=1 будет возвращено [a]
: x.
-
_last
Добавлено в версии 3.5.
Возвращает значение последней строки в группе. Например, для представления вида [a,1] : x, [a,2] : y при запросе с помощью group_level=1 будет возвращено [a]
: y.
-
_top_N
Добавлено в версии 3.5.
Верхние N значений, где N может быть любым числом от 1 до 100 включительно. Например, _top_5 возвращает список из 5 наибольших значений.
-
_bottom_N
Добавлено в версии 3.5.
Нижние N значений, где N может быть любым числом от 1 до 100 включительно. Например, _bottom_10 возвращает список из 10 наименьших значений.
-
_approx_count_distinct
Добавлено в версии 2.2.
Приблизительно подсчитывает количество уникальных ключей в индексе представления с помощью варианта алгоритма HyperLogLog. Этот алгоритм обеспечивает эффективное распараллеливаемое вычисление мощности множества с использованием фиксированного объёма памяти. В CouchDB базовая структура данных настроена на относительную погрешность около 2%.
Поскольку эта функция reduce полностью игнорирует созданные значения, вызов с group=true просто вернёт значение 1 для каждого уникального ключа в представлении. Для ключей-массивов запрос к представлению с указанным group_level вернёт количество уникальных ключей, имеющих общий префикс группы в каждой строке. Алгоритм также учитывает границы startkey и endkey и возвращает количество уникальных ключей в заданном диапазоне ключей.
И последнее замечание о сортировке Unicode: эта функция reduce напрямую использует двоичное представление каждого ключа в индексе как входные данные фильтра HyperLogLog. Поэтому ключи, которые не совпадают побайтно, но считаются равными согласно правилам сортировки Unicode, будут (ошибочно) считаться разными. Таким образом, если таких ключей много, оценка мощности пространства ключей может оказаться завышенной.
-
_count
Подсчитывает количество значений в индексе с заданным ключом. Эту функцию можно реализовать на JavaScript следующим образом:
// could be replaced by _count
function(keys, values, rereduce) {
if (rereduce) {
return sum(values);
} else {
return values.length;
}
} -
_stats
Вычисляет следующие величины для числовых значений, связанных с каждым ключом: sum, min, max, count и sumsqr. Поведение функции _stats зависит от результата функции map. В простейшем случае на этапе map для каждого ключа создаётся одно числовое значение. В этом случае функция _stats эквивалентна следующему коду JavaScript:
// could be replaced by _stats
function(keys, values, rereduce) {
if (rereduce) {
return {
'sum': values.reduce(function(a, b) { return a + b.sum }, 0),
'min': values.reduce(function(a, b) { return Math.min(a, b.min) }, Infinity),
'max': values.reduce(function(a, b) { return Math.max(a, b.max) }, -Infinity),
'count': values.reduce(function(a, b) { return a + b.count }, 0),
'sumsqr': values.reduce(function(a, b) { return a + b.sumsqr }, 0)
}
} else {
return {
'sum': sum(values),
'min': Math.min.apply(null, values),
'max': Math.max.apply(null, values),
'count': values.length,
'sumsqr': (function() {
var sumsqr = 0;
values.forEach(function (value) {
sumsqr += value * value;
});
return sumsqr;
})(),
}
}
} Функция _stats также работает с предварительно агрегированными значениями, полученными на этапе map. Функция map, создающая объект с ключами sum, min, max, count и sumsqr и соответствующими числовыми значениями, может использовать функцию _stats для объединения этих результатов с данными других документов. Созданный объект может содержать и другие ключи (редьюсер их игнорирует); кроме того, в одном представлении можно смешивать обычные числовые значения и предварительно агрегированные объекты, получая корректную объединённую статистику.
Наконец, _stats может обрабатывать пары ключ-значение, в которых каждое значение представляет собой массив чисел или предварительно агрегированных объектов. В этом случае каждое значение, созданное функцией map, должно быть массивом, причём все массивы должны иметь одинаковую длину, поскольку _stats будет вычислять указанные выше статистические величины отдельно для каждого элемента массива. Если нужно вычислить статистику для нескольких значений одного документа, можно либо emit каждое значение в индекс отдельно, либо вычислить статистику для набора значений с помощью приведённого выше примера на JavaScript и создать предварительно агрегированный объект.
-
_sum
В простейшем варианте _sum складывает числовые значения, связанные с каждым ключом, как показано в следующем коде JavaScript:
// could be replaced by _sum
function(keys, values) {
return sum(values);
} Как и _stats, функция _sum обладает рядом дополнительных возможностей. Функция _sum требует, чтобы значениями map были числа, массивы чисел или объекты. Если функция map возвращает массив, _sum вычисляет сумму для каждого элемента массива. Одиночное числовое значение рассматривается как массив из одного элемента, а для недостающих элементов более коротких массивов используются нули, чтобы их длина соответствовала длине самого длинного созданного массива. Например, рассмотрим следующий результат map:
{"total_rows":5, "offset":0, "rows": [
{"id":"id1", "key":"abc", "value": 2},
{"id":"id2", "key":"abc", "value": [3,5,7]},
{"id":"id2", "key":"def", "value": [0,0,0,42]},
{"id":"id2", "key":"ghi", "value": 1},
{"id":"id1", "key":"ghi", "value": 3}
]} Результатом _sum для этих данных без группировки будет:
{"rows": [
{"key":null, "value": [9,5,7,42]}
]} а сгруппированный результат будет таким:
{"rows": [
{"key":"abc", "value": [5,5,7]},
{"key":"def", "value": [0,0,0,42]},
{"key":"ghi", "value": 4
]} Это отличается от поведения функции _stats, для которой все созданные значения должны быть массивами одинаковой длины, если создан хотя бы один массив.
Функция _sum также может рекурсивно обходить созданный объект и вычислять суммы для каждого его поля. Смешивать объекты с другими структурами данных нельзя. Объекты могут быть вложены на произвольную глубину, если значения всех полей являются числами, массивами чисел или объектами.
Примечание
Почему функции reduce не поддерживают модули CommonJS?
Функции map имеют ограниченный доступ к сохранённым модулям через require(), однако для функций reduce такой возможности нет. Причина кроется в особенностях обработки функций map и reduce сервером запросов. Сначала рассмотрим функции map:
CouchDB отправляет серверу запросов все функции map из обрабатываемого проектного документа.
Сервер запросов обрабатывает их по очереди, компилирует и помещает во внутренний стек.
После обработки всех функций map CouchDB по очереди отправляет оставшиеся документы для индексирования.
Сервер запросов получает объект документа и передаёт его каждой функции из стека. Созданные результаты объединяются в один массив и отправляются обратно в CouchDB.
Теперь посмотрим, как обрабатываются функции reduce:
CouchDB отправляет одной командой список доступных функций reduce и список пар ключ-значение, ранее возвращённых функциями map.
Сервер запросов компилирует функции reduce и применяет их к спискам ключей и значений. Результат сокращения отправляется обратно в CouchDB.
Как видите, функции reduce применяются к результатам map за один вызов, тогда как функции map обрабатывают документы по одному. Это означает, что функции map могут предварительно компилировать библиотеки CommonJS и использовать их на протяжении всей обработки представления. Для функций reduce библиотеки пришлось бы компилировать заново при каждом сокращении результатов представления, что ухудшило бы производительность.
Функции отображения
Предупреждение
Функции отображения объявлены устаревшими в CouchDB 3.0 и будут удалены в CouchDB 4.0.
-
showfun(doc, req) -
- Аргументы:
-
doc — обрабатываемый документ; может быть опущен.
req — объект запроса.
- Возвращает:
- Тип возвращаемого значения:
-
объект или строка
Функции отображения используются для представления документов в различных форматах, обычно в виде красиво оформленных HTML-страниц. Их также можно использовать для выполнения серверных функций без предварительно существующего документа.
Пример простой функции отображения:
function(doc, req){
if (doc) {
return "Hello from " + doc._id + "!";
} else {
return "Hello, world!";
}
} Также можно проще возвращать данные в формате JSON:
function(doc, req){
return {
'json': {
'id': doc['_id'],
'rev': doc['_rev']
}
}
} И даже файлы (в этом примере — логотип CouchDB):
function(doc, req){
return {
'headers': {
'Content-Type' : 'image/png',
},
'base64': ''.concat(
'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAMAAAAoLQ9TAAAAsV',
'BMVEUAAAD////////////////////////5ur3rEBn////////////////wDBL/',
'AADuBAe9EB3IEBz/7+//X1/qBQn2AgP/f3/ilpzsDxfpChDtDhXeCA76AQH/v7',
'/84eLyWV/uc3bJPEf/Dw/uw8bRWmP1h4zxSlD6YGHuQ0f6g4XyQkXvCA36MDH6',
'wMH/z8/yAwX64ODeh47BHiv/Ly/20dLQLTj98PDXWmP/Pz//39/wGyJ7Iy9JAA',
'AADHRSTlMAbw8vf08/bz+Pv19jK/W3AAAAg0lEQVR4Xp3LRQ4DQRBD0QqTm4Y5',
'zMxw/4OleiJlHeUtv2X6RbNO1Uqj9g0RMCuQO0vBIg4vMFeOpCWIWmDOw82fZx',
'vaND1c8OG4vrdOqD8YwgpDYDxRgkSm5rwu0nQVBJuMg++pLXZyr5jnc1BaH4GT',
'LvEliY253nA3pVhQqdPt0f/erJkMGMB8xucAAAAASUVORK5CYII=')
}
} Но что делать, если нужно представлять данные в разных форматах с помощью одной функции? В этом случае вам пригодятся функции registerType() и provides():
function(doc, req){
provides('json', function(){
return {'json': doc}
});
provides('html', function(){
return '<pre>' + toJSON(doc) + '</pre>'
})
provides('xml', function(){
return {
'headers': {'Content-Type': 'application/xml'},
'body' : ''.concat(
'<?xml version="1.0" encoding="utf-8"?>\n',
'<doc>',
(function(){
escape = function(s){
return s.replace(/"/g, '"')
.replace(/>/g, '>')
.replace(/</g, '<')
.replace(/&/g, '&');
};
var content = '';
for(var key in doc){
if(!doc.hasOwnProperty(key)) continue;
var value = escape(toJSON(doc[key]));
var key = escape(key);
content += ''.concat(
'<' + key + '>',
value
'</' + key + '>'
)
}
return content;
})(),
'</doc>'
)
}
})
registerType('text-json', 'text/json')
provides('text-json', function(){
return toJSON(doc);
})
} Эта функция может возвращать представление одного и того же объекта документа в форматах html, json, xml или в нашем пользовательском формате text json, применяя одинаковые правила обработки. Вероятно, поставщику xml в нашей функции потребуется дополнительная обработка вложенных объектов и ключей с недопустимыми символами, но общий принцип вы поняли!
См. также
- Руководство по CouchDB:
Функции списков
Предупреждение
Функции списков объявлены устаревшими в CouchDB 3.0 и будут удалены в CouchDB 4.0.
-
listfun(head, req) -
- Аргументы:
-
req — объект запроса.
- Возвращает:
-
Последний фрагмент.
- Тип возвращаемого значения:
-
строка
Если функции отображения используются для настройки представления документов, то функции списков выполняют ту же задачу для результатов функций представлений.
Следующая функция списка форматирует представление и отображает его в виде простой HTML-страницы:
function(head, req){
start({
'headers': {
'Content-Type': 'text/html'
}
});
send('<html><body><table>');
send('<tr><th>ID</th><th>Key</th><th>Value</th></tr>');
while(row = getRow()){
send(''.concat(
'<tr>',
'<td>' + toJSON(row.id) + '</td>',
'<td>' + toJSON(row.key) + '</td>',
'<td>' + toJSON(row.value) + '</td>',
'</tr>'
));
}
send('</table></body></html>');
} Для более привлекательного представления данных, очевидно, можно использовать шаблоны и стили, но это отличная отправная точка. Обратите внимание, что функции registerType() и provides() можно использовать аналогично тому, как они используются в функциях отображения! Однако учтите, что при использовании внутри функции списка provides() ожидает строку в качестве возвращаемого значения, поэтому для установки пользовательских заголовков следует использовать start(), а перед возвратом преобразовать JSON в строку.
См. также
- Руководство по CouchDB:
Функции обновления
-
updatefun(doc, req) -
- Аргументы:
-
doc — обрабатываемый документ.
req — объект запроса
- Возвращает:
-
Массив из двух элементов: первый — документ (обновлённый или новый), который будет сохранён в базе данных. Если первый элемент равен
null, документ не будет сохранён в базе данных. При обновлении существующего документа в нём уже должно быть задано значение_id, а при создании нового документа обязательно задайте для него значение_id— сформированное на основе входных данных или предоставленное вreq.uuid. Второй элемент — ответ, который будет отправлен вызывающей стороне.
Обработчики обновления — это функции, которые клиенты могут вызывать для выполнения серверной логики, создающей или обновляющей документ. Эта возможность подходит для решения различных задач, например, для установки времени последнего изменения на сервере или обновления отдельных полей документа без предварительного получения последней ревизии.
Если запрос к обработчику обновления содержит идентификатор документа в URL, сервер передаст функции последнюю версию этого документа. Любые другие значения, необходимые обработчику обновления, можно передать в теле запроса POST/PUT или в параметрах строки запроса.
Простой пример, демонстрирующий все варианты использования обработчиков обновления:
function(doc, req){
if (!doc){
if ('id' in req && req['id']){
// create new document
return [{'_id': req['id']}, 'New World']
}
// change nothing in database
return [null, 'Empty World']
}
doc['world'] = 'hello';
doc['edited_by'] = req['userCtx']['name']
return [doc, 'Edited World!']
} Функции фильтрации
-
filterfun(doc, req) -
- Аргументы:
-
doc — обрабатываемый документ
req — объект запроса
- Возвращает:
-
Логическое значение:
trueозначает, что doc соответствует правилам фильтрации, аfalse— что не соответствует.
Функции фильтрации во многом похожи на функции отображения и функции списков: они форматируют или фильтруют ленту изменений.
Классические фильтры
По умолчанию лента изменений выдаёт сведения обо всех изменениях документов базы данных. Но если вас интересуют только определённые изменения, обработка всех документов будет неэффективна.
Фильтры — это специальные функции проектного документа, которые позволяют ленте изменений выдавать только документы, соответствующие правилам фильтрации.
Предположим, что наша база данных представляет собой почтовый ящик, и нам нужно обрабатывать только события о новых письмах (документы со статусом new). Наша функция фильтрации будет выглядеть так:
function(doc, req){
// we need only `mail` documents
if (doc.type != 'mail'){
return false;
}
// we're interested only in `new` ones
if (doc.status != 'new'){
return false;
}
return true; // passed!
} Функции фильтрации должны возвращать true, если документ соответствует всем правилам. Теперь, если применить эту функцию к ленте изменений, она будет выдавать только изменения, связанные с «новыми письмами»:
GET /somedatabase/_changes?filter=mailbox/new_mail HTTP/1.1
{"results":[
{"seq":"1-g1AAAAF9eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBMZc4EC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HqQ_kQG3qgSQqnoCqvJYgCRDA5ACKpxPWOUCiMr9hFUegKi8T1jlA4hKkDuzAC2yZRo","id":"df8eca9da37dade42ee4d7aa3401f1dd","changes":[{"rev":"1-c2e0085a21d34fa1cecb6dc26a4ae657"}]},
{"seq":"9-g1AAAAIreJyVkEsKwjAURUMrqCOXoCuQ5MU0OrI70XyppcaRY92J7kR3ojupaSPUUgqWwAu85By4t0AITbJYo5k7aUNSAnyJ_SGFf4gEkvOyLPMsFtHRL8ZKaC1M0v3eq5ALP-X2a0G1xYKhgnONpmenjT04o_v5tOJ3LV5itTES_uP3FX9ppcAACaVsQAo38hNd_eVFt8ZklVljPqSPYLoH06PJhG0Cxq7-yhQcz-B4_fQCjFuqBjjewVF3E9cORoExSrpU_gHBTo5m","id":"df8eca9da37dade42ee4d7aa34024714","changes":[{"rev":"1-29d748a6e87b43db967fe338bcb08d74"}]},
],
"last_seq":"10-g1AAAAIreJyVkEsKwjAURR9tQR25BF2B5GMaHdmdaNIk1FLjyLHuRHeiO9Gd1LQRaimFlsALvOQcuLcAgGkWKpjbs9I4wYSvkDu4cA-BALkoyzLPQhGc3GKSCqWEjrvfexVy6abc_SxQWwzRVHCuYHaxSpuj1aqfTyp-3-IlSrdakmH8oeKvrRSIkJhSNiKFjdyEm7uc6N6YTKo3iI_pw5se3vRsMiETE23WgzJ5x8s73n-9EMYNTUc4Pt5RdxPVDkYJYxR3qfwLwW6OZw"} Обратите внимание: значение last_seq равно 10-.., но мы получили только две записи. Похоже, остальные изменения относятся к документам, не прошедшим фильтр.
Вероятно, нам нужно фильтровать ленту изменений почтового ящика не только по одному статусу. Нас также интересуют статусы вроде «спам», чтобы обновлять эвристические правила спам-фильтра, и «исходящее», чтобы почтовая служба действительно отправляла письма, и так далее. Создавать множество похожих функций, выполняющих одну и ту же работу, — не лучшая идея, поэтому нам нужен динамический фильтр.
Вы могли заметить, что функции фильтрации принимают второй аргумент с именем request. Это позволяет создавать динамические фильтры на основе параметров запроса, контекста пользователя и других данных.
Динамический вариант нашего фильтра выглядит так:
function(doc, req){
// we need only `mail` documents
if (doc.type != 'mail'){
return false;
}
// we're interested only in requested status
if (doc.status != req.query.status){
return false;
}
return true; // passed!
} Теперь мы передали параметр запроса status, чтобы фильтр выбирал только нужные документы:
GET /somedatabase/_changes?filter=mailbox/by_status&status=new HTTP/1.1
{"results":[
{"seq":"1-g1AAAAF9eJzLYWBg4MhgTmHgz8tPSTV0MDQy1zMAQsMcoARTIkOS_P___7MymBMZc4EC7MmJKSmJqWaYynEakaQAJJPsoaYwgE1JM0o1TjQ3T2HgLM1LSU3LzEtNwa3fAaQ_HqQ_kQG3qgSQqnoCqvJYgCRDA5ACKpxPWOUCiMr9hFUegKi8T1jlA4hKkDuzAC2yZRo","id":"df8eca9da37dade42ee4d7aa3401f1dd","changes":[{"rev":"1-c2e0085a21d34fa1cecb6dc26a4ae657"}]},
{"seq":"9-g1AAAAIreJyVkEsKwjAURUMrqCOXoCuQ5MU0OrI70XyppcaRY92J7kR3ojupaSPUUgqWwAu85By4t0AITbJYo5k7aUNSAnyJ_SGFf4gEkvOyLPMsFtHRL8ZKaC1M0v3eq5ALP-X2a0G1xYKhgnONpmenjT04o_v5tOJ3LV5itTES_uP3FX9ppcAACaVsQAo38hNd_eVFt8ZklVljPqSPYLoH06PJhG0Cxq7-yhQcz-B4_fQCjFuqBjjewVF3E9cORoExSrpU_gHBTo5m","id":"df8eca9da37dade42ee4d7aa34024714","changes":[{"rev":"1-29d748a6e87b43db967fe338bcb08d74"}]},
],
"last_seq":"10-g1AAAAIreJyVkEsKwjAURR9tQR25BF2B5GMaHdmdaNIk1FLjyLHuRHeiO9Gd1LQRaimFlsALvOQcuLcAgGkWKpjbs9I4wYSvkDu4cA-BALkoyzLPQhGc3GKSCqWEjrvfexVy6abc_SxQWwzRVHCuYHaxSpuj1aqfTyp-3-IlSrdakmH8oeKvrRSIkJhSNiKFjdyEm7uc6N6YTKo3iI_pw5se3vRsMiETE23WgzJ5x8s73n-9EMYNTUc4Pt5RdxPVDkYJYxR3qfwLwW6OZw"} Поведение фильтра можно легко изменить с помощью:
GET /somedatabase/_changes?filter=mailbox/by_status&status=spam HTTP/1.1
{"results":[
{"seq":"6-g1AAAAIreJyVkM0JwjAYQD9bQT05gk4gaWIaPdlNNL_UUuPJs26im-gmuklMjVClFFoCXyDJe_BSAsA4jxVM7VHpJEswWyC_ktJfRBzEzDlX5DGPDv5gJLlSXKfN560KMfdTbL4W-FgM1oQzpmByskqbvdWqnc8qfvvHCyTXWuBu_K7iz38VCOOUENqjwg79hIvfvOhamQahROoVYn3-I5huwXSvm5BJsTbLTk3B8QiO58-_YMoMkT0cr-BwdRElmFKSNKniDcAcjmM","id":"8960e91220798fc9f9d29d24ed612e0d","changes":[{"rev":"3-cc6ff71af716ddc2ba114967025c0ee0"}]},
],
"last_seq":"10-g1AAAAIreJyVkEsKwjAURR9tQR25BF2B5GMaHdmdaNIk1FLjyLHuRHeiO9Gd1LQRaimFlsALvOQcuLcAgGkWKpjbs9I4wYSvkDu4cA-BALkoyzLPQhGc3GKSCqWEjrvfexVy6abc_SxQWwzRVHCuYHaxSpuj1aqfTyp-3-IlSrdakmH8oeKvrRSIkJhSNiKFjdyEm7uc6N6YTKo3iI_pw5se3vRsMiETE23WgzJ5x8s73n-9EMYNTUc4Pt5RdxPVDkYJYxR3qfwLwW6OZw"} Сочетание фильтров с лентой continuous позволяет создавать мощные событийно-ориентированные системы.
Фильтры представлений
Фильтры представлений работают так же, как описанные выше классические фильтры, с одним небольшим отличием: для фильтрации ленты изменений они используют функцию map представления вместо функции filter. Каждый раз, когда функция map создаёт пару ключ-значение, возвращается изменение. Это позволяет избежать использования функций фильтрации, которые в основном выполняют ту же работу, что и представления.
Чтобы использовать их, просто передайте параметры запроса filter=_view и view=designdoc/viewname в ленту изменений:
GET /somedatabase/_changes?filter=_view&view=dname/viewname HTTP/1.1
Примечание
Поскольку фильтры представлений используют функции map в качестве фильтров, они не могут работать динамически: объект запроса недоступен.
См. также
- Руководство по CouchDB:
Проверка функций обновления документов
-
validatefun(newDoc, oldDoc, userCtx, secObj) -
- Аргументы:
-
newDoc – Новая версия документа, которая будет сохранена.
oldDoc – Предыдущая версия документа, уже сохранённая.
userCtx – Объект контекста пользователя
secObj – Объект безопасности
- Вызывает исключение:
-
forbiddenошибка, чтобы предотвратить сохранение документа без аварийного завершения. - Вызывает исключение:
-
unauthorizedошибка, чтобы предотвратить сохранение и позволить пользователю повторно пройти аутентификацию.
Документ проектирования может содержать функцию с именем validate_doc_update, которую можно использовать для предотвращения сохранения недопустимых или неавторизованных запросов на обновление документа. Функции передаются новый документ из запроса на обновление, текущий документ, сохранённый в базе данных, Объект контекста пользователя, содержащий сведения о пользователе, записывающем документ (если он указан), и Объект безопасности со списками ролей безопасности базы данных.
Функции проверки обычно анализируют структуру нового документа, чтобы убедиться в наличии обязательных полей и проверить, разрешено ли запрашивающему пользователю изменять свойства документа. Например, приложение может требовать аутентификации пользователя для создания нового документа или наличия определённых полей документа при его обновлении. Функция проверки может отменить ожидающую запись документа, вызвав один из двух объектов ошибки:
// user is not authorized to make the change but may re-authenticate
throw({ unauthorized: 'Error message here.' });
// change is not allowed
throw({ forbidden: 'Error message here.' }); Проверка документов необязательна, и каждый документ проектирования в базе данных может содержать не более одной функции проверки. При получении запроса на запись для данной базы данных функция проверки в каждом документе проектирования этой базы данных вызывается в неопределённом порядке. Если любая из функций проверки вызывает ошибку, запись не будет выполнена.
Пример: ddoc _design/_auth из базы данных _users использует функцию проверки, чтобы убедиться, что документы содержат некоторые обязательные поля и изменяются только пользователем с ролью _admin:
function(newDoc, oldDoc, userCtx, secObj) {
if (newDoc._deleted === true) {
// allow deletes by admins and matching users
// without checking the other fields
if ((userCtx.roles.indexOf('_admin') !== -1) ||
(userCtx.name == oldDoc.name)) {
return;
} else {
throw({forbidden: 'Only admins may delete other user docs.'});
}
}
if ((oldDoc && oldDoc.type !== 'user') || newDoc.type !== 'user') {
throw({forbidden : 'doc.type must be user'});
} // we only allow user docs for now
if (!newDoc.name) {
throw({forbidden: 'doc.name is required'});
}
if (!newDoc.roles) {
throw({forbidden: 'doc.roles must exist'});
}
if (!isArray(newDoc.roles)) {
throw({forbidden: 'doc.roles must be an array'});
}
if (newDoc._id !== ('org.couchdb.user:' + newDoc.name)) {
throw({
forbidden: 'Doc ID must be of the form org.couchdb.user:name'
});
}
if (oldDoc) { // validate all updates
if (oldDoc.name !== newDoc.name) {
throw({forbidden: 'Usernames can not be changed.'});
}
}
if (newDoc.password_sha && !newDoc.salt) {
throw({
forbidden: 'Users with password_sha must have a salt.' +
'See /_utils/script/couch.js for example code.'
});
}
var is_server_or_database_admin = function(userCtx, secObj) {
// see if the user is a server admin
if(userCtx.roles.indexOf('_admin') !== -1) {
return true; // a server admin
}
// see if the user a database admin specified by name
if(secObj && secObj.admins && secObj.admins.names) {
if(secObj.admins.names.indexOf(userCtx.name) !== -1) {
return true; // database admin
}
}
// see if the user a database admin specified by role
if(secObj && secObj.admins && secObj.admins.roles) {
var db_roles = secObj.admins.roles;
for(var idx = 0; idx < userCtx.roles.length; idx++) {
var user_role = userCtx.roles[idx];
if(db_roles.indexOf(user_role) !== -1) {
return true; // role matches!
}
}
}
return false; // default to no admin
}
if (!is_server_or_database_admin(userCtx, secObj)) {
if (oldDoc) { // validate non-admin updates
if (userCtx.name !== newDoc.name) {
throw({
forbidden: 'You may only update your own user document.'
});
}
// validate role updates
var oldRoles = oldDoc.roles.sort();
var newRoles = newDoc.roles.sort();
if (oldRoles.length !== newRoles.length) {
throw({forbidden: 'Only _admin may edit roles'});
}
for (var i = 0; i < oldRoles.length; i++) {
if (oldRoles[i] !== newRoles[i]) {
throw({forbidden: 'Only _admin may edit roles'});
}
}
} else if (newDoc.roles.length > 0) {
throw({forbidden: 'Only _admin may set roles'});
}
}
// no system roles in users db
for (var i = 0; i < newDoc.roles.length; i++) {
if (newDoc.roles[i][0] === '_') {
throw({
forbidden:
'No system roles (starting with underscore) in users db.'
});
}
}
// no system names as names
if (newDoc.name[0] === '_') {
throw({forbidden: 'Username may not start with underscore.'});
}
var badUserNameChars = [':'];
for (var i = 0; i < badUserNameChars.length; i++) {
if (newDoc.name.indexOf(badUserNameChars[i]) >= 0) {
throw({forbidden: 'Character `' + badUserNameChars[i] +
'` is not allowed in usernames.'});
}
}
} Примечание
Оператор return используется только для функции и не влияет на процесс проверки.
См. также
- Руководство CouchDB:
Copyright © 2025 The Apache Software Foundation — Licensed under the Apache License 2.0
https://docs.couchdb.org/en/3.5.1/ddocs/ddocs.html