JOINs and relations

Declare associations, query across collections, and model common relationship patterns.

Related: JOINs, References & JOINs — Deep dive, JOINs, Selection, and Grouping, Cascading

Use this page when you need to join across collections or model relationships.

Declare associations

app/search_engine/publisher.rb

class SearchEngine::Publisher < SearchEngine::Base
  collection :publishers
  attribute :publisher_id, :string
  attribute :name, :string

  identify_by :publisher_id
end

app/search_engine/book.rb

class SearchEngine::Book < SearchEngine::Base
  collection :books
  attribute :publisher_id, :string
  attribute :name, :string

  belongs_to :publisher
end

Query across collections

SearchEngine::Book
  .joins(:publisher)
  .where(publisher: { name: "Acme" })
  .to_a

One-to-one relations

app/search_engine/user.rb

class SearchEngine::User < SearchEngine::Base
  collection :users
  attribute :user_id, :string
  attribute :email, :string

  identify_by :user_id
  has_one :profile, foreign_key: :user_id
end

app/search_engine/profile.rb

class SearchEngine::Profile < SearchEngine::Base
  collection :profiles
  attribute :user_id, :string
  attribute :display_name, :string

  belongs_to :user, local_key: :user_id, foreign_key: :user_id
end

SearchEngine::User.find("user_1").profile

One-to-many relations

app/search_engine/author.rb

class SearchEngine::Author < SearchEngine::Base
  collection :authors
  attribute :author_id, :string
  attribute :name, :string

  has_many :books, foreign_key: :author_id
end

app/search_engine/book.rb

class SearchEngine::Book < SearchEngine::Base
  collection :books
  attribute :author_id, :string
  attribute :title, :string

  belongs_to :author, local_key: :author_id, foreign_key: :author_id
end

SearchEngine::Author.find("author_1").books.where(published: true)

Many-to-many relations

app/search_engine/enrollment.rb

class SearchEngine::Enrollment < SearchEngine::Base
  collection :enrollments
  attribute :student_id, :string
  attribute :course_id, :string
end

app/search_engine/student.rb

class SearchEngine::Student < SearchEngine::Base
  collection :students
  attribute :student_id, :string
  attribute :name, :string

  has_many :enrollments, foreign_key: :student_id
end

app/search_engine/course.rb

class SearchEngine::Course < SearchEngine::Base
  collection :courses
  attribute :course_id, :string
  attribute :title, :string

  has_many :enrollments, foreign_key: :course_id
end

SearchEngine::Course
  .joins(:enrollments)
  .where(enrollments: { student_id: "student_1" })
  .to_a

Use belongs_to_many when a single local key maps to many target records via a shared foreign key.

Next steps

• Learn join rules and nested selection in JOINs.
• Explore cascading reindex behavior in Cascading.