Correlate

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.

Documentation

rdoc.info/projects/kennethkalmer/correlata
spec directory

Installation and dependencies

Use:

couchrest 0.33 or later

Development:

jeweler
rspec
activerecord
yard

Installation:

$ gem install correlate

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

Usage

require 'correlate'

class MyDocument < CouchRest::ExtendedDocument

  include Correlate

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

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

my_doc = MyDocument.new

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'
  end
end

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'
  end
end

class Document < CouchRest::ExtendedDocument

  property :some_model_id

  view_by :some_model_id
end

class Note < CouchRest::ExtendedDocument

  include Correlate

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

Status

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.