From commits-return-32901-archive-asf-public=cust-asf.ponee.io@couchdb.apache.org Fri Apr 13 07:43:20 2018 Return-Path: X-Original-To: archive-asf-public@cust-asf.ponee.io Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by mx-eu-01.ponee.io (Postfix) with SMTP id 82BFC180627 for ; Fri, 13 Apr 2018 07:43:19 +0200 (CEST) Received: (qmail 3669 invoked by uid 500); 13 Apr 2018 05:43:18 -0000 Mailing-List: contact commits-help@couchdb.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@couchdb.apache.org Delivered-To: mailing list commits@couchdb.apache.org Received: (qmail 3659 invoked by uid 99); 13 Apr 2018 05:43:18 -0000 Received: from pnap-us-west-generic-nat.apache.org (HELO spamd1-us-west.apache.org) (209.188.14.142) by apache.org (qpsmtpd/0.29) with ESMTP; Fri, 13 Apr 2018 05:43:18 +0000 Received: from localhost (localhost [127.0.0.1]) by spamd1-us-west.apache.org (ASF Mail Server at spamd1-us-west.apache.org) with ESMTP id 1320CC7DBB for ; Fri, 13 Apr 2018 05:43:18 +0000 (UTC) X-Virus-Scanned: Debian amavisd-new at spamd1-us-west.apache.org X-Spam-Flag: NO X-Spam-Score: -10.301 X-Spam-Level: X-Spam-Status: No, score=-10.301 tagged_above=-999 required=6.31 tests=[ENV_AND_HDR_SPF_MATCH=-0.5, RCVD_IN_DNSWL_MED=-2.3, SPF_PASS=-0.001, USER_IN_DEF_SPF_WL=-7.5] autolearn=disabled Received: from mx1-lw-eu.apache.org ([10.40.0.8]) by localhost (spamd1-us-west.apache.org [10.40.0.7]) (amavisd-new, port 10024) with ESMTP id cWdYfrtHUK2o for ; Fri, 13 Apr 2018 05:43:17 +0000 (UTC) Received: from mailrelay1-us-west.apache.org (mailrelay1-us-west.apache.org [209.188.14.139]) by mx1-lw-eu.apache.org (ASF Mail Server at mx1-lw-eu.apache.org) with ESMTP id 3DA9E5FB37 for ; Fri, 13 Apr 2018 05:43:16 +0000 (UTC) Received: from moin-vm.apache.org (moin-vm.apache.org [163.172.69.106]) by mailrelay1-us-west.apache.org (ASF Mail Server at mailrelay1-us-west.apache.org) with ESMTP id 40FCEE0117 for ; Fri, 13 Apr 2018 05:43:15 +0000 (UTC) Received: from moin-vm.apache.org (localhost [IPv6:::1]) by moin-vm.apache.org (ASF Mail Server at moin-vm.apache.org) with ESMTP id 9223180111 for ; Fri, 13 Apr 2018 07:43:14 +0200 (CEST) MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable From: Apache Wiki To: Apache Wiki Date: Fri, 13 Apr 2018 05:43:14 -0000 Message-ID: <152359819459.23109.7846407553587374668@moin-vm.apache.org> Subject: =?utf-8?q?=5BCouchdb_Wiki=5D_Update_of_=22HttpViewApi=22_by_JoanTouzet?= Auto-Submitted: auto-generated Dear wiki user, You have subscribed to a wiki page "Couchdb Wiki" for change notification. The page "HttpViewApi" has been deleted by JoanTouzet: https://wiki.apache.org/couchdb/HttpViewApi?action=3Ddiff&rev1=3D26&rev2=3D= 27 - #redirect HTTP_view_API - An introduction to the CouchDB HTTP view API. = - =3D=3D Basics =3D=3D - = - Views are the primary tool used for querying and reporting on Couch docum= ents. - = - Views are defined with Javascript functions. Here is the very simplest fu= nction: - = - {{{ - function(doc) { - emit(null, doc); - } - }}} - = - See [[Views]] for more information. - = - =3D=3D Creating Views =3D=3D - = - To create a permanent view, the functions must first be saved into specia= l ''design documents'' (well, they are not really special, we just call the= m special but in reality, they are regular documents, just with a special I= D). The IDs of design documents must begin with ''_design/'' and have a spe= cial views attribute that have a ''map'' member and an optional ''reduce'' = member to hold the view functions. All the views in one design document are= indexed whenever any of them gets queried. - = - A design document that defines ''all'', ''by_lastname'', and ''total_purc= hases'' views might look like this: - = - {{{ - { - "_id":"_design/company", - "_rev":"12345", - "language": "javascript", - "views": - { - "all": { - "map": "function(doc) { if (doc.Type =3D=3D 'customer') emit(null,= doc) }" - }, - "by_lastname": { - "map": "function(doc) { if (doc.Type =3D=3D 'customer') emit(doc.L= astName, doc) }" - }, - "total_purchases": { - "map": "function(doc) { if (doc.Type =3D=3D 'purchase') emit(doc.C= ustomer, doc.Amount) }", - "reduce": "function(keys, values) { return sum(values) }" - } - } - } - }}} - = - The ''language'' property tells CouchDB the language of the view function= s, which it uses to select the appropriate ViewServer (as specified in your= couch.ini file). The default is to assume Javascript, so this property can= be omitted for Javascript views. - = - =3D=3D Altering/Changing Views =3D=3D - = - To change a view or multiple view just alter the document (see HttpDocume= ntApi) they are stored in and save it as a new revision. - = - =3D=3D Access/Query =3D=3D - = - Once this document is saved into a database, then the ''all'' view can be= retrieved at the URL: - = - http://localhost:5984/database/_view/company/all - = - Example: - = - {{{ - GET /some_database/_view/company/all HTTP/1.0 - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - }}} - = - And will result in the following response: - = - {{{ - HTTP/1.1 200 OK - Date: Thu, 17 Aug 2006 05:39:28 +0000GMT - Content-Length: 318 - Connection: close - = - { - "total_rows": 3, - "offset": 0, - "rows": [{ - "id":"64ACF01B05F53ACFEC48C062A5D01D89", - "key": null, - "value": { - "LastName":"Katz", - "FirstName":"Damien", - "Address":"2407 Sawyer drive, Charlotte NC", - "Phone":012555754211 - } - }, { - "id":"5D01D8964ACF01B05F53ACFEC48C062A", - "key": null, - "value": { - "LastName":"Kerr", - "FirstName":"Wayne", - "Address":"123 Fake st., such and such", - "Phone":88721320939 - } - }, { - "id":"EC48C062A5D01D8964ACF01B05F53ACF", - "key": null, - "value": - { - "LastName":"McCracken", - "FirstName":"Phil", - "Address":"1234 Fake st., such and such", - "Phone":7766552342 - } - } - ] - } - }}} - = - =3D=3D Temporary Views =3D=3D - = - One-off queries (eg. views you don't want to save in the CouchDB database= ) can be done via the special view ''_temp_view''. Temporary views are only= good during development. Final code should not rely on them as they are ve= ry expensive to compute each time they get called and they get increasingly= slower the more data you have in a database. If you think you can't solve = something in a permanent view that you can solve in an ad-hoc view, you mig= ht want to reconsider. (TODO: add typical examples and solutions). - = - {{{ - POST /some_database/_temp_view HTTP/1.0 - Content-Length: 48 - Date: Mon, 10 Sep 2007 17:11:10 +0200 - Content-Type: application/json - = - { - "map" : "function(doc) { if (doc.foo=3D=3D'bar') { emit(null, doc.foo);= } }" - } - = - }}} - = - Could result in the following response: - = - {{{ - { - "total_rows": 1, - "offset": 0, - "rows": [{ - "id": "AE1AD84316B903AD46EF396CAFE8E50F", - "key": null, - "foo": "bar" - } - ] - } - }}} - = - =3D=3D Querying Options =3D=3D - = - Columns can be a list of values, there is no set limit to the number of v= alues or amount of data that columns can hold. - = - The following URL query arguments are allowed: - = - * GET - * key=3Dkeyvalue - * startkey=3Dkeyvalue - * startkey_docid=3Ddocid - * endkey=3Dkeyvalue - * endkey_docid=3Ddocid - * count=3Dmax rows to return - * update=3Dfalse - * descending=3Dtrue - * skip=3Dnumber of rows to skip - * group=3Dtrue ''Version 0.8.0 and forward'' - * reduce=3Dfalse ''Trunk only (0.9)'' - * include_docs=3Dtrue ''Trunk only (0.9)'' - * POST - * {"keys": ["key1", "key2", ...]} ''Trunk only (0.9)'' - = - ''key'', ''startkey'', and ''endkey'' need to be properly JSON encoded va= lues (for example, startkey=3D"string" for a string value). - = - A JSON structure of ''{"keys": ["key1", "key2", ...]}'' can be posted to = any user defined view or ''_all_docs'' to retrieve just the view rows match= ing that set of keys. Rows are returned in the order of the keys specified.= Combining this feature with ''include_docs=3Dtrue'' results in the so-call= ed ''multi-document-fetch'' feature. - = - If you specify ''?count=3D0'' you don't get any data, but all meta-data f= or this View. The number of documents in this View for example. If ''count'= ' is specified as a negative number, you will receive that many documents p= rior to the specified ''startkey''. - = - The ''skip'' option should only be used with small values, as skipping a = large range of documents this way is inefficient (it scans the index from t= he startkey and then skips N elements, but still needs to read all the inde= x values to do that). For efficient paging use ''startkey'' and/or ''startk= ey_docid''. - = - The ''update'' option can be used for higher performance at the cost of p= ossibly not seeing the all latest data. If you set the ''update'' option to= ''false'', CouchDB will not perform any refreshing on the view that may be= necessary. - = - View rows are sorted by the key; specifying ''descending=3Dtrue'' will re= verse their order. Note that the ''descending'' option is applied before an= y key filtering, so you may need to swap the values of the ''startkey'' and= ''endkey'' options to get the expected results. The sorting itself is desc= ribed in ViewCollation. - = - The ''group'' option controls whether the reduce function reduces to a se= t of distinct keys or to a single result row. - = - If a view contains both a map and reduce function, querying that view wil= l by default return the result of the reduce function. The result of the ma= p function only may be retrieved by passing ''reduce=3Dfalse'' as a query p= arameter. - = - The ''include_docs'' option will include the associated document. Althoug= h, the user should keep in mind that there is a race condition when using t= his option. It is possible that between reading the view data and fetching = the corresponding document that the document has changed. If you want to al= leviate such concerns you should emit an object with a _rev attribute as in= ''emit(key, {"_rev": doc._rev})''. This alleviates the race condition but = leaves the possiblity that the returned document has been deleted (in which= case, it includes the ''"_deleted": true'' attribute). - = - = - =3D=3D Debugging Views =3D=3D - = - When creating views, CouchDB will check the syntax of the submitted JSON,= but the view functions themselves will not be syntax checked by the Javasc= ript interpreter. And if any one of the view functions has a syntax error, = none of the view functions in that design document will execute. Perhaps te= st your functions in a temporary view before saving them in the database. - = - As of r660140 there is a log function available in the views, which logs = to the couch.log. It can be helpful for debugging but hinders performance, = so it should be used sparingly in production systems. - = - {{{ - { - "map": "function(doc) { log(doc); }" - } - }}} -=20