Add documentation for prepare_query callback

[Manzanit0]

Simply added an example use case, to make it clearer.

[josevalim]

Thanks for the PR but I am not sure if this is a good example. :) The fields from Ecto.Query are available only to adapter implementations and therefore are between public and private APIs.

[wojtekmach]

@josevalim how about something like this:

## Examples

Let's say you want to filter out records that were "soft-deleted" (have `deleted_at` column set)
from all operations unless an admin is running the query, you can define the callback like this:

    @impl true
    def prepare_query(_operation, query, opts) do
      if opts[:admin] do
        {query, opts}
      else
        query = from(x in query, where: is_nil(x.deleted_at))
        {query, opts}
      end
    end

And then execute the query:

    Repo.all(query)              # only non-deleted records are returned
    Repo.all(query, admin: true) # all records are returned

[wojtekmach]

I updated it on the branch :)

[Manzanit0]

TIL. Cheers! :)

[josevalim]

Excellent! -- *José Valimwww.plataformatec.com.br <http://www.plataformatec.com.br/>Founder and Director of R&D*

[wojtekmach]

Thanks!