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.

IMPORTANT:

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.

• rdoc.info/projects/kennethkalmer/correlata

• spec directory

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.

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 ]

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:

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

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

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

• 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.