Is there a reason to why ActiveRecord::Associations::Preloader is a nodoc?

[hovsater]

Just recently I stumbled across a problem where I had to a pretty complex query using .find_by_sql. Unfortunately, eager loading in the form of .includes, doesn't work with that finder method.

After asking around, I got introduced to ActiveRecord::Associations::Preloader which came very handy in this particular situation. I was surprised to see that it was marked as a nodoc (see https://github.com/rails/rails/blob/master/activerecord/lib/active_record/associations/preloader.rb), even though it's very well documented.

Is there any reason to this? Otherwise, I'd suggest to remove the nodoc mark and introduce it to the rest of the community.

[rafaelfranca]

It is marked as nodoc because It is for internal use of the framework and should not be used in user applications.

[andyh]

@rafaelfranca is there a better "rails-way" of acheving this that is part of the public api? I've seen this come up a few times recently. The key thing is that we want a way to load the associated objects too so we can't just do the joins in the find_by_sql

[rafaelfranca]

Using find_by_sql there is no way. But I pretty sure this same query can be written using the Active Record API.

[hovsater]

@rafaelfranca I see. But I don't think we should close this issue just yet. Currently this is a problem. Some queries just isn't suited for the Active Record API and I'll assume this is why .find_by_sql was created. I think it's fair to assume there should be an alternative to eager load records when the API isn't sufficient.

Don't you agree?

[rafaelfranca]

Could you show an example where the API is not suited?

I agree that find_by_sql is a low level API, but you can't expect to have the same features of the high level API using it.

[rafaelfranca]

Also I closed this issue since discussion can't be done on the issues tracker and in my opinion this is not an issue since you are expecting a low level API should work as a high level API.

[hovsater]

Some complex SQL queries aren't suited for the API, I guess we both can agree on that? For those types of situations I'd assume that if other low level features such as .find_by_sql is documented, why not document the Preloader as well.

It's handy to use the lower level API when the higher level API falls short. It's also easy to explicitly document a feature as low level, or in other ways state that it isn't a part of the higher level API.

I claim that this change is beneficial due to it giving advanced users an easier to overcome "complex" problems, while not getting in the way for ordinary users.

I didn't know that discussions were not allowed, so if this is the case, I'm sorry. I just want to prove my point.

[rafaelfranca]

Some complex SQL-queries isn't suited for the API, I guess we both can agree on that?

I never used find_by_sql in a project, so I can't agree with this.

It's handy to use the lower level API when the higher level API falls short. It's also easy to explicitly document a feature as low level, or in other ways state that it isn't a part of the higher level API.

Yes, agree with this. But like I said, you can't expect the lower level API works in the same way and with the same features that the higher level API.

I claim that this change is beneficial due to it giving advanced user an easier to overcome "complex" problems, while not getting in the way for an ordinary user.

I don't think we should add preloader to the public API. It is a complicated feature and adding it to public API will mean we have to support the actual API across releases removing the flexibility when evolving the framework.

But advanced users can still use it, but we don't guarantee it will not change between releases. It is the same case of arel.

I didn't know that discussions were not allowed, so if this is the case, I'm sorry.

No problem. Discussions should be done on the Rails Core mailing list. We keep the issues tracker for issues and pull requests.

I'd like to hear @jeremy @jonleighton and @tenderlove about this one, so I'm reopening.

I just want to prove my point.

Noted.

[senny]

recently there was another ticket where using the Preloader was the best way to solve the issue #10912.

/cc @josevalim

[Bertg]

@senny Thx for mentioning my old issue here.

I do think if the Preloader would be public I would not have spent the time on that pull request and just use the feature that is hidden here in the docs.

[rafaelfranca]

To make preload public API we need a lot of work. Right now the method signature is not easy to use. Also, I'm more inclined to make find_by_sql to work with include than making an internal class public.

That said I'm closing this issue since it is more a discussion, but I would love to see some implementation to make preload possible using custom SQL, or some kind of high level API easier to use than this private class.