Proposal: opt-in Table.filter(**kwargs) with Django-style lookups

[regiscamimura]

Proposal

Add an opt-in Table.filter(**kwargs) classmethod that accepts Django-style lookups and
returns a normal objects() query. It's pure sugar — .where() and the explicit style stay
the default.

# proposed
await Band.filter(popularity__gte=1000, manager__name="Guido")

# equivalent today
await Band.objects().where(
    Band.popularity >= 1000,
    Band.manager.name == "Guido",
)

Why

When filters arrive as data (API query params, config, dynamic sets), you can pass them
straight through — await Band.filter(**criteria) — instead of building expressions by hand.

For example, an endpoint like GET /bands?popularity__gte=1000&manager__name=Guido:

# request.query_params -> {"popularity__gte": "1000", "manager__name": "Guido"}
async def list_bands(request):
    return await Band.filter(**request.query_params)

The lookup name in the URL is the lookup passed to the query — no translation layer.

Scope (first PR, deliberately small)

• bare field → ==
• __in, __gte, __lte, __gt, __lt
• datetime transforms __year / __month / __day / __hour (reusing your Year/etc.)
• nested FK paths: manager__name__in

~40 lines: a lookup parser + the classmethod calling objects().where(...). No new query
machinery. Returns Objects, so it chains as usual.

Questions before I PR

1. Open to this as opt-in (explicit style stays the default)?
2. Prefer Table.filter(**kwargs), or a standalone helper passed into .where(...)?
3. Is the operator/transform set above right for a first PR, or trim further?

Happy to implement with tests + docs once you confirm the direction. Thanks!

[dantownsend]

It's an interesting idea.

In some places we allow columns with joins to be specified as column_a.column_b. For example:

>>> await Band.select('manager.name')

I guess there are two things here:

1. Making the syntax closer to Django for easier adoption
2. Making it easier to pass in filters provided as URL params

For 1. I don't mind us having some kind of Model class (in somewhere like compat.django.models).

It inherits from Table, but has a filter method, and maybe something like an objects property which maps to objects().

The question is whether we just have the filter method as an optional thing for compatibility with Django, or you can pass that syntax into Table.where too.

[regiscamimura]

So moving the discussion to code level. I have this draft PR that implements it and explain the pros of using filter and not where.

FYI, the main reason is indeed to have the __in, __gt, etc filters and a way to not translate kwargs into code, not so much to adapt to Django syntax.

Well, I'll wait for comments on the PR and we go from there.