GitHub

API Reference

PouchDB有一个异步API,支持回调promiseasync函数 . 对于初学者,尽管您可以随意使用自己喜欢的任何格式,但我们还是建议您使用诺言. 如果不确定,请查看我们的异步代码指南 .

大部分API的暴露如下:

db.doSomething(args..., [options], [callback])

…其中optionscallback都是可选的.

Callbacks

回调使用以下标准的Node.js习惯用法:

function(error, result) { /* ... */ }

……如果没有错误, error将是不确定的.

Promises

如果未指定callback ,则API将返回promise . 在支持的浏览器或Node.js的,原生的承诺使用,回落至最低图书馆谎言需要.

使用Ionic / AngularJS? 您可以将PouchDB承诺包装在$q.when() . 当PouchDB承诺解决后,这将通知AngularJS更新UI.

若要对PouchDB使用自定义的Promise实现,必须在加载PouchDB之前重新定义全局Promise对象:

<script>window.Promise = MyCustomPromiseLibrary;</script>
<script src="path/to/pouchdb.js"></script>

Async functions

如果您使用的是像一个transpiler 通天 ,可以启用异步功能 ,这是一个实验性的API ES7(ES2016)暂定提名为发行. 这使您在使用基于承诺的API(例如PouchDB的API)时可以使用async / await关键字.

如何配置Babel? 要使用异步函数,您将需要语法async-functions插件 ,以及transform-regenerator插件Kneden (在撰写本文时仍处于试验阶段). 有关完整的工作示例,请参见async-functions-with-regenerator .

请注意,API文档中的async / await示例假定您的代码位于async函数内. 因此,例如:

async function myFunction() {
  // your code goes in here
}

任何不在异步函数内部的await都是语法错误. 有关async / await更多信息,请阅读我们的介绍性博客文章 .

new PouchDB([name], [options])

此方法创建数据库或打开现有数据库. 如果您使用类似'http://domain.com/dbname'的URL,则PouchDB将作为在线CouchDB实例的客户端. 否则,它将使用存在的任何后端创建本地数据库.

Options

  • name :您可以省略name参数,而是通过options指定它. 请注意,名称是必需的.

本地数据库的选项:

  • auto_compaction :这将启用自动压缩,这意味着每次对数据库进行更改后都会调用compact() . 默认为false .
  • adapter'idb''leveldb''http' .
  • revs_limit :指定要跟踪的旧修订版本数(而不是副本). 指定一个低值意味着Pouch可能无法确定通过复制收到的新修订是否与当前拥有的任何修订相关,这可能会导致冲突. 默认为1000
  • deterministic_revs :使用md5哈希值创建文档的确定性修订号. 将其设置为false意味着修订号将是随机的UUID. 默认为true.

远程数据库的选项:

  • fetch(url, opts) :拦截或覆盖HTTP请求,您可以添加或修改与http请求有关的任何标头或选项,然后返回新的访存Promise.
  • auth.username + auth.password :您可以通过使用名称格式为http://user:pass@host/name或通过auth.username + auth.password选项来指定HTTP auth参数.
  • skip_setup :最初,PouchDB检查数据库是否存在,并尝试创建数据库(如果尚不存在). 将此设置为true可跳过此设置.

Notes:

  1. 在IndexedDB中,PouchDB将使用_pouch_为内部数据库名称添加前缀. 不要手动创建具有相同前缀的数据库.
  2. 当在Node上充当客户端时,给定的任何其他选项都将传递给request .
  3. 当使用'leveldb'适配器(Node的默认设置)时,给出的任何其他选项都将传递给levelup .

Example Usage:

var db = new PouchDB('dbname');
// or
var db = new PouchDB('http://localhost:5984/dbname');

创建一个内存包(必须首先安装pouchdb-adapter-memory ):

var db = new PouchDB('dbname', {adapter: 'memory'});

创建具有特殊提取选项的远程PouchDB:

var db = new PouchDB('http://example.com/dbname', {
  fetch: function (url, opts) {
    opts.headers.set('X-Some-Special-Header', 'foo');
    return PouchDB.fetch(url, opts);
  }
});

有关更多信息,请查看适配器 .

db.destroy([options], [callback])

删除数据库. 请注意,这对其他复制的数据库没有影响.

Example Usage

Callback:

Async:

Promise:

Example Response:

{
  "ok" : true
}

Using db.put()

db.put(doc, [options], [callback])

创建一个新文档或更新一个现有文档. 如果文档已经存在,则必须指定其修订版_rev ,否则会发生冲突.

如果即使有冲突也要更新现有文档,则应指定基本修订_rev并使用force=true选项,然后将创建一个新的冲突修订.

doc必须是"纯JSON对象",即名称/值对的集合. 如果您尝试存储非JSON数据(例如Date对象),则可能会看到不一致的结果 .

Example Usage:

Create a new doc with an _id of 'mydoc':

Callback:

Async:

Promise:

您可以使用_rev更新现有文档:

Callback:

Async:

Promise:

Example Response:

{
  "ok": true,
  "id": "mydoc",
  "rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
}

响应中包含文档的id ,新的revok以确保一切正常.

Using db.post()

db.post(doc, [options], [callback])

创建一个新文档,然后让PouchDB自动为其生成一个_id .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "ok" : true,
  "id" : "8A2C3761-FFD5-4770-9B8C-38C33CED300A",
  "rev" : "1-d3a8e0e5aa7c8fff0c376dac2d8a4007"
}

Put vs. post :基本的经验法则是: put()具有_id新文档, post()没有_id新文档.

您还应该更喜欢put()而不是post() ,因为在post() ,您缺少使用allDocs()_id对文档进行排序的机会(因为_id是随机的). 有关更多信息,请阅读PouchDB专业提示 .

db.get(docId, [options], [callback])

检索由docId指定的文档.

Options

除非另有说明,否则所有选项默认为false .

  • options.rev :获取文档的特定修订版. 默认为获胜修订版(请参阅CouchDB指南 ).
  • options.revs :包括文档的修订历史记录.
  • options.revs_info :包括文档修订及其可用性的列表.
  • options.open_revs :如果open_revs="all"获取所有叶子修订版,或获取open_revs数组中指定的所有叶子修订版. 叶子将按照输入数组中指定的顺序返回.
  • options.conflicts :如果指定,则冲突的叶子修订版将附加在_conflicts数组中.
  • options.attachments :包括附件数据.
    • options.binary :以Blobs / Buffers的形式返回附件数据,而不是以base64编码的字符串形式返回.
  • options.latest: Forces retrieving latest “leaf” revision, no matter what rev was requested. Default is false.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "_id": "mydoc",
  "_rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
  "title": "Rock and Roll Heart",
}

响应包含文档存储在数据库中,以及_id_rev .

db.remove(doc, [options], [callback])

Or:

db.remove(docId, docRev, [options], [callback])

删除文件. doc必须是至少具有_id_rev属性的文档. 发送完整文档也可以.

请参阅过滤复制,以了解为什么您可能希望将put(){_deleted: true}使用.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "ok": true,
  "id": "mydoc",
  "rev": "2-9AF304BE281790604D1D8A4B0F4C9ADB"
}

您还可以通过仅提供idrev来删除文档:

Callback:

Async:

Promise:

您还可以通过将put(){_deleted: true}一起使用来删除文档:

Callback:

Async:

Promise:

db.bulkDocs(docs, [options], [callback])

创建,更新或删除多个文档. docs参数是一组文档.

如果在给定文档上省略_id参数,则数据库将创建一个新文档并为您分配ID. 要更新文档,必须同时包含_id参数和_rev参数,这_rev参数应与基于其更新的文档的ID和修订版相匹配. 最后,要删除文档,请包含_deleted参数,其值为true .

Example Usage:

放一些新文档,提供_id

Callback:

Async:

Promise:

Post some new docs and auto-generate the _ids:

Callback:

Async:

Promise:

Example Response:

[
  {
    "ok": true,
    "id": "doc1",
    "rev": "1-84abc2a942007bee7cf55007cba56198"
  },
  {
    "ok": true,
    "id": "doc2",
    "rev": "1-7b80fc50b6af7a905f368670429a757e"
  }
]

响应包含来自put()/ post()API的熟悉的ok / rev / id数组. 如果有任何错误,将单独提供它们,如下所示:

[
  { status: 409,
    name: 'conflict',
    message: 'Document update conflict',
    error: true
  }
]

结果以与提供的" docs"数组相同的顺序返回.

请注意, bulkDocs()不是事务性的,并且您可能会得到错误/非错误的混合数组. 在CouchDB / PouchDB中,最小的原子单位是文档.

Bulk update/delete:

您还可以使用bulkDocs()一次更新/删除许多文档:

Callback:

Async:

Promise:

或删除它们:

Callback:

Async:

Promise:

注意:如果将options对象的new_edits属性设置为false ,则可以发布其他数据库中的现有文档,而无需为其分配新的修订ID. 通常,只有复制算法才需要执行此操作.

db.allDocs([options], [callback])

提取多个文档,并按_id索引和排序. 仅在指定options.keys情况下才包括已删除的文档.

Options

除非另有说明,否则所有选项默认为false .

  • options.include_docs :将文档本身包含在doc字段的每一行中. 否则,默认情况下,您仅获得_id_rev属性.
  • options.conflicts :在文档的_conflicts字段中包含冲突信息.
  • options.attachments :将附件数据包括为base64编码的字符串.
  • options.binary :以Blobs / Buffers的形式返回附件数据,而不是以base64编码的字符串形式返回.
  • options.startkeyoptions.endkey :获取ID在一定范围内(包括/包括在内)的文档.
  • options.inclusive_end :包括ID等于给定options.endkey文档. 默认值: true .
  • options.limit :要返回的最大文档数.
  • options.skip :返回之前要跳过的文档数(警告:IndexedDB / LevelDB上的性能不佳!).
  • options.descending :反转输出文档的顺序. 注意, descending true时, startkeyendkey的顺序相反.
  • options.key :仅返回ID与此字符串键匹配的文档.
  • options.keys :一次捕获的字符串键数组.
    • 使用此选项不能指定开始startkeyendkey .
    • 这些行以与提供的keys数组相同的顺序返回.
    • 删除文档的行将具有删除的修订ID,并在value属性中带有一个额外的键"deleted":true .
    • 不存在的文档所在的行将仅包含值为"not_found""error"属性.
    • 有关详细信息,请参阅CouchDB查询选项文档 .
  • options.update_seq :包括一个update_seq值,该值指示视图反映基础数据库的哪个序列ID.

注意:对于分页, options.limitoptions.skip也可用,但是与CouchDB中的性能问题相同. 请改用startkey / endkey模式 .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "offset": 0,
  "total_rows": 1,
  "rows": [{
    "doc": {
      "_id": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
      "_rev": "1-5782E71F1E4BF698FA3793D9D5A96393",
      "title": "Sound and Vision",
      "_attachments": {
      	"attachment/its-id": {
      	  "content_type": "image/jpg",
      	  "data": "R0lGODlhAQABAIAAAP7//wAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw==",
      	  "digest": "md5-57e396baedfe1a034590339082b9abce"
      	}
      }
    },
   "id": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
   "key": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
   "value": {
    "rev": "1-5782E71F1E4BF698FA3793D9D5A96393"
   }
 }]
}

在响应中,您有三件事:

  • total_rows数据库中未删除文档的总数
  • offset skip如果提供),或在CouchDB中实际偏移
  • rows :包含文档的行,如果未将include_docs设置为true ,则仅包含_id / _revs .

  • 如果将update_seq设置为true则还可以选择具有update_seq

您可以使用startkey / endkey查找范围内的所有文档:

Callback:

Async:

Promise:

这将返回所有在'bar''quux'之间带有_id的文档.

您可以通过使用特殊的高Unicode字符'\ufff0'allDocs()进行前缀搜索-即"给我所有_id'foo'开头的文档'\ufff0'

Callback:

Async:

Promise:

之所以可行,是因为CouchDB / PouchDB _id是按字典顺序排序的.

db.changes(options)

对数据库中文档所做的更改的顺序列表,其顺序为: 它返回一个带有cancel()方法的对象,如果您不想再听新的更改,可以调用该对象.

它是一个事件发射器 ,将在每次文档更改时发出'change'事件,在处理'complete'所有更改后将发出'complete'事件,在发生'error'时将发出'error'事件. 调用cancel()将自动取消订阅所有事件侦听器.

Options

除非另有说明,否则所有选项默认为false .

  • options.live :将发出所有将来更改的更改事件,直到被取消.
  • options.include_docs :每次更改都包括关联的文档.
    • options.conflicts :包括冲突.
    • options.attachments :包括附件.
      • options.binary :以Blobs / Buffers的形式返回附件数据,而不是以base64编码的字符串形式返回.
  • options.descending :反转输出文档的顺序.
  • options.since :在给定序号之后立即从更改开始结果. 如果您只想进行新更改(当livetrue ),也可以传递'now' .
  • options.limit :将结果数限制为该数.
  • options.timeout :请求超时(以毫秒为单位),使用false禁用.
  • options.heartbeat :仅对于http适配器,服务器发出心跳以保持长时间连接打开的时间(以毫秒为单位). 默认值为10000(10秒),使用false禁用默认值.

过滤选项:

  • options.filter: Reference a filter function from a design document to selectively get updates. To use a view function, pass _view here and provide a reference to the view function in options.view. See filtered changes for details.
  • options.doc_ids :仅显示具有这些ID(字符串数组)的文档的更改.
  • options.query_params :对象包含传递给过滤函数,如性能{"foo:"bar"} ,其中"bar"将在过滤功能可用params.query.foo .要访问params ,定义过滤器函数,例如function (doc, params) {/* ... */} .
  • options.view :指定一个视图函数(例如'design_doc_name/view_name''view_name'作为'view_name/view_name'简写)以充当过滤器. 如果地图功能为其发出至少一条记录,则文档将被视为视图过滤器的"通过". 注意options.filter必须设置为'_view' ,此选项才能起作用.
  • options.selector :使用查询/ pouchdb查找选择器进行过滤. 注意 :CouchDB 1.x不支持选择器. 不能与过滤器选项结合使用.

高级选项:

  • options.return_docs :默认为true除非options.live = true否则默认为false . 传递false阻止更改提要将所有文档保留在内存中-换句话说,complete总是有一个空结果数组,而change事件是获取该事件的唯一方法. 对于大型更改集很有用,否则将耗尽内存.
  • options.batch_size :仅适用于http数据库,它配置了一次要获取的更改数量. 增加此数量可以减少发出的请求数量. 默认值为25.
  • options.style :指定在changes数组中返回多少修订. 默认'main_only' ,将仅返回当前的"获奖"修订版. 'all_docs'将返回所有叶子修订版(包括冲突和已删除的先前冲突). 除非您正在编写复制器,否则最有可能不需要它.
  • options.seq_interval :仅适用于http数据库. 指定仅每N次更改生成一次seq信息. 较大的值可以提高CouchDB 2.0及更高版本的更改吞吐量. 请注意, last_seq总是填充last_seq .

Example Usage:

var changes = db.changes({
  since: 'now',
  live: true,
  include_docs: true
}).on('change', function(change) {
  // handle change
}).on('complete', function(info) {
  // changes() was canceled
}).on('error', function (err) {
  console.log(err);
});

changes.cancel(); // whenever you want to cancel

Example Response:

{
  "id":"somestuff",
  "seq":21,
  "changes":[{
    "rev":"1-8e6e4c0beac3ec54b27d1df75c7183a8"
  }],
  "doc":{
    "title":"Ch-Ch-Ch-Ch-Changes",
    "_id":"someDocId",
    "_rev":"1-8e6e4c0beac3ec54b27d1df75c7183a8"
  }
}

Change events

  • changeinfo )-找到更改后将触发此事件. info将包含有关更改的详细信息,例如是否已删除以及新的_rev是什么. 如果将include_docs设置为trueinfo.doc将包含该文档. 请参阅下面的示例响应.
  • completeinfo )-读取所有更改complete触发此事件. 在实时更改中,只有取消更改才应触发此事件. info.results将包含更改列表. 请参阅下面的示例.
  • errorerr )-由于不可恢复的故障而停止更改Feed时,将引发此事件.

Example response

'change'侦听器中的示例响应(使用{include_docs: true} ):

{ id: 'doc1',
  changes: [ { rev: '1-9152679630cc461b9477792d93b83eae' } ],
  doc: {
    _id: 'doc1',
    _rev: '1-9152679630cc461b9477792d93b83eae'
  },
  seq: 1
}

删除文档后在'change'侦听器中的示例响应:

{ id: 'doc2',
  changes: [ { rev: '2-9b50a4b63008378e8d0718a9ad05c7af' } ],
  doc: { _id: 'doc2',
    _rev: '2-9b50a4b63008378e8d0718a9ad05c7af',
    _deleted: true
  },
  deleted: true,
  seq: 3
}

'complete'侦听器中的示例响应:

{
  "results": [
    {
      "id": "doc1",
      "changes": [ { "rev": "1-9152679630cc461b9477792d93b83eae" } ],
      "doc": {
        "_id": "doc1",
        "_rev": "1-9152679630cc461b9477792d93b83eae"
      },
      "seq": 1
    },
    {
      "id": "doc2",
      "changes": [ { "rev": "2-9b50a4b63008378e8d0718a9ad05c7af" } ],
      "doc": {
        "_id": "doc2",
        "_rev": "2-9b50a4b63008378e8d0718a9ad05c7af",
        "_deleted": true
      },
      "deleted": true,
      "seq": 3
    }
  ],
  "last_seq": 3
}

seqlast_seq对应于整个数据库的整体序列号,这是使用since时传递的内容(特殊的'now'除外). 它是更改提要的主键,也被复制算法用作检查点.

Single-shot

如果您未指定{live: true} ,那么您也可以使用标准的回调/承诺样式中的changes() ,它将被视为单次请求,该请求将返回更改列表(例如,发出'complete'事件):

Callback:

Async:

Promise:

Example Response:

{
  "results": [{
    "id": "0B3358C1-BA4B-4186-8795-9024203EB7DD",
    "seq": 1,
    "changes": [{
      "rev": "1-5782E71F1E4BF698FA3793D9D5A96393"
    }]
  }, {
    "id": "mydoc",
    "seq": 2,
    "changes": [{
      "rev": "1-A6157A5EA545C99B00FF904EEF05FD9F"
    }]
  }, {
    "id": "otherdoc",
    "seq": 3,
    "changes": [{
      "rev": "1-3753476B70A49EA4D8C9039E7B04254C"
    }]
  }, {
    "id": "828124B9-3973-4AF3-9DFD-A94CE4544005",
    "seq": 4,
    "changes": [{
      "rev": "1-A8BC08745E62E58830CA066D99E5F457"
    }]
  }],
  "last_seq": 4
}

如果livefalse ,则返回的对象也是事件发出者和承诺,并且将在准备好结果时触发'complete'事件.

请注意,仅当您不进行实时更改时才会触发此'complete'事件.

Filtered changes

copy()一样 ,您可以使用以下方法进行过滤:

  • 临时filter功能
  • doc_ids数组
  • 设计文档中的filter功能
  • 设计文档内部的带有query_paramsfilter函数
  • 设计文档中的view功能

如果在远程CouchDB上运行changes() ,则第一种方法将在客户端运行,而后四种将在服务器端进行过滤. 因此,最好使用后四个,尤其是在数据库较大的情况下,因为您希望通过网络发送尽可能少的文档.

如果您正在本地PouchDB上运行changes() ,那么显然所有五个方法都将在客户端运行. 使用这五个中的任何一个也没有性能上的好处,因此也可以在自己的on('change')处理函数中过滤自己. 这些方法纯粹是在PouchDB中实现的,目的是与CouchDB保持一致.

可以使用'designdoc_id/function_name'指定命名的函数,或者(如果设计文档ID和函数名称均相同)指定为'fname'作为'fname/fname'简写.

Filtering examples

在这些示例中,我们将与一些哺乳动物合作. 假设我们的文档是:

[
  {_id: 'a', name: 'Kangaroo', type: 'marsupial'},
  {_id: 'b', name: 'Koala', type: 'marsupial'},
  {_id: 'c', name: 'Platypus', type: 'monotreme'}
]

这是使用5种不同系统的5个示例.

示例1:临时filter功能

警告 :如果数据库是远程的,它将在客户端运行.

type === 'marsupial'过滤type === 'marsupial'

db.changes({
  filter: function (doc) {
    return doc.type === 'marsupial';
  }
});

示例2: doc_ids数组

使用_id s ['a', 'c']过滤文档.

db.changes({
  doc_ids: ['a', 'c']
});

示例3:设计文档中的filter功能

首先put()一个设计文件:

{
  _id: '_design/mydesign',
  filters: {
    myfilter: function (doc) {
      return doc.type === 'marsupial';
    }.toString()
  }
}

然后按type === 'marsupial'过滤:

db.changes({
  filter: 'mydesign/myfilter'
});

示例4:带有query_params的设计文档中的filter函数

这是最强大的过滤方式,因为它允许您将任意选项传递给过滤功能.

首先put()一个设计文件:

{
  _id: '_design/myfilter',
  filters: {
    myfilter: function (doc, req) {
      return doc.type === req.query.type;
    }.toString()
  }
}

然后按type === 'marsupial'过滤:

db.changes({
  filter: 'myfilter',
  query_params: {type: 'marsupial'}
});

由于设计文档和过滤器函数具有相同的名称,因此我们可以将函数名称'myfilter''myfilter' .

示例5:设计文档中的view功能

与前两种方法相比,这实际上没有任何优势,除非您已经使用view进行map / reduce查询,并且想要重用它.

任何emit()任何东西的文档都将被视为已通过此筛选器方法.

首先put()一个设计文件:

{
  _id: '_design/mydesign',
  views: {
    myview: function (doc) {
      if (doc.type === 'marsupial') {
        emit(doc._id);
      }
    }.toString()
  }
}

然后按type === 'marsupial'过滤:

db.changes({
  filter: '_view',
  view: 'mydesign/myview'
});
PouchDB.replicate(source, target, [options])

将数据从source复制到target . sourcetarget都可以是PouchDB实例,也可以是表示CouchDB数据库URL或本地PouchDB数据库名称的字符串. 如果options.livetrue ,则它将跟踪将来的更改并自动复制它们. 此方法返回一个带有cancel()方法的对象,如果要取消实时复制,可以调用该对象.

复制是一个类似于changes()事件发射器,并发出'complete''active''paused''change''denied''error'事件.

Options

除非另有说明,否则所有选项默认为false .

  • options.live :如果为true ,则开始订阅source数据库中将来的更改并继续复制它们.
  • options.retry :如果为true则在失败(由于脱机)的情况下将尝试重试复制,请使用退避算法,该算法以越来越长的时间间隔重试直到重新建立连接,最大延迟为10分钟. 仅当options.live也为true .

过滤选项:

  • options.filter :从设计文档中引用过滤器功能以有选择地获取更新. 要使用视图功能, _view在此处传递_view并在options.view提供对视图功能的引用. 有关详细信息,请参见过滤复制 .
  • options.doc_ids :仅显示具有这些ID(字符串数组)的文档的更改.
  • options.query_params :对象包含传递给过滤器函数的属性,例如{"foo":"bar"} ,其中"bar"在过滤器函数中可作为params.query.foo . 要访问这些params ,请定义您的过滤器函数,例如function (doc, params) {/* ... */} .
  • options.view :指定一个视图函数(例如'design_doc_name/view_name''view_name'作为'view_name/view_name'简写)以充当过滤器. 如果地图功能为其发出至少一条记录,则文档将被视为视图过滤器的"通过". 注意options.filter必须设置为'_view' ,此选项才能起作用.
  • options.selector :使用查询/ pouchdb查找选择器进行过滤. 注意 :CouchDB 1.x不支持选择器.

高级选项:

  • options.since :在给定序列号之后复制更改.
  • options.heartbeat :配置CouchDB支持的心跳,使更改连接保持活动状态.
  • options.timeout :请求超时(以毫秒为单位).
  • options.batch_size :一次要处理的变更Feed项的数量. 默认值为100.这会影响内存中保存的文档和附件的数量以及一次发送到目标服务器的数量. 如果定位内存不足的设备(例如电话),或者文档和/或附件的大小很大,或者版本有很多冲突,则可能需要向下调整. 如果您的文档很小,那么增加此数量可能会加快复制速度.
  • options.batches_limit :一次要处理的批次数. 默认值为10.(与batch_size )控制一次在内存中保留多少文档,因此一次在内存中的最大文档数等于batch_size × batches_limit .
  • options.back_off_functionretry复制中使用的退避功能. 此函数将当前补偿作为输入(或第一次为0),并以毫秒为单位返回新补偿. 您可以使用它来调整用户脱机时复制将尝试重新连接到远程数据库的时间以及方式. 默认为一个函数,该函数在0到2秒之间选择一个随机退避,并在每次连接失败时加倍. 默认延迟将不会超过10分钟. (请参阅下面的自定义重试复制 .)
  • options.checkpoint :如果要禁用源,目标或两者上的检查点,可以使用. 将此选项设置为false将防止在源和目标上都写入检查点. 将其设置为source只会在源上写入检查点. 将其设置为target只会在目标上写入检查点.

Example Usage:

var rep = PouchDB.replicate('mydb', 'http://localhost:5984/mydb', {
  live: true,
  retry: true
}).on('change', function (info) {
  // handle change
}).on('paused', function (err) {
  // replication paused (e.g. replication up to date, user went offline)
}).on('active', function () {
  // replicate resumed (e.g. new changes replicating, user went back online)
}).on('denied', function (err) {
  // a document failed to replicate (e.g. due to permissions)
}).on('complete', function (info) {
  // handle complete
}).on('error', function (err) {
  // handle error
});

rep.cancel(); // whenever you want to cancel

给定现有的PouchDB对象,还有一些复制的捷径. 这些行为与PouchDB.replicate()相同:

db.replicate.to(remoteDB, [options]);
// or
db.replicate.from(remoteDB, [options]);

remoteDB可以是字符串,也可以是PouchDB对象. 如果在远程数据库上具有访存覆盖,则将要使用PouchDB对象而不是字符串,以便使用这些选项.

Replication events

  • changeinfo )-复制写入新文档时将触发此事件. info将包含有关更改的详细信息. info.docs将包含该更改所涉及的文档. 请参阅下面的示例响应.
  • completeinfo )-复制完成或取消时触发此事件. 在实时复制中,只有取消复制才应触发此事件. info将包含有关复制的详细信息. 请参阅下面的示例响应.
  • pausederr )-暂停复制时将触发此事件,可能是由于实时复制正在等待更改,或者是由于err导致复制暂时失败,并试图恢复.
  • active -当复制开始积极变化处理此事件; 例如,当错误恢复或有新更改可用时.
  • deniederr )-如果由于验证或授权错误而导致文档复制失败,则触发此事件.
  • errorerr )-由于不可恢复的故障而停止复制时,将引发此事件. 如果retryfalse ,则在用户脱机或发生其他网络错误时也会触发(因此,您可以自行处理重试).

Single-shot

changes()一样 ,您也可以省略live ,在这种情况下,您可以使用回调/承诺样式的copy replicate() ,它将被视为一次操作.

Callback:

Async:

Promise:

对于非实时复制,返回的对象也是事件发出者和承诺,并且您可以使用上述所有事件( 'paused''active'除外,它们仅适用于retry复制).

Example Response:

'change'侦听器中的示例响应:

{
  "doc_write_failures": 0,
  "docs_read": 1,
  "docs_written": 1,
  "errors": [],
  "last_seq": 1,
  "ok": true,
  "start_time": "Fri May 16 2014 18:23:12 GMT-0700 (PDT)",
  "docs": [
    { _id: 'docId',
      _rev: '1-e798a1a7eb4247b399dbfec84ca699d4',
      and: 'data' }
  ]
}

'complete'侦听器中的示例响应:

{
  "doc_write_failures": 0,
  "docs_read": 2,
  "docs_written": 2,
  "end_time": "Fri May 16 2014 18:26:00 GMT-0700 (PDT)",
  "errors": [],
  "last_seq": 2,
  "ok": true,
  "start_time": "Fri May 16 2014 18:26:00 GMT-0700 (PDT)",
  "status": "complete"
}

请注意,本地和远程数据库均支持复制. 因此,您可以从本地复制到本地或从远程复制到远程.

但是,如果从远程复制到远程,则更改将通过PouchDB进行. 如果要触发服务器启动的复制,请按照CouchDB文档中的描述,使用常规ajax POST到CouchDB _replicate端点.

Filtered replication

changes()一样 ,您可以使用以下方法从源数据库进行过滤:

  • 临时filter功能
  • an array of doc_ids
  • 设计文档中的filter功能
  • 设计文档内部的带有query_paramsfilter函数
  • 设计文档中的view功能

如果要从远程CouchDB复制,则第一种方法将在客户端运行,而后四种将在服务器端进行过滤. 因此,最好使用后四个,尤其是在数据库较大的情况下,因为您希望通过网络发送尽可能少的文档.

您还应该提防尝试使用过滤复制来增强安全性,例如,为每个用户划分数据库. 更好的策略是"每个用户一个数据库"方法 .

删除过滤的文档 :使用过滤的复制时,应避免使用remove()删除文档,因为这也会删除其所有字段,这意味着它们可能不再通过过滤功能,从而导致无法复制已删除的修订. 而是将doc._deleted标志设置为true ,然后使用put()bulkDocs() .

Filtering examples

在这些示例中,我们将与一些哺乳动物合作. 假设我们的文档是:

[
  {_id: 'a', name: 'Kangaroo', type: 'marsupial'},
  {_id: 'b', name: 'Koala', type: 'marsupial'},
  {_id: 'c', name: 'Platypus', type: 'monotreme'}
]

这是使用5种不同系统的5个示例.

示例1:临时filter功能

警告 :如果要从远程数据库复制,它将在客户端运行.

type === 'marsupial'过滤type === 'marsupial'

remote.replicate.to(local, {
  filter: function (doc) {
    return doc.type === 'marsupial';
  }
});

示例2: doc_ids数组

使用_id s ['a', 'c']过滤文档.

remote.replicate.to(local, {
  doc_ids: ['a', 'c']
});

示例3:设计文档中的filter功能

首先在远程数据库中put()一个设计文档:

{
  _id: '_design/mydesign',
  filters: {
    myfilter: function (doc) {
      return doc.type === 'marsupial';
    }.toString()
  }
}

然后按type === 'marsupial'过滤:

remote.replicate.to(local, {
  filter: 'mydesign/myfilter'
});

示例4:带有query_params的设计文档中的filter函数

这是最强大的过滤方式,因为它允许您将任意选项传递给过滤功能.

首先在远程数据库中put()一个设计文档:

{
  _id: '_design/mydesign',
  filters: {
    myfilter: function (doc, req) {
      return doc.type === req.query.type;
    }.toString()
  }
}

然后按type === 'marsupial'过滤:

remote.replicate.to(local, {
  filter: 'mydesign/myfilter',
  query_params: {type: 'marsupial'}
});

示例5:设计文档中的view功能

与前两种方法相比,这实际上没有任何优势,除非您已经使用view进行map / reduce查询,并且想要重用它.

任何emit()任何东西的文档都将被视为已通过此筛选器方法.

首先在远程数据库中put()一个设计文档:

{
  _id: '_design/mydesign',
  views: {
    myview: {
      map: function(doc) {
        if (doc.type === 'marsupial') {
          emit(doc._id);
        }
      }.toString()
    }
  }
}

然后按type === 'marsupial'过滤:

remote.replicate.to(local, {
  filter: '_view',
  view: 'mydesign/myview'
});

Customizing retry replication

retry复制期间,您可以自定义退避功能,该功能确定用户脱机时重新连接之前要等待的时间.

这是一个简单的退避功能,该功能从1000毫秒开始,每次远程请求失败时,其功能都会增加两倍:

db.replicate.to(remote, {
  live: true,
  retry: true,
  back_off_function: function (delay) {
    if (delay === 0) {
      return 1000;
    }
    return delay * 3;
  }
});

第一次请求失败时,此函数将接收0作为输入. 下次失败时,将先传递1000,然后再传递3000,再传递9000,依此类推.当用户重新联机时, delay将回到0.

默认情况下,PouchDB使用退避功能,该功能选择0到2000毫秒之间的随机起始数字,并且每次都会大致翻倍,并且具有一定的随机性以防止客户端请求同时发生.

var sync = PouchDB.sync(src, target, [options])

同步数据从srctargettargetsrc . 这是双向数据复制的便捷方法.

换句话说,此代码:

PouchDB.replicate('mydb', 'http://localhost:5984/mydb');
PouchDB.replicate('http://localhost:5984/mydb', 'mydb');

等效于以下代码:

PouchDB.sync('mydb', 'http://localhost:5984/mydb');

Options

  • options.push + options.pull :允许您为单个复制指定单独的复制选项 .

复制选项(例如,传递给直接同步的filter将传递到两个复制中. 请参阅copy()以获得有关这些选项的文档.

Example Usage:

var sync = PouchDB.sync('mydb', 'http://localhost:5984/mydb', {
  live: true,
  retry: true
}).on('change', function (info) {
  // handle change
}).on('paused', function (err) {
  // replication paused (e.g. replication up to date, user went offline)
}).on('active', function () {
  // replicate resumed (e.g. new changes replicating, user went back online)
}).on('denied', function (err) {
  // a document failed to replicate (e.g. due to permissions)
}).on('complete', function (info) {
  // handle complete
}).on('error', function (err) {
  // handle error
});

sync.cancel(); // whenever you want to cancel

还有一个同步给定现有PouchDB对象的捷径. 行为与PouchDB.sync()相同:

db.sync(remoteDB, [options]);

由于性能原因,还可以将"单向"复制和同步结合在一起. 当您的PouchDB应用程序启动时,它可以执行一次性的单向复制,直到完成,然后启动双向的,连续的可重试同步:

var url = 'http://localhost:5984/mydb';
var opts = { live: true, retry: true };

// do one way, one-off sync from the server until completion
db.replicate.from(url).on('complete', function(info) {
  // then two-way, continuous, retriable sync
  db.sync(url, opts)
    .on('change', onSyncChange)
    .on('paused', onSyncPaused)
    .on('error', onSyncError);
}).on('error', onSyncError);

与仅使用db.sync相比,以上技术导致使用的HTTP请求更少,性能更高.

Example Response:

sync更改事件具有一个额外的属性direction ,该方向指的是更改的方向. 其值将为pushpull .

{ direction: 'push',
  change:
   { ok: true,
     start_time: '2015-10-21T15:26:51.151Z',
     docs_read: 1,
     docs_written: 1,
     doc_write_failures: 0,
     errors: [],
     last_seq: 1,
     docs: [ [Object] ] } }

有关更多详细信息,请参考copy() .

db.putAttachment(docId, attachmentId, [rev], attachment, type, [callback]);

将二进制对象附加到文档.

此方法将更新现有文档以添加附件,因此如果文档已存在,则需要rev . 如果文档尚不存在,则此方法将创建一个包含附件的空文档.

附件的意义是什么? 如果您要处理大型二进制数据(例如PNG),则如果将它们简单地作为base64或十六进制编码的字符串包含在文档中,则可能会导致性能或存储损失. 但是,如果您将二进制数据作为附件插入,则PouchDB将尝试以最有效的方式存储它.

有关详细信息,请参阅附件中CouchDB文档 .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "ok": true,
  "id": "doc",
  "rev": "2-068E73F5B44FEC987B51354DFC772891"
}

在Node中,必须使用Buffer而不是Blob

var attachment = new Buffer('Is there life on Mars?');

For details, see the Mozilla docs on Blob or the Node docs on Buffer.

如果您需要不支持Blob构造函数的较旧浏览器的填充程序,或者想要一些方便的Blob方法,则可以使用blob-util .

Save a base64 attachment

如果您提供一个字符串而不是Blob / Buffer ,那么它将被假定为base64编码的字符串,并将对其进行相应的处理:

Callback:

Async:

Promise:

Save an inline attachment

您还可以内联文档中的附件. 附件数据可以作为具有content_type的base64编码的字符串提供:

Callback:

Async:

Promise:

Save an inline Blob/Buffer attachment

您还可以内联BlobBuffer

Callback:

Async:

Promise:

Save many attachments at once

内联方法允许您一次将多个附件保存到同一文档:

Callback:

Async:

Promise:

有关详细信息,请参见CouchDB Wiki上的内联附件 .

db.getAttachment(docId, attachmentId, [options], [callback])

获取附件数据.

Options

  • options.rev :与get()一样 ,您可以传递rev ,并获取该特定修订版本的文档附件.

Example Usage:

从ID为'doc'文档中获取文件'att.txt'的附件:

Callback:

Async:

Promise:

从ID为'doc'文档获取文件'att.txt'的附件,版本为'1-abcd'

Callback:

Async:

Promise:

Response type:

响应将是浏览器中的Blob对象,以及Node.js中的Buffer对象. 有关将Blob转换为其他格式的实用程序,请参见blob-util ,例如base64编码的字符串,数据URL,数组缓冲区等.

Inline base64 attachments

You can specify {attachments: true} to most “read” operations, such as get(), allDocs(), changes(), and query(). The attachment data will then be included inlined in the resulting doc(s). However, it will always be supplied as base64. For example:

{
  "_attachments": {
    "att.txt": {
      "content_type": "text/plain",
      "digest": "d5ccfd24a8748bed4e2c9a279a2b6089",
      "data": "SXMgdGhlcmUgbGlmZSBvbiBNYXJzPw=="
    }
  },
  "_id": "mydoc",
  "_rev": "1-e147d9ec9c85139dfe7e93bc17148d1a"
}

对于此类API,当您不指定{attachments: true} ,您将获得有关附件的元数据. 例如:

{
  "_attachments": {
    "att.txt": {
      "content_type": "text/plain",
      "digest": "d5ccfd24a8748bed4e2c9a279a2b6089",
      "stub": true
    }
  },
  "_id": "mydoc",
  "_rev": "1-e147d9ec9c85139dfe7e93bc17148d1a"
}

在某些情况下,此"摘要"操作可能会更快,因为不需要从磁盘读取附件本身.

db.removeAttachment(docId, attachmentId, rev, [callback])

从文档中删除附件. 您必须提供现有文档的rev .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "ok": true,
  "rev": "2-1F983211AB87EFCCC980974DFC27382F"
}
db.createIndex(index [, callback])

如果不存在则创建索引,或者如果已经存在则不执行任何操作.

需要使用pouchdb-find插件:此API需要使用pouchdb-find插件. 请参阅芒果查询以获取安装说明.

Example Usage:

Callback:

Async:

Promise:

Example Response:

如果创建索引,您将看到:

{ "result": "created" }

或者,如果索引已经存在:

{ "result": "exists" }

您还可以在多个字段上创建索引:

Callback:

Async:

Promise:

或关于深场的索引:

Callback:

Async:

Promise:

如果要对创建索引的方式进行更多控制,还可以指定其他选项:

Callback:

Async:

Promise:

Options

  • fields :要索引的字段列表
  • name (可选):索引名称,如果不包含索引,则自动生成
  • ddoc (可选):设计文档名称(即'_design/'之后的部分),如果不包含它则自动生成
  • type (可选):仅支持'json' ,这也是默认值
db.find(request [, callback])

查询索引并返回与请求匹配的文档列表.

需要使用pouchdb-find插件:此API需要使用pouchdb-find插件. 请参阅芒果查询以获取安装说明.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "docs": [
    {
      "_id": "mario",
      "name": "Mario"
    }
  ]
}

上面是一个简单的示例. 有关深入的教程,请参阅《芒果指南》 .

Options

  • selector定义一个选择器以过滤结果. 需要.
    • $lt匹配字段"小于"此字段.
    • $gt匹配字段"大于"此字段.
    • $lte匹配字段"小于或等于"此字段.
    • $gte匹配字段"大于或等于"此字段.
    • $eq匹配字段与此相等.
    • $ne匹配不等于此字段的字段.
    • $exists如果该字段应存在, $exists true,否则为false.
    • $type " null"," boolean"," number"," string"," array"或" object"之一.
    • $in文档字段必须存在于提供的列表中.
    • $and如果数组中的所有选择器都匹配则匹配.
    • $nin提供的列表中不能存在文档字段.
    • $all如果它包含参数数组的所有元素,则匹配数组值.
    • $size特殊条件,用于匹配文档中数组字段的长度.
    • $or如果数组中的任何选择器匹配,则匹配. 所有选择器必须使用相同的索引.
    • $nor如果数组中的所有选择器$nor匹配,则匹配.
    • $not如果给定的选择器不匹配,则匹配.
    • $mod仅在document字段为整数时,匹配(field%Divisor == Remainder)为true的文档.
    • $regex与文档字段匹配的$regex则表达式模式.
    • $elemMatch匹配包含一个包含至少一个与所有指定查询条件匹配的元素的数组字段的所有文档.
  • fields (可选)定义要接收的字段列表. 如果省略,则会获得完整的文档.
  • sort (可选)定义用于定义sort的字段列表. 请注意,还必须在selector已排序的字段.
  • limit (可选)要返回的最大文档数.
  • skip (可选)返回之前要跳过的文档数.
  • use_index (可选)设置要用于查询的索引. 它可以是" design-doc-name"或" ['design-doc-name','name']".

如果没有与您的selector / sort匹配的索引,则此方法将发出警告:

{
  "docs": [ /* ... */ ],
  "warning": "no matching index found, create an index to optimize query time"
}

最佳索引将自动选择. 如果要查看查询的查询计划,请打开调试:

PouchDB.debug.enable('pouchdb:find');

有关选择器和Mango查询语言的更多详细信息,请参见CouchDB _find文档 .

More examples

使用$eq表示"等于":

Callback:

Async:

Promise:

这等效于:

Callback:

Async:

Promise:

您还可以在多个字段上进行选择. 例如,要查找所有series'Mario'debut大于1990文档:

Callback:

Async:

Promise:

这等效于:

Callback:

Async:

Promise:

您还可以对返回的文档进行排序. 例如,要查找按debut登降序排序的所有文档:

Callback:

Async:

Promise:

db.explain(request [, callback])

解释给定查询的查询计划

需要使用pouchdb-find插件:此API需要使用pouchdb-find插件. 请参阅芒果查询以获取安装说明.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "dbname": "database-name"
  "index": {
    "ddoc": "_design/design-doc-name",
    "name": "index-name",
    "type": "json",
    "def": {
      "fields": [
        {
          "name": "asc"
        },
        {
          "series": "asc"
        }
      ]
    }
  },
  "selector": {
    "$and": [
      {
        "name": {
          "$eq": "mario"
        }
      },
      {
        "series": {
          "$eq": "mario"
        }
      }
    ]
  },
  "opts": {
    "use_index": [],
    "bookmark": "nil",
    "limit": 25,
    "skip": 0,
    "sort": {"name": "asc"},
    "fields": [
      "_id"
    ],
    "r": [
      49
    ],
    "conflicts": false
  },
  "limit": 10,
  "skip": 1,
  "fields": [
    "_id"
  ],
  "range": {
    "start_key": [
      "mario",
      "mario"
    ],
    "end_key": [
      "mario",
      "mario",
      {}
    ]
  }
};
db.getIndexes([callback])

获取您创建的所有索引的列表. 还告诉您特殊的_all_docs索引,即_id字段上的默认索引.

需要使用pouchdb-find插件:此API需要使用pouchdb-find插件. 请参阅芒果查询以获取安装说明.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "indexes": [
    {
      "ddoc": null,
      "name": "_all_docs",
      "type": "special",
      "def": {
        "fields": [
          {
            "_id": "asc"
          }
        ]
      }
    },
    {
      "ddoc": "_design/idx-0f3a6f73110868266fa5c688caf8acd3",
      "name": "idx-0f3a6f73110868266fa5c688caf8acd3",
      "type": "json",
      "def": {
        "fields": [
          {
            "foo": "asc"
          },
          {
            "bar": "asc"
          }
        ]
      }
    }
  ]
}
db.deleteIndex(index [, callback])

删除索引,删除所有孤立的设计文档,并清理磁盘上的所有剩余数据.

需要使用pouchdb-find插件:此API需要使用pouchdb-find插件. 请参阅芒果查询以获取安装说明.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{ "ok": true }

注意,最简单的方法是使用getIndexes()找到要删除的索引. 例如,以下是从该列表删除第二个索引的方法(该索引应该是内置_all_docs索引之后的_all_docs ):

Callback:

Async:

Promise:

Notes:

  • 删除索引时无需提供_rev .
  • 假定仅包含一个索引,则关联的设计文档将自动删除.
  • 无需调用viewCleanup来清理所有剩余的数据. deleteIndex()会自动为您执行此操作.
db.query(fun, [options], [callback])

调用map / reduce函数,该函数允许您在PouchDB上执行比allDocs()changes()find()更为复杂的查询. 用于映射/缩小CouchDB文档适用于PouchDB.

由于视图会对所有文档执行全面扫描,因此除非您先将视图保存在设计文档中,否则此方法可能会很慢. 阅读查询指南以获取良好的教程.

警告:高级API. map / reduce API专为对于Mango查询而言过于复杂的情况而设计,在createIndex()find()listIndexes()deleteIndex()中进行了描述 .

在后台,Mango索引与map / reduce索引相同. Mango API只是map / reduce之上的简化的面向用户的API.

Options

除非另有说明,否则所有选项默认为false .

  • fun :映射/归约函数,可以是以下之一:
    • 完整的CouchDB样式的map / reduce视图: {map : ..., reduce: ...} .
    • 映射功能本身(不减少).
    • 现有设计文档中视图的名称(例如'mydesigndoc/myview''myview'作为'myview/myview'的简写).
  • options.reduce :定义了reduce函数时,默认为true ,否则为false . 有效值:
    • true -调用定义reduce功能,或者map功能,如果没有reduce被定义.
    • false调用定义的map函数.
    • 归约功能.
    • :内置函数的字符串名称'_sum''_count' ,或'_stats' .
      • 提示:如果您不使用内置功能,则可能做错了 .
      • PouchDB将始终使用rereduce == false来调用reduce函数. 至于CouchDB,请参阅CouchDB文档 .
  • options.include_docs :将文档包含在doc字段的每一行中.
    • options.conflicts :在文档的_conflicts字段中包含冲突.
    • options.attachments :包括附件数据.
      • options.binary :以Blobs / Buffers的形式返回附件数据,而不是以base64编码的字符串形式返回.
  • options.startkeyoptions.endkey :获取键在一定范围内(包括/不包括)的行.
  • options.inclusive_end :包括键等于给定options.endkey . 默认值: true .
  • options.limit :要返回的最大行数.
  • options.skip :返回之前要跳过的行数(警告:IndexedDB / LevelDB上的性能不佳!).
  • options.descending :反转输出行的顺序.
  • options.key :仅返回与此键匹配的行.
  • options.keys :单次获取的键数组.
    • 使用此选项不能指定开始startkeyendkey .
    • 这些行以与提供的keys数组相同的顺序返回.
    • 删除文档的行将具有删除的修订ID,并在value属性中带有一个额外的键"deleted":true .
    • 不存在的文档所在的行将仅包含值为"not_found""error"属性.
  • options.group :如果您希望化简函数按键对结果进行分组,而不是返回单个结果,则为true. 默认为false .
  • options.group_level :假设键是数组,则键中要分组的元素数. 默认为数组的全长.
  • options.stale'ok''update_after' . 仅适用于已保存的视图. 可以是以下之一:
    • 未指定(默认):返回最新结果,必要时等待视图建立.
    • 'ok' :立即返回结果,即使它们已过期.
    • 'update_after' :立即返回结果,但随后开始构建.
  • options.update_seq :包括一个update_seq值,该值指示视图反映基础数据库的哪个序列ID.

有关详细信息,请参阅CouchDB查询选项文档 .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "offset" : 0,
  "rows": [{
    "id": "doc3",
    "key": "Lisa Says",
    "value": null,
    "doc": {
      "_id": "doc3",
      "_rev": "1-z",
      "title": "Lisa Says"
    }
  }],
  "total_rows" : 4
}

结果中, total_rows是视图中可能结果的总数. 响应与allDocs()的响应非常相似.

如果将update_seq设置为true则结果也可能具有update_seq

注意:您也可以传递map函数而不是先保存设计文档,但这很慢,因为它必须进行完整的数据库扫描. 为了简化起见,以下示例将使用此模式,但通常应避免使用它.

Complex keys

您还可以使用复杂的键进行花式订购:

Callback:

Async:

Promise:

Example Response:

{
  "offset": 0,
  "rows": [{
      "id"  : "bowie",
      "key" : ["Bowie", "David", 67]
    }, {
      "id"  : "dylan",
      "key" : ["Dylan", "Bob", 72]
    }, {
      "id"  : "younger_dylan",
      "key" : ["Dylan", "Jakob", 44]
    }, {
      "id"  : "hank_the_third",
      "key" : ["Williams", "Hank", 41]
    }, {
      "id"  : "hank",
      "key" : ["Williams", "Hank", 91]
    }],
  "total_rows": 5
}

Tips:

  • 排序顺序为[nulls, booleans, numbers, strings, arrays, objects] ,因此{startkey: ['Williams'], endkey: ['Williams', {}]}将返回所有姓氏为'Williams'因为对象高于字符串. 像'zzzzz''\ufff0''zzzzz'东西也可以工作.
  • 使用复杂键时, group_level可能会非常有用. 在上面的示例中,您可以使用{group_level: 1}按姓氏分组,或者使用{group_level: 2}按姓氏和名字分组. (请务必同时设置{reduce: true, group: true} .)

Linked documents

PouchDB完全支持链接的文档 . 只需将_id添加到发出的值,即可使用它们将两种类型的文档连接在一起:

Callback:

Async:

Promise:

Example response:

{
    "offset": 0,
    "rows": [
        {
            "doc": {
                "_id": "bowie",
                "_rev": "1-fdb234b78904a5c8293f2acf4be70d44",
                "age": 67,
                "firstName": "David",
                "lastName": "Bowie"
            },
            "id": "album_hunkeydory",
            "key": "Hunky Dory",
            "value": {
                "_id": "bowie",
                "albumYear": 1971
            }
        },
        {
            "doc": {
                "_id": "bowie",
                "_rev": "1-fdb234b78904a5c8293f2acf4be70d44",
                "age": 67,
                "firstName": "David",
                "lastName": "Bowie"
            },
            "id": "album_low",
            "key": "Low",
            "value": {
                "_id": "bowie",
                "albumYear": 1977
            }
        },
        {
            "doc": {
                "_id": "bowie",
                "_rev": "1-fdb234b78904a5c8293f2acf4be70d44",
                "age": 67,
                "firstName": "David",
                "lastName": "Bowie"
            },
            "id": "album_spaceoddity",
            "key": "Space Oddity",
            "value": {
                "_id": "bowie",
                "albumYear": 1969
            }
        }
    ],
    "total_rows": 3
}

Closures

如果将一个函数传递给db.query并将其emit函数作为第二个参数,则可以使用闭包. (由于PouchDB必须使用eval()来绑定emit .)

Callback:

Async:

Promise:

请注意,只有具有临时视图的本地数据库才支持关闭. 因此,如果使用闭包,则必须使用较慢的方法,该方法需要完整的数据库扫描.

db.viewCleanup([callback])

清除所有过时的映射/减少索引.

随着设计文档的删除或修改,它们的关联索引文件(在CouchDB中)或伴随数据库(在本地PouchDB中)继续占用磁盘空间. viewCleanup()删除这些不必要的索引文件.

有关详细信息,请参见有关视图清理的CouchDB文档 .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{ "ok" : "true" }
db.info([callback])

获取有关数据库的信息.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "db_name": "test",
  "doc_count": 4,
  "update_seq": 5
}

响应对象:

  • db_name是您在调用new PouchDB()时提供的数据库名称,也是该数据库的唯一标识符.
  • doc_count是数据库中未删除文档的总数.
  • update_seq是数据库的序列号. 它从0开始,并在每次添加或修改文档时递增.

您还可以使用一些详细信息进行调试. 这些是非官方的,可能随时更改:

  • adapter :正在使用的适配器的名称(idb,leveldb等).
  • idb_attachment_format :(IndexedDB) 'base64''binary' ,具体取决于浏览器是否支持二进制Blob .
  • backend_adapter :(Node.JS)正在使用的后端* DOWN适配器(MemDOWN,RiakDOWN等).
db.compact([options], [callback])

在本地或远程数据库中触发压缩操作. 通过删除未使用的和旧的数据(即非叶子修订版和不再被这些修订版引用的附件),可以减小数据库的大小. 请注意,这是与viewCleanup()分开的操作.

对于远程数据库,PouchDB会定期检查压缩状态,并在完成后触发回调(或解析承诺). 有关更多详细信息,请查阅CouchDB维护文档压缩部分 .

另请参阅自动压缩 ,它会自动运行压缩(仅限本地数据库).

  • options.interval :再次询问是否已执行压缩之前要等待的毫秒数. 默认值为200.(仅适用于远程数据库.)

Example Usage:

Callback:

Async:

Promise:

Example Response:

{ "ok" : "true" }
db.revsDiff(diff, [callback])

给定一组文档/修订ID,返回与存储在数据库中的修订不对应的那些子集. 主要用于复制.

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "myDoc1": {
    "missing": ["2-3a24009a9525bde9e4bfa8a99046b00d"]
  }
}
db.bulkGet(options, [callback])

给定一组文档/修订版ID,返回指定的每个ID /修订对的文档主体(以及可选的附件数据).

Options

  • options.docs :的数组idrev表示修订取对.
    • id :要获取的文档的ID.
    • rev :修订要获取的文档. 如果未指定,则将获取所有可用的修订.
    • atts_since :可选,仅受http适配器支持. 仅包含自指定修订版以来的附件. 不包括指定修订的附件.
  • options.revs :每个返回的修订正文将包含其修订历史作为_revisions属性. 默认值为false .
  • options.attachments :在响应中包括附件数据. 默认值为false ,导致仅返回存根.
  • options.binary :以Blobs / Buffers的形式返回附件数据,而不是以base64编码的字符串形式返回. 默认值为false .

Example Usage:

Callback:

Async:

Promise:

Example Response:

{
  "results": [
  {
    "docs": [
    {
      "ok": {
        "_id": "doc-that-exists",
        "_rev": "1-967a00dff5e02add41819138abb3284d",
        "_revisions": {
          "ids": [
            "967a00dff5e02add41819138abb3284d"
          ],
          "start": 1
        }
      }
    }],
    "id": "doc-that-exists"
  },
  {
    "docs": [
    {
      "error": {
        "error": "not_found",
        "id": "doc-that-does-not-exist",
        "reason": "missing",
        "rev": "undefined"
      }
    }],
    "id": "doc-that-does-not-exist"
  },
  {
    "docs": [
    {
      "error": {
        "error": "not_found",
        "id": "doc-that-exists",
        "reason": "missing",
        "rev": "1-badrev"
      }
    }
    ],
    "id": "doc-that-exists"
  }]
}
db.close([callback])

关闭数据库,这将关闭与基础存储的所有打开的连接,并释放数据库可能正在使用的内存(事件侦听器).

Example Usage

Callback:

Async:

Promise:

PouchDB是事件发射器'created'数据库时将发出'created'事件. 'destroyed'数据库时,将发出'destroyed'事件.

PouchDB.on('created', function (dbName) {
  // called whenever a db is created.
});
PouchDB.on('destroyed', function (dbName) {
  // called whenever a db is destroyed.
});

如果发现自己反复使用相同的构造函数选项,则可以使用PouchDB.defaults()简化代码:

PouchDB.defaults({
  option1: 'foo',
  option2: 'value'
});

返回的对象是一个构造函数,其功能与PouchDB相同,不同之处在于,无论何时调用它(例如,使用new ),默认情况下都会传递给定的选项.

Example Usage:

var MyMemPouch = PouchDB.defaults({
  adapter: 'memory'
});
// In-memory PouchDB
var myMemPouch = new MyMemPouch('dbname');

var MyPrefixedPouch = PouchDB.defaults({
  prefix: '/path/to/my/db/'
});
// db will be named '/path/to/my/db/dbname', useful for LevelDB
var myPrefixedPouch = new MyPrefixedPouch('dbname');

var HTTPPouch = PouchDB.defaults({
  prefix: 'http://example.org'
});

// db will be located at 'http://example.org/dbname'
var myHttpPouch = new HTTPPouch('dbname');

请注意特殊的构造函数选项prefix ,它在数据库名称后附加一个前缀,对于基于URL或基于文件的LevelDOWN路径名很有用.

支持所有构造函数选项 . 默认选项仍然可以单独覆盖.

本节介绍创作插件. For a list of third-party plugins, see Plugins, or for a list of first-party plugins that you can use to customize the PouchDB build, see Custom Builds.

编写插件很容易! 该API是:

PouchDB.plugin({
  methodName: myFunction
});

这会将db.methodName()添加到所有运行myFunction数据库中.它将始终在上下文中调用,因此在函数中, this指向数据库对象.

有一个PouchDB Plugin Seed项目 ,这是开始编写,构建和测试自己的插件的最快方法.

Example Usage:

PouchDB.plugin({
  sayHello : function () {
    console.log("Hello!");
  }
});
new PouchDB('foobar').sayHello(); // prints "Hello!"

或者,您可以传入一个采用PouchDB对象并对其执行所需操作的函数,而不是将对象传递给.plugin() . 您可以使用它来加载多个插件,添加适配器或将事件侦听器附加到PouchDB对象.

Example Usage:

PouchDB.plugin(function (PouchDB) {
  PouchDB.hello = 'world';
});
console.log(PouchDB.hello); // prints "world"

(很可能,如果您正在编写PouchDB插件,则将导出对象样式或函数样式的插件,以便您的用户可以将其附加到他们的PouchDB对象.)

Load Plugins from require()

您可以通过require()插件加载到PouchDB中.

var greet = {sayHello: function() { console.log("Hello!"); }};

var PouchDB = require('pouchdb').plugin(greet);

var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"

您还可以链接插件:

var greet = {sayHello: function() { console.log("Hello!"); }};
var manners = {thank: function(name) { console.log("Thank you, " + name); }};

var PouchDB = require('pouchdb')
  .plugin(greet)
  .plugin(manners);

var db = new PouchDB('foobar');
db.sayHello(); // prints "Hello!"
db.thank('Mom'); // prints "Thank you, Mom"

Example Plugin: Intercept Updates

插件的一个有用功能是在更新存储到PouchDB中之前对其进行拦截. 这样,插件可以验证数据对于应用程序是正确的,甚至可以在将文档提交到数据库之前对其进行更改.

拦截对PouchDB数据库的所有更新的最好方法是重写bulkDocs()方法 . 对PouchDB文档的所有更改最终都会通过bulkDocs()方法传递. 例如,对put()的调用将变成带有一个"批处理"一个文档的bulkDocs()调用.

因为PouchDB向插件作者保证所有数据更改最终都会通过bulkDocs()发生,所以它是应用程序或插件拦截更新的理想场所.

// Keep a reference to the "upstream" function.
var pouchBulkDocs = PouchDB.prototype.bulkDocs;
PouchDB.plugin({bulkDocs: validBulkDocs});

function validBulkDocs(body, options, callback) {
  if (typeof options == 'function') {
    callback = options
    options = {}
  }

  if (Array.isArray(body)) {
    var docs = body;
  } else {
    var docs = body.docs;
  }

  // All documents must have a .name field.
  for (var i = 0; i < docs.length; i++) {
    if (!docs[i].name) {
      var id = doc._id || '(no _id given)';
      return callback(new Error('Document is missing .name field: ' + id));
    }
  }

  // All documents check out. Pass them to PouchDB.
  return pouchBulkDocs.call(this, docs, options, callback);
}

如果有任何尝试存储未命名文档(包括在复制过程中更改的文档)的话,上述插件将返回错误.

注意:这是一个非常非常简单的验证示例. 例如,它的行为不像Apache CouchDB validate_doc_update() API.

PouchDB将调试模块用于细粒度的调试输出.

debug() API当前是PouchDB核心的一部分. 但是,在PouchDB v7.0.0中,它将被移到单独的插件中.

要启用调试模式,只需调用:

PouchDB.debug.enable('*');

在浏览器控制台中,您应该会看到类似以下内容的内容:

Coloured Log Output

在Node.js中,您还可以设置命令行标志:

DEBUG=pouchdb:* node myscript.js

您还可以启用特定模块的调试. 当前,我们只有pouchb:api (API级调用)和pouchdb:http (HTTP请求):

PouchDB.debug.enable('pouchdb:api'); // or
PouchDB.debug.enable('pouchdb:http');

这些设置将保存到浏览器的LocalStorage. 因此,要禁用它们,必须调用:

PouchDB.debug.disable();

除非您在应用程序代码中明确调用PouchDB.debug.enable()否则用户将看不到调试输出.

by  ICOPY.SITE