clouchdb

special · Query Operators

(ql:quickload "clouchdb")  

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

;; Install the Stefil test framework. This example installs Stefil using Quicklisp
(ql:quickload "stefil")

(load "tests.lisp")
(in-package :clouchdb-tests)

;; The following is only necessary if the couchdb server is not on 
;; localhost, or authenticaion is enabled, respectively.
(set-connection :host "hostname" :user "username" :password "password")

(test-all)

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 :parenscript))
#<PACKAGE "CLOUCHDB-USER">

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

;; View the current (default) CouchDb connection configuration
CLOUCHDB-USER> *couchdb*
#S(CLOUCHDB::DB
   :HOST "localhost"
   :PORT "5984"
   :NAME "default"
   :PROTOCOL "http"
   :USER NIL
   :PASSWORD NIL
   :DOCUMENT-FETCH-FN NIL
   :DOCUMENT-UPDATE-FN NIL)

;; The current database name is "default". Set appropriate values, for
;; example, if the CouchDb server is running on host "odeon" set that 
;; value like so:
CLOUCHDB-USER> (set-connection :host "odeon")
#S(CLOUCHDB::DB
   :HOST "odeon"
   :PORT "5984"
   :NAME "default"
   :PROTOCOL "http"
   :USER NIL
   :PASSWORD NIL
   :DOCUMENT-FETCH-FN NIL
   :DOCUMENT-UPDATE-FN NIL)

;; GetCouchDb Server Information. This is the first communication
;; with the CouchDb server.
CLOUCHDB-USER> (get-couchdb-info)
((:|couchdb| . "Welcome") (:|version| . "0.10.0a788899"))

;; Create database named "default", (as configured in *couchdb*)
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| . "1-1009420200"))

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

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

;; Get the updated document to verify that the new field stuck
CLOUCHDB-USER> (get-document "gjc")
((:|_id| . "gjc") (:|_rev| . "2-3501332342") (: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| . "37173e3a844a342414272daa733e1302")
 (:|rev| . "1-3111744915"))

;; 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| . "1-2190467195"))

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

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

;; 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| . "1-56705403"))

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

;; Let's see all documents in this database
CLOUCHDB-USER> (get-all-documents)
((:|total_rows| . 3) (:|offset| . 0)
 (:|rows|
  ((:|id| . "37173e3a844a342414272daa733e1302")
   (:|key| . "37173e3a844a342414272daa733e1302")
   (:|value| (:|rev| . "1-3111744915")))
  ((:|id| . "czechrepublic") (:|key| . "czechrepublic")
   (:|value| (:|rev| . "1-56705403")))
  ((:|id| . "someid") (:|key| . "someid")
   (:|value| (:|rev| . "2-1066530650")))))

;; 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| . "1-2083466274"))

CLOUCHDB-USER> (create-document '((:city . "Amsterdam")
                                  (:country . "NL"))
                                :id "amst") 
((:|ok| . T) (:|id| . "amst") (:|rev| . "1-3092672538"))

CLOUCHDB-USER> (create-document '((:city . "Rotterdam")
                                  (:country . "NL"))
                                :id "rott") 
((:|ok| . T) (:|id| . "rott") (:|rev| . "1-2303974290"))

CLOUCHDB-USER> (create-document '((:city . "Chicago")
                                  (:country . "US"))
                                :id "chi") 
((:|ok| . T) (:|id| . "chi") (:|rev| . "1-1962544983"))

;; Make a persistent view document that can be used to find cities in the 
;; Netherlands, cities by country key, and cities by country and city.

;; Note: Expressions within the (ps) expressions 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| . "1-544897531"))

;; 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| . "1-3092672538") (:CITY . "Amsterdam")
    (:COUNTRY . "NL")))
  ((:|id| . "rott") (:|key| . "Rotterdam")
   (:|value| (:|_id| . "rott") (:|_rev| . "1-2303974290") (: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| . 1)
 (:|rows|
  ((:|id| . "rott") (:|key| . "Rotterdam")
   (:|value| (:|_id| . "rott") (:|_rev| . "1-2303974290") (:CITY . "Rotterdam")
    (:COUNTRY . "NL")))))

;; Invoke "country" view to search for US cities
CLOUCHDB-USER> (invoke-view "cities" "country" :key "US")
((:|total_rows| . 4) (:|offset| . 2)
 (:|rows|
  ((:|id| . "chi") (:|key| . "US")
   (:|value| (:|_id| . "chi") (:|_rev| . "1-1962544983") (:CITY . "Chicago")
    (:COUNTRY . "US")))
  ((:|id| . "nyc") (:|key| . "US")
   (:|value| (:|_id| . "nyc") (:|_rev| . "1-2083466274")
    (: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| . 4) (:|offset| . 2)
 (:|rows|
  ((:|id| . "chi") (:|key| "US" "Chicago")
   (:|value| (:|_id| . "chi") (:|_rev| . "1-1962544983") (: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| . 4) (:|offset| . 0)
 (:|rows|
  ((:|id| . "amst") (:|key| "NL" "Amsterdam")
   (:|value| (:|_id| . "amst") (:|_rev| . "1-3092672538") (:CITY . "Amsterdam")
    (:COUNTRY . "NL")))
  ((:|id| . "rott") (:|key| "NL" "Rotterdam")
   (:|value| (:|_id| . "rott") (:|_rev| . "1-2303974290") (:CITY . "Rotterdam")
    (:COUNTRY . "NL")))))

;; Adding an attachment to a document, this will create the document too
;; if it does not already exist
CLOUCHDB-USER> (add-attachment "photos" 
                               (pathname "/home/peter/images/camels.jpg"))
((:|ok| . T) (:|id| . "photos") (:|rev| . "1-1883927893"))

;; Take a look at what was just created
CLOUCHDB-USER> (get-document "photos")
((:|_id| . "photos") (:|_rev| . "1-1883927893")
 (:|_attachments|
  (:|camels.jpg| (:|stub| . T) (:|content_type| . "application/octet-stream")
   (:|length| . 54271))))

;; Copy the attachment from the document to /tmp directory on the local disk
;; and return the resulting file name and path.
CLOUCHDB-USER> (save-attachment "photos" "camels.jpg" (pathname "/tmp/"))
#P"/tmp/camels.jpg"

;; Copy the camels.jpg attachment from the document to a differently 
;; named file on the local disk
CLOUCHDB-USER> (save-attachment "photos" "camels.jpg" 
                                (pathname "/tmp/SomeCamels.jpg"))
#P"/tmp/SomeCamels.jpg"

;; Copy camels.jpg attachment from the "photos" document to
;; the "camels2.jpg" attachment of the "animals" document
;; The with-attachment macro returns the attachment as
;; an input stream and closes that stream before returning.
CLOUCHDB-USER> (with-attachment (in "photos" "camels.jpg")
                 (add-attachment "animals" in :name "camels2.jpg"))
((:|ok| . T) (:|id| . "animals") (:|rev| . "1-2497134014"))

;; Delete the "camels.jpg" attachment from the "photos" document
CLOUCHDB-USER> (delete-attachment "photos" "camels.jpg")
((:|ok| . T) (:|id| . "photos") (:|rev| . "2-3799224225"))

;; Delete all attachments in the "animals" document
CLOUCHDB-USER> (dolist (at (attachment-list "animals"))
                 (delete-attachment "animals" at))

;; Changes for the current database
(changes)
=> 
((:|results|
  ((:|seq| . 4) (:|id| . "_design/example")
   (:|changes| ((:|rev| . "1-f83b5f3e154eb3c0ba2d721ad53211b3"))))
  ((:|seq| . 5) (:|id| . "_design/toast")
   (:|changes| ((:|rev| . "1-3525a1d974ba13a34d26e305116feab2")))))
 (:|last_seq| . 5))

;; Define function to be called when changes occur
(defun handle-change (change) 
  (format t "got change: ~A~%" change) 
  ;; return true to continue to receive change notifications
  t)

(changes :feed :continuous :notify-fn #'handle-change :heartbeat 1000)

got change: ((seq . 4) (id . _design/example)
             (changes ((rev . 1-f83b5f3e154eb3c0ba2d721ad53211b3))))
got change: ((seq . 5) (id . _design/toast)
             (changes ((rev . 1-3525a1d974ba13a34d26e305116feab2))))
got change: ((seq . 6) (id . biking)
             (changes ((rev . 1-7e2d4e10305a1b9cfc0ae5bd40a1b301))))
got change: ((seq . 7) (id . bought-a-cat)
             (changes ((rev . 1-8ea27c5ff15247402947864f1bafc245))))
got change: NIL
got change: NIL
got change: NIL

;; Compact current database
(compact-db)
=> ((:|ok| . T))

;; Compact "default" database
(compact-db :db "default")

;; Compact "default" database
(compact-db :db (make-db :name "default"))
=> ((:|ok| . T))

;; Create the database named in the current connection settings
(set-connection :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 "tvland" :if-exists :ignore)
=> ((:|ok| . T) (:IGNORED . T))

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

;; Create then delete the database named in the current connection settings
(set-connection :name "tvland")
(create-db)
=> ((:|ok| . T))
(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 result if database did not exist
(delete-db :db "radio" :if-missing :ignore)
=> ((:|error| . "not_found") (:|reason| . "missing"))

(get-couchdb-info)
=> ((:|couchdb| . "Welcome") (:|version| . "0.10.0a788899"))

(get-db-info)
=> ((:|db_name| . "default") (:|doc_count| . 0) (:|doc_del_count| . 0)
     (:|update_seq| . 0) (:|purge_seq| . 0) (:|compact_running|)
     (:|disk_size| . 79) (:|instance_start_time| . "1247095993127949")
     (:|disk_format_version| . 3))

(get-db-info :db "default")
=> ((:|db_name| . "default") (:|doc_count| . 0) (:|doc_del_count| . 0)
     (:|update_seq| . 0) (:|purge_seq| . 0) (:|compact_running|)
     (:|disk_size| . 79) (:|instance_start_time| . "1247095993127949")
     (:|disk_format_version| . 3))

(get-db-info :db *couchdb*)
=> ((:|db_name| . "default") (:|doc_count| . 0) (:|doc_del_count| . 0)
     (:|update_seq| . 0) (:|purge_seq| . 0) (:|compact_running|)
     (:|disk_size| . 79) (:|instance_start_time| . "1247095993127949")
     (:|disk_format_version| . 3))

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

(make-db)
=> #S(CLOUCHDB::DB
      :HOST "localhost"
      :PORT "5984"
      :NAME "default"
      :PROTOCOL "http"
      :USER NIL
      :PASSWORD NIL
      :DOCUMENT-FETCH-FN NIL
      :DOCUMENT-UPDATE-FN NIL)

(make-db :name "users" :host "www.company.com")
=> #S(CLOUCHDB::DB
      :HOST "www.company.com"
      :PORT "5984"
      :NAME "users"
      :PROTOCOL "http"
      :USER NIL
      :PASSWORD NIL
      :DOCUMENT-FETCH-FN NIL
      :DOCUMENT-UPDATE-FN NIL)

;; Temporarily set current db connection info to alternate database
(let ((*couchdb* (make-db :name "users" :host "www.company.com")))
  (get-document "someuser"))

*couchdb*
=> #S(CLOUCHDB::DB
     :HOST "localhost"
     :PORT "5984"
     :NAME "default"
     :PROTOCOL "http"
     :USER NIL
     :PASSWORD NIL
     :DOCUMENT-FETCH-FN NIL
     :DOCUMENT-UPDATE-FN NIL)

(set-connection :host "orubus")
*couchdb*
=> #S(CLOUCHDB::DB
     :HOST "orubus"
     :PORT "5984"
     :NAME "default"
     :PROTOCOL "http"
     :USER NIL
     :PASSWORD NIL
     :DOCUMENT-FETCH-FN NIL
     :DOCUMENT-UPDATE-FN NIL)

;; 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
(set-connection :document-update-fn #'time-stamper)

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

;; Display the new document with timestamp
(get-document "test")
=> ((:|_id| . "test") (:|_rev| . "3721228336") (:TIMESTAMP . 3422649324) 
  (:HELLO . "there"))

  ;; Replicate current database to databased named "backup" on the same server
  (replicate "backup")

  ;; Replicate current database to remotely hosted "backup" database
  (replicate (make-db :name "backup" :host "remote"))

  ;; Replicate one remote database to another
  (replicate (make-db :name "backup" :host "remoteB")
     :source (make-db :name "source" :host "remoteA"))

;; Get document from specified host and database
(with-connection (:host "cornichon.cucumber.net" :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 (:name "otherdb")
    (get-document "someid"))
  :id "copy-of-someid")

(with-temp-db 
  *couchdb*)

=> #S(CLOUCHDB::DB
      :HOST "localhost"
      :PORT "5984"
      :NAME "temp-3456412771-3"
      :PROTOCOL "http"
      :USER NIL
      :PASSWORD NIL
      :DOCUMENT-FETCH-FN NIL
      :DOCUMENT-UPDATE-FN NIL)

(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)
                              (: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))

(bulk-document-update 
  (mapcar #'as-deleted-document (list (get-document "one")
                                       (get-document "two"))))
=>(((:|id| . "one") (:|rev| . "2-1128337663"))
   ((:|id| . "two") (:|rev| . "2-1919003983")))

;; 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"

(get-document "apple")
=> ((:|_id| . "apple") (:|_rev| . "1-4022626409") (:FRUIT . "Apple"))

(couchdb-document-properties (get-document "apple"))
=> ((:|_id| . "apple") (:|_rev| . "1-4022626409"))
;; Create document, specifying ID of "example"
(create-document '((:string . "string") 
                   (:number . 42)
                   (:array . ("one" 2 "nine"))
                   (:map . ((:foo . "bar")
                            (:size . 3)
                            (:colors . ("red" "blue" "green")))))
                 :id "example")

;; Create a document and let CouchDb provide an ID
(create-document '((:some . "data")))

(bulk-document-update (list '((:name . "Bob"))
                            '((:name . "Ted") (:|_id| . "ted"))))
=>(((:|id| . "6df18bda590ee37927ec33cdcdd3e41b") (:|rev| . "1-2493069933"))
   ((:|id| . "ted") (:|rev| . "1-1461663065")))

;; Copy document identified by "source" to new document "copy")
(copy-document "source" "copy")

;; Overwrite "destination" with "source" document
(copy-document "source" (get-document "destination"))

;; Overwrite "destination" with "source" document
(copy-document "source" "destination" :revision :current)

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

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

;; Nested property change example
(create-document '((:a . 1)(:b . ((:c . ((:d . "New York")))))) :id "nested")
;; Change (:d . "New York") to (:d . "Boston")
(put-document
  (setf (document-property '(:b :c :d) (get-document "nested")) "Boston"))

    ;; Create a document, let server assign an ID
    (get-uuids :count 3)

    =>((:|uuids| "ff02503bc937206fa3aec576b0378fc0"
        "84b78cb82667856025929bfe30168ea3" "2c9026f46d8db4f8cc669f91c501c265"
        "289f477p587e1775a5f3f6e55cb5b76f0" "d28f7a78268d8411b53bdf4bb4d6b9f9"))

(get-document "apple")
=> ((:|_id| . "apple") (:|_rev| . "1-4022626409") (:FRUIT . "Apple"))

(document-properties (get-document "apple"))
=> ((:FRUIT . "Apple"))

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

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

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

;; Copy 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))

;; A document with three attachments
(get-document "images")
=>((:|_id| . "images") (:|_rev| . "7-1856240461")
   (:|_attachments|
    (:|camels.jpg| (:|stub| . T) (:|content_type| . "image/jpeg")
     (:|length| . 54271))
    (:|butter.jpg| (:|stub| . T) (:|content_type| . "image/jpeg")
     (:|length| . 54271))
    (:|birds.jpg| (:|stub| . T) (:|content_type| . "application/octet-stream")
     (:|length| . 54271))))

;; Add file attachment with content type
(add-attachment "Moscow"
                (pathname "/home/peter/Pictures/images/Zaryadye.jpg")
                :content-type "image/jpeg")
=>((:|ok| . T) (:|id| . "Moscow") (:|rev| . "1-2164210511"))

;; Add attachment but supply an attachment name to use instead of
;; the file name
(add-attachment "Moscow"
                (pathname "/home/peter/Pictures/images/Suharevskaia.jpg")
                :name "Sukharevskaya.jpeg"
                :content-type "image/jpeg")
=>((:|ok| . T) (:|id| . "Moscow") (:|rev| . "2-2235841483"))

;; Add string value as attachment
(add-attachment "StringDoc" "Attachment Content" :name "StringAttachment")
=>((:|ok| . T) (:|id| . "StringDoc") (:|rev| . "1-2376170595"))

(attachment-list "Moscow")
=>((:|Sukharevskaya.jpeg| (:|stub| . T) (:|content_type| . "image/jpeg")
    (:|length| . 119891))
   (:|Zaryadye.jpg| (:|stub| . T) (:|content_type| . "image/jpeg")
    (:|length| . 30057)))

(dolist (attachment (attachment-list "SomeDocument"))
  (format t "Name: ~s~%" (attachment-name attachment)))
=> Name: "Sukharevskaya.jpeg"
   Name: "Zaryadye.jpg"

;; Save an attachment to /tmp/camels.jpg. Directory name must end
;; with / 
(save-attachment "images" "camels.jpg" (pathname "/tmp/"))
=>#P"/tmp/camels.jpg"

;; Save an attachment to a different file name in /tmp/
(save-attachment "images" "camels.jpg" (pathname "/tmp/someCamels.jpg"))
=>#P"/tmp/someCamels.jpg"

;; Use with-attachment to copy attachment "camels.jpg" from document
;; "images" to document "animals"
(with-attachment (in "images" "camels.jpg")
  (add-attachment "animals" in :name "camels.jpg"))
=>((:|ok| . T) (:|id| . "animals") (:|rev| . "1-2861475448"))

(create-document '((:name . "Laraby")))
(ad-hoc-view "function(doc) { if (doc.NAME == 'Laraby') { map(null,doc.NAME) } }")

(create-document '((:name . "Laraby")))
(ad-hoc-view (ps (lambda (doc)
                   (with-slots (*name*) doc
                     (if (eql *name* "Laraby")
                       (emit nil doc))))))

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

(create-ps-view "company"
                (ps-view ("all")
                  (defun map (doc)
                    (with-slots (type) doc
                      (if (eql type "customer")
                          (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)
                      (if (eql type "purchase")
                          (emit customer amount))))
                  (defun reduce (keys values)
                    (sum values)))))

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

;; Views defined with Parenscript
(create-ps-view "names"
  (cons "laraby"
        (ps (lambda (doc)  ;; parameter-less view
              (with-slots (name) doc
                (if (eql "Laraby" name)
                  (emit nil doc))))))
  (cons "name"
        (ps (lambda (doc)  ;; parameter view
              (with-slots (name) doc
                (emit name doc))))))

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

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

Parameter	Description
:db	The target database or database host information, specified either as a string or a db structure. Defaults to current database in *couchdb*.
:feed	Either :normal to not poll (the default), :longpoll to block waiting for a single response from the server, or :continuous to poll for changes indefinately.
:since
:heartbeat	The period, in milliseconds, after which a nil result is sent. Applies only to :longpoll and :continuous feed options. Overrides any timeout value.
:timeout	Time, in milliseconds, after which the database will send an empty line. Applies only to :longpoll or :continuous feed options.
:filter
:notify-fn	A function to call as change notifications arrive. If specified, the call to (changes) will block and the notify-fn function will be called as each change notification arrives. The function should take one parameter, which will be the change notification document or nil (when :heartbeat is specified). The function should return true to continue to receive change notifications or false to cancel receipt of change notifications. When the notification function returns false the open stream to the CouchDb server is closed and the call to (changes) will return.
:include-docs	If true, include the associated document with each result. (CouchDb version 0.11+)

Parameter	Description
doc	The document contents or nil to create empty document
:id	The ID for the new document. If not specified, CouchDb will provide an ID value.
:attachments	One or more document attachments

Parameter	Description
id	The document ID
:revision	The optional document revision. If not specified, returns the most recent revision.
:conflicts	If true, return any existing replication conflicts for the document.
:revisions	If non-nil, return brief revision information for the document.
:revision-info	If non-nil, returned document will contain detailed document revision information.
:if-missing	If the specified document does not exist, return the value specified instead. If the value is a function pointer, call the function with the ID of the missing document.

Parameter	Description
:db	The target database or database host information, specified either as a string or a db structure. Defaults to current database in *couchdb*.
:count	The number of UUIDS to return. Default is 1

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.

clouchdb

Overview

Contents

News

Download and Installation

Support and mailing lists

Examples

API Reference

Connection and Database API

Document API

Atachment API

Views API

Conditions Defined by Clouchdb

Symbol Index

Issues and Bugs

News

Download and Installation

Requirements:

Optional Libraries:

Quicklisp Install

ASDF Install

Unit tests

Examples

Github Source

CVS Access

Support and mailing lists

Examples

Example 1

Example 2

Example 3

Example 4

API Reference

Server Connection and Database Management API

Document API

Attachment API

Views API

Conditions Defined by Clouchdb

Symbol Index

Issues and Bugs

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