Raise Errors::EagerLoad when trying to eager load many-to-many:

- All benchmarks show the extra query to get all the ids to be slower
  than executing the queries individually. This is before even setting
  the documents in the identity map.

lib/config/locales/bg.yml

@@ -8,6 +8,9 @@ bg:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Не е намерен документ %{klass} с id(та) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Базата данни трябва да е от тип Mnogo:DB, а не  %{name}.
         invalid_type:

lib/config/locales/de.yml

@@ -8,6 +8,9 @@ de:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Dokument für Klasse %{klass} mit ID(s) %{identifiers} nicht gefunden.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Datenbank sollte eine Mongo::DB sein, nicht %{name}.
         invalid_type:

lib/config/locales/en-GB.yml

@@ -8,6 +8,9 @@ en-GB:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Document not found for class %{klass} with id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           "Database should be a Mongo::DB, not %{name}."
         invalid_options:

lib/config/locales/en.yml

@@ -8,6 +8,9 @@ en:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Document not found for class %{klass} with id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           "Database should be a Mongo::DB, not %{name}."
         invalid_options:

lib/config/locales/es.yml

@@ -6,6 +6,9 @@ es:
           ya está en uso
         document_not_found:
           No se encontró ningún documento para la clase %{klass} con los id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           La base de datos debería ser una instancia de Mongo::DB, en lugar de %{name}.
         invalid_type:

lib/config/locales/fr.yml

@@ -8,6 +8,9 @@ fr:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Document introuvable pour la classe %{klass} avec les ids %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           La base de données doit être une Mongo::DB, pas %{name}.
         invalid_type:

lib/config/locales/hi.yml

@@ -8,6 +8,9 @@ en:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           "%{identifiers}  id(s) के साथ, वर्ग %{klass} के लिए दस्तावेज़ नहीं मिला."
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           "डेटाबेस Mongo::DB होना चाहिए, %{name} नहीं."
         invalid_options:

lib/config/locales/hu.yml

@@ -8,6 +8,9 @@ hu:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           "%{klass} osztályban, %{identifiers} id(k)-el nem található dokumentum."
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Az adatbázisnak Mongo::DB-nek kellene lennie, nem %{name}.
         invalid_type:

lib/config/locales/id.yml

@@ -8,6 +8,9 @@ id:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Dokumen tidak ditemukan untuk kelas %{klass} dengan id %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Database harus Mongo::DB, bukan %{name}.
         invalid_type:

lib/config/locales/it.yml

@@ -8,6 +8,9 @@ it:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Documento non trovato per la classe %{klass} con id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Il database dovrebbe essere un Mongo::DB, non %{name}.
         invalid_type:

lib/config/locales/ja.yml

@@ -8,6 +8,9 @@ ja:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           次のDocumentは見つかりませんでした。class %{klass} with id(s) %{identifiers}
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           次のDatabaseは利用できませんでした。%{name}
         invalid_type:

lib/config/locales/kr.yml

@@ -8,6 +8,9 @@ kr:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           클라스 %{klass}와 id를 %{identifiers} 위한 문서를 찾을수 없습니다.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           데이타베이스가 Mongo::DB이어야 합니다, %{name}이면 안됩니다.
         invalid_type:

lib/config/locales/nl.yml

@@ -8,6 +8,9 @@ nl:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Document niet gevonden voor class %{klass} met de id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Database moet een Mongo::DB zijn, niet een %{name}.
         invalid_type:

lib/config/locales/pl.yml

@@ -8,6 +8,9 @@ pl:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Nie znaleziono dokumentu dla klasy %{klass} o id %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Baza danych powinna być typu Mongo::DB, a nie %{name}.
         invalid_type:

lib/config/locales/pt-BR.yml

@@ -8,6 +8,9 @@ pt-BR:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Nenhum documento encontrado para a classe %{klass} com os id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           A base de dados deverá ser uma Mongo::DB, em vez de %{name}.
         invalid_type:

lib/config/locales/pt.yml

@@ -8,6 +8,9 @@ pt:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Nenhum documento encontrado para a classe %{klass} com os id(s) %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           A base de dados deverá ser uma Mongo::DB, em vez de %{name}.
         invalid_type:

lib/config/locales/ro.yml

@@ -8,6 +8,9 @@ ro:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Nu există document în clasa %{klass} cu id %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Baza de date ar trebui să fie de tipul Mongo::DB, nu %{name}.
         invalid_type:

lib/config/locales/ru.yml

@@ -8,6 +8,9 @@ ru:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Документ класса %{klass} с id %{identifiers} не найден.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           База данных должна быть Mongo::DB, а не %{name}.
         invalid_type:

lib/config/locales/sv.yml

@@ -8,6 +8,9 @@ sv:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Inget dokument kunde hittas för klass %{klass} med id %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Databasen bör vara Mongo::DB, inte %{name}.
         invalid_type:

lib/config/locales/vi.yml

@@ -8,6 +8,9 @@ vi:
           "Calling %{method} on %{klass} resulted in a false return from a callback."
         document_not_found:
           Không tìm thấy văn bản cho lớp %{klass} với định danh %{identifiers}.
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           Cơ sở dữ liệu nên là Mongo::DB, không phải %{name}.
         invalid_type:

lib/config/locales/zh-CN.yml

@@ -10,6 +10,9 @@ zh-CN:
           已占用
         document_not_found:
           没有发现类是%{klass}id(s)是%{identifiers}的文档
+        eager_load:
+          "Eager loading :%{name} is not supported due to it being a many-to-many
+          relation."
         invalid_database:
           数据库应该是Mongo::DB,而不是%{name}.
         invalid_type:

lib/mongoid/errors.rb

@@ -2,6 +2,7 @@
 require "mongoid/errors/mongoid_error"
 require "mongoid/errors/callback"
 require "mongoid/errors/document_not_found"
+require "mongoid/errors/eager_load"
 require "mongoid/errors/invalid_collection"
 require "mongoid/errors/invalid_database"
 require "mongoid/errors/invalid_field"

lib/mongoid/errors/eager_load.rb

@@ -0,0 +1,25 @@
+# encoding: utf-8
+module Mongoid #:nodoc
+  module Errors #:nodoc
+
+    # This error is raised when attempting to eager load a many to many
+    # relation.
+    class EagerLoad < MongoidError
+
+      attr_reader :name
+
+      # Create the new eager load error.
+      #
+      # @example Create the new eager load error.
+      #   EagerLoad.new(:preferences)
+      #
+      # @param [ Symbol ] name The name of the relation.
+      #
+      # @since 2.2.0
+      def initialize(name)
+        @name = name
+        super(translate("eager_load", { :name => name }))
+      end
+    end
+  end
+end

lib/mongoid/relations/referenced/many_to_many.rb

@@ -245,9 +245,7 @@ def criteria(metadata, object, type = nil)
           #
           # @since 2.2.0
           def eager_load(metadata, criteria)
-            raise RuntimeError.new(
-              "Eager loading many-to-many relations is not supported."
-            )
+            raise Errors::EagerLoad.new(metadata.name)
           end
 
           # Returns true if the relation is an embedded one. In this case