Switch branches/tags
Nothing to show
Find file
Fetching contributors…
Cannot retrieve contributors at this time
145 lines (95 sloc) 3.33 KB


Correlate is an experiment in loosely expressing relationsips between documents stored in CouchDB using couchrest.

Correlate stores all the relationships in an array of links, similar to the link elements found in HTML:

  "links" : [
   { "rel" : "another_doc", "href" : "<uuid>" },
   { "rel" : "important", "href" : "<uuid>" }

Inspired by looking for ways to express the loosened relationships that exists between documents inside CouchDB, but to not mimic the nature of an RDBMS.


Unlike relational-thinking, all the relationships are expressed on the given object itself, not its correlated objects. Correlate does support recipocal correlations which, when enabled for a correlation, updates the links on both objects.


Installation and dependencies


  • couchrest 0.33 or later


  • jeweler

  • rspec

  • activerecord

  • yard


$ gem install correlate

Correlate does not depend on ActiveRecord and can be safely used in any project that doesn't use ActiveRecord.


require 'correlate'

class MyDocument < CouchRest::ExtendedDocument

  include Correlate

  related_to do
    some :other_documents, :class => 'OtherDocument', :rel => 'other_doc'

This sets up a links property on the document, with some accessors for loading and ammending relationships:

my_doc =

my_doc.other_documents << other_document_instance

my_doc.other_documents #=> [ other_document_instance ]

Associations with ActiveRecord models

When transitioning from ActiveRecord to CouchDB it is inevitable that relationships will exist across the boundaries of each database. Correlate helps you to express these relationships:

CouchDB to ActiveRecord

Pretty much the same as the examples above:

class MyDocument < CouchRest::ExtendedDocument

  include Correlate

  related_to do
    a :model, :class => 'Model', :rel => 'model'

ActiveRecord to CouchDB

When using an 'a' relationship, you don't need to specify any additional information, but when specifying a 'some' relationship you'll want to supply the name of the view.

class SomeModel < ActiveRecord::Base

  include Correlate

  related_to do
    some :documents, :class => 'Document', :view => 'some_model_id', :key => :id
    some :notes, :class => 'Note', :rel => 'some_model'

class Document < CouchRest::ExtendedDocument

  property :some_model_id

  view_by :some_model_id

class Note < CouchRest::ExtendedDocument

  include Correlate

  related_to do
    a :some_model, :class => 'SomeModel', :rel => 'some_model'


This project is highly experimental, but is in use in a few applications in one form or another.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.


Copyright © 2009 Kenneth Kalmer. See LICENSE for details.