chickadee » couchdb



Apache CouchDB is a document-oriented database that can be queried and indexed in a MapReduce fashion using JavaScript. CouchDB also offers incremental replication with bi-directional conflict detection and resolution.

The couchdb egg provides a scheme interface to couchdb's RESTful JSON API.

If you are looking for a method of writing couchdb views, i.e server side code in scheme see the couchdb-view-server egg.


http-client intarweb json uri-common defstruct


As said above a CouchDB server will use the JSON format for encoding responses. The json egg manages the marshalling and unmarshalling. See there for the correct type conversions. As a convenience function json-ref is provided by this egg.

Querys to the database are encoded in URIs. Depending on the setup of the CouchDB server username and password may have to be encoded in the URI. This applys to database creation / deletion mostly.

Error handling

All procedures return #f on error. The last error is provided with the utility procedure last-error.

CouchDB connection procedures

For identifying connections a connection record has to be created first.

(make-connection database: DATABASE-STRING server: URI-REFERENCE)procedure

Creates a connection record for the desired DATABASE-STRING on the CouchDB located at the specified URI reference.

Note: You will need uri-common's uri-reference.


(define conn (make-connection server: (uri-reference "http://localhost:5984/")
                              database: "chicken-test-couchdb"))
Connection accessors / setters
connection-uri connectionprocedure
connection-database connectionprocedure

Accessors for the CouchDB egg connection record.

update-connection connection #!key database connectionprocedure

Update function for the connection record.

get-server-info connectionprocedure

Returns the couchdb version information as the json egg parses the response.

CSI> (get-server-info (make-connection server: (uri-reference "http://localhost:5984/")))
#(("couchdb" . "Welcome") ("version" . "0.11.0"))

Database handling

create-database connectionprocedure

Creates a database as specified in the connection record connection. Use (make-connection database-string couchdb-uri-string) to create a connection object.

Returns #t or #f. Verbose error message can be retrieved with ''last-error'.

delete-database connectionprocedure

Deletes the database as specified in the connection record connection. Use (make-connection database-string couchdb-uri-string) to create a connection object.

Returns #t or #f. Verbose error message can be retrieved with ''last-error'.

get-database-info connectionprocedure

Returns the database information for a given connection record. Use (make-connection database-string couchdb-uri-string) to create a connection record.

Document handling

The central entity in a CouchDB is a so called document. A CouchDB document is an object that consists of named fields. Field values may be strings, numbers, dates, or even ordered lists and associative maps, all encoded in JSON.

However there are at least two mandatory fields in each document:

unique id within the database
revision of that document
Document datatype
make-document id revision #!optional (body '#())procedure

The couchdb uses a record to represent the contents of a document. The mandatory elements have distinct slots whereas the rest of the fiels is accessible in a vector called body.

document? docprocedure

Type checking predicate for a document record.

document-id docprocedure
document-rev docprocedure
document-body docprocedure
update-document doc #!key id rev bodyprocedure

Accessors for the id rev and body slots of a document record.

document-attribute? document nameprocedure

Predicate indicating wether document does contain a attribute name.

document-attribute document nameprocedure

Returns the value for name if it is contained in document.

Document retrieval / storage
get-document connection idprocedure

Requests the document with id id and returns that or #f.

save-document connection documentprocedure

Stores the document in the database and returns it with updated id and revision attributes. If the document does not exist in the database it is created.

delete-document connection documentprocedure

Deletes the document form the database.

get-all-documents connection #!optional (query '())procedure

Returns all documents in the database. The output can be quite large! You can pass any valid query URI part for the optional query parameter.

View Handling

get-view connection view-string #!optional (query '())procedure

Returns the results of the requested view. View can be either a string depicting an explicit path or a list of strings which in the latter case is treated as (list design-document view-name). The query parameter is an alist containing (parameter-name . value) pairs.

<Procedure>(send-temp-view-request connection view method #!key query)</procedure>

Utility functions

json-ref name objectprocedure

Retrieves a field name from a JSON object object. This is a convenience function to ease the access of the vector / hash-table mix the json egg generates.

last-error #fparameter

Will be set on errors. Returns a descriptive error string.


Moritz Heidkamp


Apache CouchDB client library

Copyright (C) 2009 Moritz Heidkamp

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public License
as published by the Free Software Foundation; either version 3 of
the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
Lesser General Public License for more details.

You can find a copy of the GNU Lesser General Public License at

Version History

initial release

Contents »