From 105e9393185c042ddcdad857630c2d1c52da6c2a Mon Sep 17 00:00:00 2001 From: Jeremy Evans Date: Sun, 15 May 2011 18:24:05 -0700 Subject: [PATCH] Add documentation about the new capabilities for filtering/excluding by associations --- doc/association_basics.rdoc | 48 +++++++++++++++++++++++++++++++++---- 1 file changed, 43 insertions(+), 5 deletions(-) diff --git a/doc/association_basics.rdoc b/doc/association_basics.rdoc index 6cb1c8ed72..47ce4c7620 100644 --- a/doc/association_basics.rdoc +++ b/doc/association_basics.rdoc @@ -421,13 +421,51 @@ This doesn't just work for +many_to_one+ associations, it also works for Note that for +one_to_many+ and +many_to_many+ associations, you still use the plural form even though only a single model object is given. -You cannot use an array of model objects as the value, only a single model -object. To use separate model objects for the same association, you can -use the array form of condition specifiers: - Album.filter([[:tags, Tag[1]], [:tags, Tag[2]]]) +You can also exclude by associations: -That will return albums associated with both tag 1 and tag 2. + Album.exclude(:artist=>@artist).all + +This will return all albums not by that artist. + +You can also provide an array with multiple model objects: + + Album.filter(:artist=>[@artist1, @artist2]).all + +Similar to using an array of integers or strings, this will return +all albums whose artist is one of those two artists. You can also +use +exclude+ if you want all albums not by either of those artists: + + Album.exclude(:artist=>[@artist1, @artist2]).all + +If you are using a +one_to_many+ or +many_to_many+ association, you +may want to return records where the records matches all of multiple +records, instead of matching any of them. For example: + + Album.filter(:tags=>[@tag1, @tag2]) + +This matches albums that are associated with either @tag1 or @tag2 or +both. If you only want ones that you are associated with both, you can +use separate filter calls: + + Album.filter(:tags=>@tag1).filter(:tags=>@tag2) + +Or the the array form of condition specifiers: + + Album.filter([[:tags, @tag1], [:tags, @tag2]]) + +These will return albums associated with both @tag1 and @tag2. + +You can also provide a dataset value when filtering by associations: + + Album.filter(:artist=>Artist.filter(:name.like('A%'))).all + +This will return all albums whose artist starts with 'A'. Like +the other forms, this can be inverted: + + Album.exclude(:artist=>Artist.filter(:name.like('A%'))).all + +This will return all albums whose artist does not start with 'A'. Note that filtering by associations only works correctly for simple associations (ones without conditions).