Re: Naming of network_ops vs. inet_ops for SP-GIST

PG Doc comments form <noreply(at)postgresql(dot)org> writes:
> I wanted to add an SP-GIST index for an inet field ip_address
> In https://www.postgresql.org/docs/14/spgist-builtin-opclasses.html
> network_ops is stated as the built-in opclass for (inet, inet)
> I entered the following command:
> # create index concurrently ip_address_spgist_ban_by_ip on ban_by_ip using
> spgist (ip_address network_ops);
> ERROR: operator class "network_ops" does not exist for access method
> "spgist"

Hmm. There's some confusion here, because network_ops is the name of
the operator *family*:

=# \dAf spgist
List of operator families
AM | Operator family | Applicable types
--------+-----------------+------------------
spgist | box_ops | box
spgist | kd_point_ops | point
spgist | network_ops | inet
spgist | poly_ops | polygon
spgist | quad_point_ops | point
spgist | range_ops | anyrange
spgist | text_ops | text
(7 rows)

but inet_ops is the name of the operator *class*:

n=# \dAc spgist
List of operator classes
AM | Input type | Storage type | Operator class | Default?
--------+------------+--------------+----------------+----------
spgist | anyrange | | range_ops | yes
spgist | box | | box_ops | yes
spgist | inet | | inet_ops | yes
spgist | point | | kd_point_ops | no
spgist | point | | quad_point_ops | yes
spgist | polygon | box | poly_ops | yes
spgist | text | | text_ops | yes
(7 rows)

This naming was evidently chosen to match btree, which has both
inet_ops and cidr_ops opclasses within its network_ops family.
spgist only supports inet_ops (and there's not really a reason
to change that, since it will in fact work for cidr too).
But you have to use the class name not the family name when
explicitly selecting an index's opclass.

> I notice inet_ops, not network_ops, is mentioned in the docs for 13. Perhaps
> it was renamed to network_ops in 15 but not 14?

Hmm, apparently somebody decided that the family name was more
appropriate to show here, since the operators are tied to an
opfamily not just an opclass. But the table header still says
"operator classes", so that's incorrect.

We could change the table header, but I'm not sure that that is a
useful direction to take, because people need to use the class name
for index creation but there are few cases where non-developers
need be concerned with family names.

I wonder whether we shouldn't just revert this table to
showing opclass names, and avert our eyes from the theoretical
inconsistency. Michael, looks like it was your 7a1cd5260
that changed it; what do you think?

regards, tom lane