Flattened relationships are a fancy term for a relationship which involves three or more tables in the database. Lets say you have Artists and Exhibits. They are joined with a many-many join table called Artist_Exhibit, because many Artists could collaborate on one Exhibit and each Artist might be part of many Exhibits. Now you could map these as separate joins and end up with Java code which looks like this:
artist.getArtistExhibits().getExhibits()
but with a flattened join, it is even simpler:
artist.getExhibits()
From the application point of view there is no difference in working with flattened relationships compared to the "normal" ones. Cayenne internally figures out how to build the needed query joins to retrieve related objects. On adding or removing an object to/from a flattened relationship via a corresponding "addTo..." / "removeFrom..." method an appropriate join record is created or removed.
 | Flattened Relationships Limitations Only many-to-many flattened relatationships with a single join table can be modified. All other types of flattened relationships can be used as "read-only". This is reflected in the DataObject code generated for such relationships - no set/addTo/RemoveFrom methods are created for read-only relationships. |
See this documentation on how to create flattened relationships in Cayenne Modeler