Creating, Getting and Deleting Data

Simplecouchdb represents CouchDB documents as instances of document classes. Methods of a document instance create, update and delete the document. CouchDB documents can be fetched as document instances using views or id.

See also

Schema Reference for more information about documents use in simplecouchdb.

Creating and Updating a Document

Instances of Document classes represent CouchDB documents. An application creates a new document by calling the constructor of the document class.

pet = Pet(name="Fluffy",
      type="cat",
      owner="Jean")

The new document is not created in CouchDB database until the instance is “saved” for the first time, by calling the simplecouchdb.schema.Document.save() method on the instance.

pet.save(db)

db is an instance of simplecouchdb.core.Database .

If the instance has been saved before (id is not None), the simplecouchdb.schema.Document.save() update it cleanly.

Getting documents using id

All documents stored in CouchDB have an id.

You can simply get a document with simplecouchdb.schema.Document.get() :

pet.get(db, "04ba0f93aeef0602b757bd1cfb6b95c1")

If you don’t specify id of document, id are generated by CouchDB server as uuid.

Getting documents using view

Views are CouchDB way using Map/Reduce to get documents.

here is simple design_doc in javascript that define a view to get all pets by their type

{
    '_id': '_design/pet',
    'language': 'javascript',
    'views': {
        'by_type': {
            'map': 'function(doc) { if (doc.doc_type == "Pet") emit(doc.type, doc); }'
        }
    }
}

Note

Each document instance is saved with a doc_type property. By default it is se to class name, but you could change it with simplecouchdb.schema.Document.doc_type property.

You could simply get all pet of type cat with simplecouchdb.schema.Document.view() method :

cats = Pet.view(db, "pet/by_type", key="cat")

It return a simplecouchdb.core.ViewResults object that you could itterate. All results are Pet instance.

You could also get results as dict object with simplecouchdb.core.Database.view property :

cats = db.view.get('pets/by_type', key="cat")

Like above, it return a simplecouchdb.core.ViewResults object that you could itterate but resulst are simple dict not mapped to Pet instance and all results are simple javascript type: unicode, integer, list, dict.

See also

See HTTP View API from the CouchDB wiki for more informations about views.

Getting documents using view property

Last way to get documents is by adding a simplecouchdb.schema.ViewProperty to your document instance. It will alow you in the same time to define the view and using a simple way to synchronise it in your application.

class Pet(schema.Document):
    ...
    by_type = schema.ViewProperty("pet", map_fun="""function(doc) { if (doc.doc_type == "Pet") emit(doc.type, doc); }""")

db.sync()
cats = Pet.by_type.get(key="cat")

See also

ViewDefinition class for more information View defintion.

Deleting document

Delete a document by using simplecouchdb.schema.Document.delete() method:

pet1 = Pet()
pet.get(db, "04ba0f93aeef0602b757bd1cfb6b95c1")
pet.delete()

Or use simplecouchdb.core.Database.delete() or just del():

db.delete("04ba0f93aeef0602b757bd1cfb6b95c1")

or

del db["04ba0f93aeef0602b757bd1cfb6b95c1"]