[clouchdb-cvs] CVS clouchdb/public_html
peddy
peddy at common-lisp.net
Sat Mar 1 19:19:17 UTC 2008
Update of /project/clouchdb/cvsroot/clouchdb/public_html
In directory clnet:/tmp/cvs-serv28981/public_html
Modified Files:
index.html style.css
Log Message:
- Updated docs with complex view key info
- Updated examples with complex view examples
--- /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/02/18 03:16:01 1.16
+++ /project/clouchdb/cvsroot/clouchdb/public_html/index.html 2008/03/01 19:19:16 1.17
@@ -219,8 +219,8 @@
<p>
NB: If you try these examples I suggest also viewing the results via
CouchDb's bulit-in HTML UI
- at <a href="http://localhost:5894/_utils/browse/index.html">http://localhost:8888/_utils/browse/index.html</a>,
- (or <a href="http://localhost:8888/_utils/browse/index.html">http://localhost:5984/_utils/browse/index.html</a>
+ at <a href="http://localhost:5984/_utils/browse/index.html">http://localhost:5894/_utils/browse/index.html</a>,
+ (or <a href="http://localhost:8888/_utils/browse/index.html">http://localhost:8888/_utils/browse/index.html</a>
if you're using ClouchDb versions prior to 7.2), of course you'll
need to adjust the URL for the actual CouchDb server and port in
use.
@@ -302,11 +302,11 @@
;; Get revision information for this document (formatted for legibility)
CLOUCHDB-USER> <b>(get-document "someid" :revision-info t)</b>
((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green")
- (:|_rev|S_INFO
- ((:|rev| . "4275808446") (:STATUS . "disk"))
- ((:|rev| . "3181950830") (:STATUS . "disk"))))
-;; Since the first revision is still available (:status . "disk") we
-;; can still retrieve it
+ (:|_revs_info|
+ ((:|rev| . "4275808446") (:|status| . "disk"))
+ ((:|rev| . "3181950830") (:|status| . "disk"))))
+;; Since the first revision is still available (i.e., :|status| == "disk")
+;; we can still retrieve it:
CLOUCHDB-USER> <b>(get-document "someid" :revision "3181950830")</b>
((:|_id| . "someid") (:|_rev| . "3181950830") (:SIZE . "large") (:COLOR . "blue"))
@@ -317,11 +317,11 @@
(:tags . ("country" "European"))
;; Field using map property value:
(:demographics . ((:population . 10230000)
- ;; A nested map property:
- (:religion . ((:agnostic . 0.59)
- (:roman-catholic . 0.26)
- (:protestant . 2.5)))
- (:political-system . "democracy"))))
+ ;; A nested map property:
+ (:religion . ((:agnostic . 0.59)
+ (:roman-catholic . 0.26)
+ (:protestant . 2.5)))
+ (:political-system . "democracy"))))
:id "czechrepublic")</b>
((:|ok| . T) (:|id| . "czechrepublic") (:|rev| . "4272625130"))
;; Let's see what this document looks like (formatted for legibility)
@@ -336,12 +336,12 @@
((:TOTAL_ROWS . 3) (:OFFSET . 0)
(:ROWS
((:|id| . "C731D3A3698DA144FB35EDA9737917F2") (:KEY . "C731D3A3698DA144FB35EDA9737917F2")
- (:VALUE (:|rev| . "3363852140")))
- ((:|id| . "czechrepublic") (:KEY . "czechrepublic") (:VALUE (:|rev| . "4272625130")))
- ((:|id| . "someid") (:KEY . "someid") (:VALUE (:|rev| . "4275808446")))))
+ (:|value| (:|rev| . "3363852140")))
+ ((:|id| . "czechrepublic") (:KEY . "czechrepublic") (:|value| (:|rev| . "4272625130")))
+ ((:|id| . "someid") (:KEY . "someid") (:|value| (:|rev| . "4275808446")))))
</pre>
-<h4>Example 3</h4>
+<h4><a name="example-3">Example 3</a></h4>
<p>Demonstrating:</p>
<ul>
@@ -369,46 +369,86 @@
(:country . "NL"))
:id "amst") </b>
((:|ok| . T) (:|id| . "amst") (:|rev| . "3679905075"))
+CLOUCHDB-USER> <b>(create-document '((:city . "Rotterdam")
+ (:country . "NL"))
+ :id "rott") </b>
+((:|ok| . T) (:|id| . "rott") (:|rev| . "46041399"))
CLOUCHDB-USER> <b>(create-document '((:city . "Chicago")
(:country . "US"))
:id "chi") </b>
((:|ok| . T) (:|id| . "chi") (:|rev| . "1627558845"))
;; Create a persistent view document to find cities in the
-;; Netherlands and also to find cities by country key.
+;; Netherlands, cities by country key, and cities by country
+;; and city.
+
;; Note: Expressions within the (ps) expressions are <a href="http://www.cliki.net/Parenscript/">Parenscript</a>,
-;; a lispy way to generate JavaScript.
+;; a lispy way to generate JavaScript. Unquoted keyword symbols in Lisp
+;; field names should be referenced in Parenscript with the double
+;; asterix names, as in the examples below. This is because JavaScript
+;; is case sensitive and unquoted Lisp symbols are converted to upper
+;; case. The double asterix syntax causes Parenscript to generate
+;; upper case JavaScript property names.
+
CLOUCHDB-USER> <b>(create-view "cities"
+ ;; Index of cities in the Netherlands
+ (cons "nl"
+ (ps (lambda (doc)
+ (with-slots (*country* *city*) doc
+ (if (eql "NL" *country*)
+ (map *city* doc))))))
+ ;; Index by country
(cons "country"
(ps (lambda (doc)
- (with-slots (country) doc
- (map country doc)))))
- (cons "nl"
+ (with-slots (*country*) doc
+ (map *country* doc)))))
+ ;; Index by country and city
+ (cons "multi"
(ps (lambda (doc)
- (with-slots (country) doc
- (if (eql "NL" country)
- (map country doc)))))))</b>
+ (with-slots (*country* *city*) doc
+ (map (list *country* *city*) doc))))))</b>
((:|ok| . T) (:|id| . "_design/cities") (:|rev| . "3690565831"))
;; Invoke "nl" view to find cities in the Netherlands
CLOUCHDB-USER> <b>(invoke-view "cities" "nl")</b>
-((:TOTAL_ROWS . 1) (:OFFSET . 0)
- (:ROWS
- ((:|id| . "amst") (:KEY . "NL") (:VALUE (:|_id| . "amst")
- (:|_rev| . "3679905075") (:CITY . "Amsterdam") (:COUNTRY . "NL")))))
+((:|total_rows| . 2) (:|offset| . 0)
+ (:|rows|
+ ((:|id| . "amst") (:|key| . "Amsterdam") (:|value| (:|_id| . "amst")
+ (:|_rev| . "3679905075") (:CITY . "Amsterdam") (:COUNTRY . "NL")))
+ ((:|id| . "rott") (:|key| . "Rotterdam") (:|value| (:|_id| . "rott")
+ (:|_rev| . "46041399") (:CITY . "Rotterdam") (:COUNTRY . "NL")))))
+
+;; Use "nl" view to find a specific city in the Netherlands
+CLOUCHDB-USER> <b>(invoke-view "cities" "nl" :key "Rotterdam")</b>
+((:|total_rows| . 2) (:|offset| . 0)
+ (:|rows|
+ ((:|id| . "rott") (:|key| . "Rotterdam") (:|value| (:|_id| . "rott")
+ (:|_rev| . "46041399") (:CITY . "Rotterdam") (:COUNTRY . "NL")))))
-;; Invoke "country" view created above and search for US cities
+;; Invoke "country" view to search for US cities
CLOUCHDB-USER> <b>(invoke-view "cities" "country" :key "US")</b>
-((:TOTAL_ROWS . 3) (:OFFSET . 1)
- (:ROWS
- ((:|id| . "chi") (:KEY . "US") (:VALUE (:|_id| . "chi")
+((:|total_rows| . 3) (:|offset| . 1)
+ (:|rows|
+ ((:|id| . "chi") (:|key| . "US") (:|value| (:|_id| . "chi")
(:|_rev| . "1627558845") (:CITY . "Chicago") (:COUNTRY . "US")))
- ((:|id| . "nyc") (:KEY . "US") (:VALUE (:|_id| . "nyc")
+ ((:|id| . "nyc") (:|key| . "US") (:|value| (:|_id| . "nyc")
(:|_rev| . "1023292373") (:CITY . "New York City") (:COUNTRY . "US")))))
-;; Note: the two responses above have been formatted for legibility. Also,
-;; see CouchDb documentation for why 3 is returned for TOTAL_ROWS when
-;; there are only two results.
+;; Find the US city Chicago using the "multi" index:
+CLOUCHDB-USER> <b>(invoke-view "cities" "multi" :key '("US" "Chicago"))</b>
+((:|total_rows| . 3) (:|offset| . 1)
+ (:|rows|
+ ((:|id| . "chi") (:|key| . "US") (:|value| (:|_id| . "chi")
+ (:|_rev| . "1627558845") (:CITY . "Chicago") (:COUNTRY . "US")))))
+
+;; Use "multi" index to find all cities with country codes that start with "N"
+CLOUCHDB-USER> <b>(invoke-view "cities" "multi" :start-key '("N") :end-key '("O"))</b>
+((:|total_rows| . 3) (:|offset| . 0)
+ (:|rows|
+ ((:|id| . "amst") (:|key| . "Amsterdam") (:|value| (:|_id| . "amst")
+ (:|_rev| . "3679905075") (:CITY . "Amsterdam") (:COUNTRY . "NL")))
+ ((:|id| . "rott") (:|key| . "Rotterdam") (:|value| (:|_id| . "rott")
+ (:|_rev| . "46041399") (:CITY . "Rotterdam") (:COUNTRY . "NL"))))))
</pre>
@@ -887,6 +927,11 @@
matches the keyword field name in the document, wild card symbols,
or a function.
</p>
+<p>
+ Note that this function does not represent any CouchDb API, nor does
+ it communicate with the database other than when functions are used
+ in the query and these functions communicate with the database.
+</p>
<table summary="query operators">
<caption><em>Query Operators</em></caption>
<tr>
@@ -910,13 +955,13 @@
<tr>
<td>function</td>
<td>
- The function should accept a single parameter, which will
- contain the value of the previous match or the initial document
- if the function is the first element in the query list. Query
- operators following the function are applied to the result of
- the function or, if the function is the last operator in the
- query, the function return value is collected in the
- query-document results list.
+ The function should accept a single parameter. This parameter
+ will contain the value matched by the previous query term, or
+ the initial document if the function is the first element in
+ the query list. Query operators following the function are
+ applied to the result of the function or, if the function is
+ the last operator in the query, the function return value is
+ collected in the query-document results list.
</td>
</tr>
</table>
@@ -970,7 +1015,7 @@
<b>=></b> (((:IS (:DIFFERENT . "Different Deep Value"))) "Deep Value")
-;; Query using a function
+;; Functions
;;
;; Query the results of (<a href="#sym-get-all-documents">get-all-documents</a>), extracting all
;; document :|id| values in the :|rows| property.
@@ -1019,13 +1064,46 @@
<hr/><h4><a name="views-api-reference">Views API</a></h4>
<p>
- Views are the mechanism with which documents are queried in
- CouchDb. There are two types of views in CouchDb: ad hoc and
- persistent. As you might expect, persistent views are stored in the
- database. Ad hoc views are not, they are sent from the client each
- time they're used. Native CouchDb views are expressed in JavaScript
- though it is not necessary to use JavaScript directly thanks
- to <a href="http://www.cliki.net/Parenscript/">Parenscript</a>.
+ Views are the query mechanism for CouchDb. There are two types of
+ views in CouchDb: ad hoc and persistent. As you might expect
+ persistent views are stored in the database. Ad hoc views are not,
+ they are sent from the client each time they're used. Native CouchDb
+ views are expressed in JavaScript. While it is possible to use
+ JavaScript with the Clouchdb API, it may be more natural to use the
+ <a href="http://www.cliki.net/Parenscript/">Parenscript</a> library
+ instead. Parenscript is library for generating JavaScript using Lisp
+ syntax.
+</p>
+<p>
+ Note that CouchDb and JavaScript are case sensitivie. Field names in
+ documents created using un-quoted keyword symbol field names (e.g.,
+ :name) will be converted to upper case by Lisp and result in upper
+ case field names in CouchDb and JavaScript.
+</p>
+<p>
+<table summary="query operators" width="80%" align="center">
+ <caption><em>Field Name Case Comparison</em></caption>
+ <tr>
+ <th>Clouchdb</th>
+ <th>Parenscript</th>
+ <th>CouchDb/JavaScript</th>
+ </tr>
+ <tr>
+ <td>:name, :NAME, :NaMe</td>
+ <td>*name*, *NAME* *NaMe*</td>
+ <td>NAME</td>
+ </tr>
+ <tr>
+ <td>:|name|</td>
+ <td>name</td>
+ <td>name</td>
+ </tr>
+ <tr>
+ <td>:|mixedCase|</td>
+ <td>mixed-case</td>
+ <td>mixedCase</td>
+ </tr>
+</table>
</p>
<p>
@@ -1051,12 +1129,11 @@
<p>
Keyword parameters
</p>
-
<ul>
<li>
<b>key</b> A value to match against the document property or
properties mapped in the view. Only documents matching this
- value are returned.
+ value are returned. Values may be strings or s-expresions.
</li>
<li>
<b>start-key</b> Return documents with mapped keys greater than or
@@ -1091,7 +1168,7 @@
</p>
<pre class="code">
(create-document '((:name . "Laraby")))
-(ad-hoc-view "function(doc) { if (doc.name == 'Laraby') { map(null,doc.name) } }")
+(ad-hoc-view "function(doc) { if (doc.NAME == 'Laraby') { map(null,doc.NAME) } }")
</pre>
<p>
@@ -1103,8 +1180,8 @@
<pre class="code">
(create-document '((:name . "Laraby")))
(ad-hoc-view (ps (lambda (doc)
- (with-slots (name) doc
- (if (eql name "Laraby")
+ (with-slots (*name*) doc
+ (if (eql *name* "Laraby")
(map nil doc))))))
</pre>
<p>
@@ -1119,17 +1196,20 @@
</p>
<pre class="code">
(ad-hoc-view (ps (lambda (doc)
- (if (eql doc.name "Laraby")
+ (if (eql doc.*name* "Laraby")
(map nil doc))))))
</pre>
-<p>See (<a href="#sym-create-view">create-view</a>) </p>
+<p>See (<a href="#sym-create-view">create-view</a>) and <a href="#example-3">Example 3</a></p>
</blockquote>
<p>[Function]<br />
<a name="sym-create-view"><b>create-view</b></a> {view-definition}*</p>
<blockquote>
<p>
-Creates a view document containing one or more view definitions
+ Creates a view document containing one or more view definitions. The
+ view definitions may be specified in a JavaScript string
+ or <a href="http://www.cliki.net/Parenscript/">Parenscript</a>
+ s-expresions.
</p>
<p>
Example:
@@ -1149,6 +1229,8 @@
</pre>
<p>
See (<a href="#sym-invoke-view">invoke-view</a>)
+(<a href="#sym-ad-hoc-view">ad-hoc-view</a>)
+and <a href="#example-3">Example 3</a>
</p>
</blockquote>
@@ -1234,7 +1316,10 @@
(invoke-view <b>"names" "name" :key "Laraby"</b>)
</pre>
<p>
-See (<a href="#sym-create-view">create-view</a>) (<a href="#sym-ad-hoc-view">ad-hoc-view</a>)</p>
+See (<a href="#sym-create-view">create-view</a>)
+(<a href="#sym-ad-hoc-view">ad-hoc-view</a>)
+and <a href="#example-3">Example 3</a>
+</p>
</blockquote>
--- /project/clouchdb/cvsroot/clouchdb/public_html/style.css 2007/12/01 14:19:59 1.1.1.1
+++ /project/clouchdb/cvsroot/clouchdb/public_html/style.css 2008/03/01 19:19:16 1.2
@@ -33,6 +33,7 @@
padding: 7px;
background-color: #DDFFEE;
border: 1px solid #99CCBB;
+ font-size: 1.2em;
}
p.def {
More information about the clouchdb-cvs
mailing list