clouchdb

Representation of Field Names and Values

(asdf-install:install 'clouchdb)  
(asdf:oos 'asdf:load-op '#:clouchdb)

(asdf:oos 'asdf:load-op '#:clouchdb-tests)
(in-package :clouchdb-tests)
;; If CouchDb is running on a different host
(set-connection :host "db-host")
(run-all-tests)

(asdf:oos 'asdf:load-op '#:clouchdb-examples)
(in-package :clouchdb-examples)

cvs -z3 -d :pserver:anonymous:anonymous@common-lisp.net:/project/clouchdb/cvsroot co clouchdb

;; Create a package to try out clouchdb
CL-USER> (defpackage :clouchdb-user (:use :cl :clouchdb))
#<Package "CLOUCHDB-USER">

CL-USER> (in-package :clouchdb-user)
#<Package "CLOUCHDB-USER">

;; If CouchDb is running on a different host set that host
;; name (default is "localhost"), also set the database name
;; to be used in this session (default database name is "default")
CLOUCHDB-USER> (set-connection :host "odeon" :db-name "test-db") 
; No value

;; Get CouchDb Server Information by specifying a nil DB name
CLOUCHDB-USER> (get-db-info :db-name nil)
((:|couchdb| . "Welcome") (:|version| . "0.8.0-incubating"))

;; Create database "test-db", which we named above
CLOUCHDB-USER> (create-db)
((:|ok| . T))

;; Create a document with one field, and give it an ID of "gjc"
CLOUCHDB-USER> (create-document '((:name . "Gaius Julius Caesar")) :id "gjc")
((:|ok| . T) (:|id| . "gjc") (:|rev| . "1479031852"))

;; Fetch the document we just created 
CLOUCHDB-USER> (get-document "gjc")
((:|_id| . "gjc") (:|_rev| . "1479031852") (:NAME . "Gaius Julius Caesar"))

;; Add a field to "gjc"
CLOUCHDB-USER> (put-document (cons '(:lover . "Servilia Caepionis") *))
((:|ok| . T) (:|id| . "gjc") (:|rev| . "1460552879"))

;; Get the updated document
CLOUCHDB-USER> (get-document "gjc")
((:|_id| . "gjc") (:|_rev| . "1460552879") (:LOVER . "Servilia Caepionis") 
 (:NAME . "Gaius Julius Caesar"))

;; Create, or drop and recreate, the current database
CLOUCHDB-USER> (create-db :if-exists :recreate)
((:|ok| . T))

;; Create a document that will have it's ID assigned by the CouchDb server
CLOUCHDB-USER> (create-document '((:size . "medium") (:color . "blue")))
((:|ok| . T) (:|id| . "C731D3A3698DA144FB35EDA9737917F2") (:|rev| . "3363852140"))

;; CouchDb generated IDs are too large to use easily in an
;; interactive example like this, so create another document
;; with a shorter ID to demonstrate property value updates
CLOUCHDB-USER> (create-document '((:size . "large") (:color . "blue")) 
                                :id "someid")
((:|ok| . T) (:|id| . "someid") (:|rev| . "3181950830"))

;; Change :color property
CLOUCHDB-USER> (put-document 
                 (set-document-property (get-document "someid")
                                        :color "green")
((:|ok| . T) (:|id| . "someid") (:|rev| . "4275808446"))

;; Show that the new property stuck
CLOUCHDB-USER> (get-document "someid")
((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green"))

;; Get revision information for this document
CLOUCHDB-USER> (get-document "someid" :revision-info t)
((:|_id| . "someid") (:|_rev| . "4275808446") (:SIZE . "large") (:COLOR . "green") 
 (:|_revs_info|
  ((:|rev| . "4275808446") (:|status| . "available")) 
  ((:|rev| . "3181950830") (:|status| . "available"))))

;; Since the first revision is still available we can still retrieve it:
CLOUCHDB-USER> (get-document "someid" :revision "3181950830")
((:|_id| . "someid") (:|_rev| . "3181950830") (:SIZE . "large") (:COLOR . "blue"))

;; In the following document, the :tags field has an array value,
;; the :demographics field has a map value, and the :religion map 
;; key also has an associated map value.
CLOUCHDB-USER> (create-document '((:name . "Czech Republic")
                                  (: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"))))
                                :id "czechrepublic")
((:|ok| . T) (:|id| . "czechrepublic") (:|rev| . "4272625130"))

;; Let's see what this document looks like
CLOUCHDB-USER> (get-document "czechrepublic")
((:|_id| . "czechrepublic") (:|_rev| . "3929202819") 
 (:NAME . "Czech Republic") (:TAGS "country" "european") 
 (:DEMOGRAPHICS (:POPULATION . 10230000) 
                (:RELIGION (:AGNOSTIC . 0.59) (:ROMAN-CATHOLIC . 0.26) (:PROTESTANT . 2.5)) 
                (:POLITICAL-SYSTEM . "democracy")))

;; Get all documents in current database
CLOUCHDB-USER> (get-all-documents)
((:|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")))))

;; Get just the ID values for all documents in the current database
(query-document '(:|rows| :|id|) (get-all-documents))
("someid" "czechrepublic" "C731D3A3698DA144FB35EDA9737917F2")

;; Create current database if it doesn't already exist.
;; An (:IGNORED . T) result indicates that the create
;; was ignored because the database already existed.
CLOUCHDB-USER> (create-db :if-exists :ignore)
((:|ok| . T) (:IGNORED . T))

;; Create some documents representing various cities and their 
;; associated countries.
CLOUCHDB-USER> (create-document '((:city . "New York City")
                                  (:country . "US"))
                                :id "nyc")
((:|ok| . T) (:|id| . "nyc") (:|rev| . "1023292373"))
CLOUCHDB-USER> (create-document '((:city . "Amsterdam")
                                  (:country . "NL"))
                                :id "amst") 
((:|ok| . T) (:|id| . "amst") (:|rev| . "3679905075"))
CLOUCHDB-USER> (create-document '((:city . "Rotterdam")
                                  (:country . "NL"))
                                :id "rott") 
((:|ok| . T) (:|id| . "rott") (:|rev| . "46041399"))
CLOUCHDB-USER> (create-document '((:city . "Chicago")
                                  (:country . "US"))
                                :id "chi") 
((:|ok| . T) (:|id| . "chi") (:|rev| . "1627558845"))

;; Create a persistent view document to find cities in the
;; Netherlands, cities by country key, and cities by country 
;; and city. 

;; Note: Expressions within the (ps-view) macro are Parenscript,
;; 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> (create-ps-view "cities"
                 ;; Index of cities in the Netherlands
                 (ps-view ("nl")
                   (defun map (doc)
                     (with-slots (*country* *city*) doc
                       (if (eql "NL" *country*)
                         (emit *city* doc)))))
                 ;; Index by country
                 (ps-view ("country")
                   (defun map (doc)
                     (with-slots (*country*) doc
                       (emit *country* doc)))))
                 ;; Index by country and city
                 (ps-view ("multi")
                   (defun map (doc)
                     (with-slots (*country* *city*) doc
                       (emit (list *country* *city*) doc))))))
((:|ok| . T) (:|id| . "_design/cities") (:|rev| . "3690565831"))

;; Invoke "nl" view to find cities in the Netherlands
CLOUCHDB-USER> (invoke-view "cities" "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> (invoke-view "cities" "nl" :key "Rotterdam")
((:|total_rows| . 2) (:|offset| . 0) 
 (:|rows| 
  ((:|id| . "rott") (:|key| . "Rotterdam") (:|value| (:|_id| . "rott") 
   (:|_rev| . "46041399") (:CITY . "Rotterdam") (:COUNTRY . "NL")))))

;; Invoke "country" view to search for US cities
CLOUCHDB-USER> (invoke-view "cities" "country" :key "US")
((:|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") 
   (:|_rev| . "1023292373") (:CITY . "New York City") (:COUNTRY . "US")))))

;; Find the US city Chicago using the "multi" index:
CLOUCHDB-USER> (invoke-view "cities" "multi" :key '("US" "Chicago"))
((:|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> (invoke-view "cities" "multi" :start-key '("N") :end-key '("O"))
((:|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"))))))

;; Create the database named in the current connection settings
(set-connection :db-name "tvland")
(create-db)
=> ((:|ok| . T))

;; Specify name of database to create, if it already exists
;; then ignore the request (don't generate error, don't
;; recreate database), return (:ignored . T) if database did
;; exist
(create-db :db-name "tvland" :if-exists :ignore)
=> ((:|ok| . T) (:IGNORED . T))

;; Create named db, if it already exists, drop it and 
;; recreate it
(create-db :db-name "tvland" :if-exists :recreate)
=> ((:|ok| . T))

;; Create the database named in the current connection settings
(set-connection :db-name "tvland")
(delete-db)
=> ((:|ok| . T))

;; Specify name of database to delete, if it doesn't exist
;; then ignore the request (don't generate error), return 
;; ((:ERROR . "not_found") (:REASON . "missing")) if 
;; database did not exist
(delete-db :db-name "tvland" :if-missing :ignore)
=> ((:ERROR . "not_found") (:REASON . "missing"))

;; Create a function that adds or updates a timestamp field in a
;; document and returns the modified document
(defun time-stamper (doc) 
  (set-document-property doc :timestamp (get-universal-time)))

;; Cause time-stamper to be invoked with each document as
;; it's updated or created
(setf *document-fetch-fn* #'time-stamper)

;; Test the new time stamping feature
(create-document '((:hello . "there")) :id "test")
=> ((:|ok| . T) (:|id| . "test") (:|rev| . "3721228336"))

;; The new document should have been created with a timestamp, 
;; let's see if it worked:
(get-document "test")
=> ((:|_id| . "test") (:|_rev| . "3721228336") (:TIMESTAMP . 3422649324) 
  (:HELLO . "there"))

(get-db-info)
=> ((:DB_NAME . "test-db") (:DOC_COUNT . 3) (:UPDATE_SEQ . 4))

(list-dbs)
=> ("default" "example1" "example2" "example3")

;; Get document from specified host and database
(with-connection (:host "cornichon.cucumber.net" :db-name "rfc")
  (get-document "2616"))

;; Copy document identified by "someid" from database "otherdb" to 
;; current database, use "copy-of-someid" for copied document ID.
(put-document
  (with-connection (:db-name "otherdb")
    (get-document "someid"))
  :id "copy-of-someid")

(create-document '((:name . "Max") (:agent . 86)) :id "agent86")
(get-document "agent86")
=> ((:|_id| . "agent86") (:|_rev| . "3674093994") (:NAME . "Max") (:AGENT . 86))

(create-document '((:string . "String Value")
                   (:number . 42.0)
                   (:list . (milk eggs "green beans"))
                   (:alist . ((:string . "Another String")
                              (:size . 3)
                              (:false . t)
                              (:list . ("un" "deux" "trois"))
                              (:another-alist . ((a . "A") (b . "B")))))))

(create-document '((:name . "Maxwell Smart") (:agent . 86)) :id "max")
=> ((:|ok| . T) (:|id| . "max") (:|rev| . "3789799231"))

(get-document "max")
=> ((:|_id| . "max") (:|_rev| . "3789799231") (:NAME . "Maxwell Smart") (:AGENT . 86))

  ;; Lower case
  (as-keyword-symbol "lowercase")
  => :|lowercase|

  ;; Upper case
  (as-keyword-symbol "UPPER-CASE")
  => :UPPER-CASE

  ;; Mixed case
  (as-keyword-symbol "MixedCase")
  =>:|MixedCase|

  ;; Upper case
  (as-field-name-string :case)
  => "CASE"

  ;; Lower case
  (as-field-name-string :|case|)
  => "case"

  ;; Mixed case
  (as-field-name-string :|MixedCase|)
  => "MixedCase"

(create-document '((:string . "string") 
                   (:number . 42)
                   (:array . ("one" 2 "nine"))
                   (:map . ((:foo . "bar")
                            (:size . 3)
                            (:colors . ("red" "blue" "green")))))
                 :id "example")

(create-document '((:name . "Maxwell Smart") (:agent . 86)) :id "max")

(document-property :name (get-document "max"))
=> "Maxwell Smart"

;; document-property is setf-able, but note that the result is
;; not persisted automatically (use put-document for that)

(setf (document-property :name (get-document "max")) "Max")
=>((:|_id| . "max") (:|_rev| . "1213746364") (:NAME . "Max") (:AGENT . 86))

(document-property :name (get-document "max"))
=> "Maxwell Smart"

(put-document (setf (document-property :name (get-document "max")) "Max"))
=>((:|ok| . T) (:|id| . "max") (:|rev| . "1262996208"))

(get-document "max")
=>((:|_id| . "max") (:|_rev| . "1262996208") (:NAME . "Max") (:AGENT . 86))

;; Create a document, let server assign an ID
(post-document '((:field . "value")))

=> ((:|ok| . T) (:|id| . "4A0FF20F6AE5168B771BC41D4557F650") (:|rev| . "16873930"))

;; Create document "A"
(put-document '((:name . "Larrabee")) :id "A")

;; Copy document A to new document "B"
(put-document (get-document "A") :id "B")

;; Add field to document "B"
(put-document (cons '(:new-field . "new-value")) (get-document "B"))

;; Secret Agent document to query
(setf *agents* '((:control
                  (((:name . "Max") (:agent . 86)) 
                   ((:name . "Ninety Nine") (:agent . 99))
                   ((:agent . 44))
                   ((:agent . 13))
                   ((:name . "Hymie"))
                   ((:name . "Larrabee"))
                   ((:name . "Fang") (:agent . "K-9"))))
                 (:kaos
                  (((:name . "Siegfried"))
                   ((:name . "Shtarker"))
                   ((:name . "The Claw"))
                   ((:name . "Colonel von Klaus"))))))

;; Get the agent values for all Control agents that have these values
(query-document '(:control :agent) *agents*)
=> ("K-9" 13 44 99 86)

;; Get names of agents that work for Control or Kaos, for agents who have names
(query-document '(:* :name) *agents*)
=> ("Colonel von Klaus" "The Claw" "Shtarker" "Siegfried" "Fang" "Larrabee" 
  "Hymie" "Ninety Nine" "Max")

;; Get a value from a deeply nested position
(query-document '(:** :value) '((:a . 
                                 ((:very . 
                                   ((:deeply . 
                                     ((:nested . 
                                       ((:value . "Deep Value")))))))))))
=> ("Deep Value")

;; Use the recursive wild card operator to retrieve values from any level
(query-document '(:** :value) 
                '((:one . 
                   ((:very . 
                     ((:deeply . 
                       ((:nested . 
                         ((:value . "Deep Value")))))))))
                  (:this . 
                    ((:value . 
                      ((:is . 
                        ((:different . "Different Deep Value")))))))))

=> (((:IS (:DIFFERENT . "Different Deep Value"))) "Deep Value")

;; Functions
;;
;; Query the results of (get-all-documents), extracting all
;; document :|id| values in the :|rows| property.
;; 
;; Use the clouchdb function (get-document) to look up the 
;; corresponding document for each value of :|id|. The form below will 
;; return the value of the :name property for all documents in the
;; current database that have one or more :name properties

(query-document `(:|rows| :|id| ,#'get-document :** :name) (get-all-documents))

(create-document '((:name . "Maxwell Smart") (:agent . 86)) :id "max")

(document-property :name (get-document "max"))
=> "Maxwell Smart"

;; Modify existing :name value and add :employer property
(put-document 
  (set-document-property (get-document "max")
                         :name "Maxwell Smart, Secret Agent"
                         :employer "Control"))
(get-document "max")
=> ((:|_id| . "max") (:|_rev| . "655510103") (:EMPLOYER . "Control")
    (:NAME . "Maxwell Smart, Secret Agent") (:AGENT . 86))

(create-document '((:name . "Larrabee")))

(ad-hoc-view "{'map': function(doc) { 
                        if (doc.NAME == 'Larrabee') {
                          map(null,doc.NAME) 
                        }
                      };
              }")

(create-document '((:name . "Larrabee")))

(ad-hoc-view (ps-view ()
               (defun map (doc)
                 (with-slots (*name*) doc
                   (if (eql *name* "Larrabee")
                     (map nil doc))))))

(ad-hoc-view (ps-view (lambda (doc)
               (if (eql doc.*name* "Larrabee")
                 (map nil doc))))))

{
  "_id":"_design/company",
  "_rev":"12345",
  "language": "javascript",
  "views":
  {
    "all": {
      "map": "function(doc) { if (doc.Type == 'customer')  emit(null, doc) }"
    },
    "by_lastname": {
      "map": "function(doc) { if (doc.Type == 'customer')  emit(doc.LastName, doc) }"
    },
    "total_purchases": {
      "map": "function(doc) { if (doc.Type == 'purchase')  
                emit(doc.Customer, doc.Amount) }",
      "reduce": "function(keys, values) { return sum(values) }"
    }
  }
}

(create-ps-view "company"
  (ps-view ("all")
    (defun map (doc)
      (with-slots (type) doc
        (if (eql "customer" type)
          (emit null doc)))))
  (ps-view ("by_lastname")
    (defun map (doc)
      (with-slots (type last-name) doc
        (if (eql type "customer")
          (emit last-name doc)))))
  (ps-view ("total_purchases")
    (defun map (doc)
      (with-slots (type customer amount) doc
        (if (eql type "purchase")
          (emit customer amount)))
    (defun reduce (keys values)
      (return (sum values)))))

;; Views defined with Parenscript
(create-ps-view "names"
  (ps-view ("larrabee")
    (defun map (doc)  ;; parameter-less view
      (with-slots (name) doc
        (if (eql "Larrabee" name)
          (emit nil doc)))))
  (ps-view ("name")
    (defun map (doc)  ;; parameter view
      (with-slots (name) doc
        (emit name doc)))))

;; Find document by invoking parameter-less "larrabee" view
(invoke-view "names" "larrabee")

;; Find document by invoking "name" view with key parameter
(invoke-view "names" "name" :key "Larrabee")

;; Document to query
(create-document '((:name . "Larrabee")))

;; Views defined with Parenscript
(create-ps-view "names"
  (ps-view ("larrabee")
    (defun map (doc)  ;; parameter-less view
      (with-slots (name) doc
        (if (eql "Larrabee" name)
          (emit nil doc)))))
  (ps-view ("name")
    (defun map (doc)  ;; parameter view
      (with-slots (name) doc
        (emit name doc)))))

;; Find document by invoking parameter-less "larrabee" view
(invoke-view "names" "larrabee")

;; Find document by invoking "name" view with key parameter
(invoke-view "names" "name" :key "Larrabee")

Description	Lisp	JSON
Boolean	(:boolean . t) (:boolean . nil)	"BOOLEAN" : true "BOOLEAN" : false \| null
String	(:string . "Example")	"STRING" : "Example"
Keywords	(:keyword . example) (:keyword . :example) (:keyword . \|Example\|) Note: Keywords are always converted to strings	"KEYWORD" : "EXAMPLE" "KEYWORD" : "EXAMPLE" "KEYWORD" : "Example"
Number	(:number . 42)	"NUMBER" : 42
Floating Point Number	(:number . 42.0)	"NUMBER" : 42.0
Lisp List/JSON Array	(:list . (1 2 3)) (:list 1 2 3)	"LIST" : [1,2,3]
Lisp Associative Array/JSON Object	(:person . ((:name . "Bruce") (:gender . m)))	"PERSON" : {"NAME": "Bruce", "GENDER": "M"}

Clouchdb	Parenscript	CouchDb/JavaScript
:name, :NAME, :NaMe	name, NAME NaMe	NAME
:\|name\|	name	name
:\|mixedCase\|	mixed-case	mixedCase

clouchdb

Contents

Overview

News

Download and Installation

Examples

Support and mailing lists

API Reference

Connection and Database API

Document API

Views API

Symbol Index

Issues and Bugs

Overview

Design Goals

License

News

Download and Installation

Requirements:

ASDF Install

Unit tests

Examples

CVS Access

Support and mailing lists

Examples

Example 1

Example 2

Example 3

API Reference

Server Connection and Database Management API

Document API

Views API

Symbol Index

Issues and Bugs

Type	Description
keyword symbol	Matches field name in document
:*	Wild card, matches any symbol at the current level in the document
:**	Recursive wild card, matches subsequent symbol at any level in the document below the current level
function	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.