Better documentation and defaults for BoolOr and BoolAnd

[Alex Scott]

The only documentation available (that I found at least) for Postgres DB functions is:
​https://docs.djangoproject.com/en/3.0/ref/contrib/postgres/aggregates/

It would be really nice to have an example or two for each of those.

One issue I ran into with BoolOr when I was doing something like BoolOr(Q('someCharField') == Value('someVal')) (which in itself would be a great example to show), is an error:

'Cannot resolve expression type, unknown output_field'

Adding output_field=BooleanField() seemed to solve it but this wasn't intuitive. Shouldn't the default output for BoolOr be boolean? If so, it would be good to set it as such I think.

[Simon Charette]

A patch for both documentation and explicit output_field for BoolOr and BoolAnd would be welcome. The issue you're experiencing here is likely due to the fact Q and WhereNode are marked conditional=True but don't set output_field = models.BooleanField() and thus the default behavior of Expression._resolve_output_field cannot be leveraged.

Are you interested in submitting a PR with these improvements?

[Alex Scott]

Thanks Simon for the quick response. I'm a bit of a n00b and have never really contributed a PR to an open source project but maybe this could be the first. Do you think setting the default is all that needs to be done? I can try to take a look over this next week (and read about how to contribute) and let you know if I think I'm capable.

Replying to Simon Charette:

A patch for both documentation and explicit output_field for BoolOr and BoolAnd would be welcome. The issue you're experiencing here is likely due to the fact Q and WhereNode are marked conditional=True but don't set output_field = models.BooleanField() and thus the default behavior of Expression._resolve_output_field cannot be leveraged.

Are you interested in submitting a PR with these improvements?

[Simon Charette]

Do you think setting the default is all that needs to be done?

yeah, defining BoolOr.output_field = models.BooleanField() at the class level (for BoolAnd as well) should be enough.

For the tests an extra method in ​tests/postgres_tests/test_aggregates.py for usage of Q objects for both functions should be enough for each aggregate function.

e.g.

def test_bool_or_q_object(self):
    values = AggregateTestModel.objects.aggregate(boolor=BoolOr(Q(integer_field__gt=2))
    self.assertEqual(values, {'boolor': False})

I think examples in ​the documentation would also be welcome.

[David Chorpash]

I am interested in working this ticket. I know plenty of time has passed since this was last modified, but I'll give it up to Alex if he wants to give it a shot within the next day or so.

[Alex Scott]

Thanks David! Please do. Day job work got in the way of me taking a stab at this and I'll continue to be busy for the next few weeks. So happy for you to take it.

[David Chorpash]

Alex, I understand how that goes!

Simon, I submitted a ​PR and I wanted to make sure I set it up where I'm merging to the correct branch. This is the first time submitting a PR for a ticket where the version was not set to master.

Since the version is set to 3.0, I'm going to be merging into the stable/3.1.x. Is that correct?

[Simon Charette]

Thanks for your PR Alex!

I left some comments on Github but you'll want to target the master branch instead of stable/3.1.x, mergers will take care of the backport if necessary.

I also think it might be worth documenting the usage of Q objects for these aggregates and not solely boolean fields.

[David Chorpash]

Thank you for the feedback, Simon!

I fixed the PR so that it's targeting master. I also made adjustments based on the comments and added documentation for Q objects.

[Mariusz Felisiak <felisiak.mariusz@…>]

In a2e621b:

Refs #31720 -- Added examples to BoolAnd() and BoolOr() documentation.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 6ec5eb5:

Refs #31720 -- Defined default output_field of BoolAnd() and BoolOr() aggregate functions.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 5360f00:

[3.1.x] Refs #31720 -- Added examples to BoolAnd() and BoolOr() documentation.

Backport of a2e621b14e85836362b7fc0e6b1bf7d7ff98e42b from master

[Mariusz Felisiak <felisiak.mariusz@…>]

In 0a3c1272:

[3.0.x] Refs #31720 -- Added examples to BoolAnd() and BoolOr() documentation.

Backport of a2e621b14e85836362b7fc0e6b1bf7d7ff98e42b from master