Opened 8 years ago

Closed 3 years ago

#27694 closed Cleanup/optimization (fixed)

Improve documentation of supported lookups on HStore & JSON fields

Reported by: Stephen Burrows Owned by: Sarah Abderemane
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

The documentation of supported lookups on HStore & JSON fields is lacking. For example, HStoreField supports iexact lookups, but the documentation has a scary warning implying that this is not the case:

Since any string could be a key in a hstore value, any lookup other than those listed below will be interpreted as a key lookup.

iexact is not listed below – but neither is contains, which is used directly above the scary warning as an example of how "You can chain other lookups after key lookups". (Actually, contains is listed below, but it's a different contains that applies only to the field level and not to a specific key.)

I suspect that the intended meaning is that all lookups are supported after a key lookup, and that the first lookup on the hstore field must be a key or one of the special lookups listed below.

JSONField does not mention being able to chain lookups after key lookups at all - but I can see people using gt and in in blog posts like this. BUT iexact lookups don't currently work on JSONField.

Change History (17)

comment:1 by Tim Graham, 8 years ago

Triage Stage: UnreviewedAccepted
Type: BugCleanup/optimization

comment:2 by Mariusz Felisiak, 5 years ago

JSONField-part of this ticket is fixed as a part of PR.

comment:3 by Mariusz Felisiak <felisiak.mariusz@…>, 4 years ago

In 6789ded0:

Fixed #12990, Refs #27694 -- Added JSONField model field.

Thanks to Adam Johnson, Carlton Gibson, Mariusz Felisiak, and Raphael
Michel for mentoring this Google Summer of Code 2019 project and
everyone else who helped with the patch.

Special thanks to Mads Jensen, Nick Pope, and Simon Charette for
extensive reviews.

Co-authored-by: Mariusz Felisiak <felisiak.mariusz@…>

comment:4 by Mariusz Felisiak, 4 years ago

Easy pickings: set

comment:5 by Jacob Walls, 3 years ago

Has patch: set
Owner: changed from nobody to cammil
Status: newassigned

comment:6 by Mariusz Felisiak, 3 years ago

Has patch: unset
Owner: cammil removed
Status: assignednew

Jacob, this patch has nothing to do with the HStore docs.

comment:7 by cammil, 3 years ago

Yeh. Not sure what that PR has to do with this ticket. Seems completely unrelated to me.

comment:8 by Jacob Walls, 3 years ago

Thanks, I've asked the author of the unrelated patch to update the ticket number he referenced. Sorry for the noise (and for not reading the patch before linking here).

comment:9 by Sarah Abderemane, 3 years ago

I'd be happy to help on this issue but HStore is new for me, iexact on HStoreField lookup, it's based on which SQL operator ?
Same as contains @> but it's with case-insensitive or another one ?

in reply to:  9 comment:10 by Mariusz Felisiak, 3 years ago

Replying to Sarah Abderemane:

I'd be happy to help on this issue but HStore is new for me, iexact on HStoreField lookup, it's based on which SQL operator ?
Same as contains @> but it's with case-insensitive or another one ?

iexact and other text-lookups should work on key transforms on HStoreField because it returns TextField. Maybe it's enough to add a similar note to the one about JSONField, e.g.:

.. note::

    Key transforms can also be chained with: :lookup:`contains`,
    :lookup:`icontains`, :lookup:`endswith`, :lookup:`iendswith`,
    :lookup:`iexact`, :lookup:`regex`, :lookup:`iregex`, :lookup:`startswith`,
    and :lookup:`istartswith`.

This is untested so some tests will also be required.

comment:11 by Sarah Abderemane, 3 years ago

Owner: set to Sarah Abderemane
Status: newassigned

Thanks Mariusz, I'll try to see for that

comment:12 by Jacob Walls, 3 years ago

Has patch: set

comment:13 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 533f345:

Refs #27694 -- Added more tests for chaining lookups with HStoreField key transforms.

comment:14 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 1953dd0:

Refs #27694 -- Doc'd lookups that can be chained with HStoreField key transforms.

comment:15 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 7fa946c7:

[4.0.x] Refs #27694 -- Doc'd lookups that can be chained with HStoreField key transforms.

Backport of 1953dd02b6719ee89fddbc3098d86968d79f3cd7 from main

comment:16 by Mariusz Felisiak <felisiak.mariusz@…>, 3 years ago

In 51e4dbfe:

[3.2.x] Refs #27694 -- Doc'd lookups that can be chained with HStoreField key transforms.

Backport of 1953dd02b6719ee89fddbc3098d86968d79f3cd7 from main

comment:17 by Mariusz Felisiak, 3 years ago

Resolution: fixed
Status: assignedclosed
Note: See TracTickets for help on using tickets.
Back to Top