From: Tom Lane <tgl@sss.pgh.pa.us>
To: "David G. Johnston" <david.g.johnston@gmail.com>
cc: Adrien Nayrat <adrien.nayrat@dalibo.com>, pgsql-docs@postgresql.org
Subject: Re: Text operators "~<=~ ~<~ ~>=~ ~>~" not documented
In-reply-to: 
 <CAKFQuwZiuWg5QEk-tN+=Y8JS1cY-xFxe0xZKbMLBh1TM-fSh7w@mail.gmail.com>
References: <92d30118-9933-3674-a95b-f84c97abde6c@dalibo.com>
 <CAKFQuwZiuWg5QEk-tN+=Y8JS1cY-xFxe0xZKbMLBh1TM-fSh7w@mail.gmail.com>
Comments: In-reply-to "David G. Johnston" <david.g.johnston@gmail.com>
	message dated "Thu, 08 Feb 2018 08:32:50 -0700"
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <25752.1518104554.1@sss.pgh.pa.us>
Date: Thu, 08 Feb 2018 10:42:34 -0500
Message-ID: <25753.1518104554@sss.pgh.pa.us>
Precedence: bulk

"David G. Johnston" <david.g.johnston@gmail.com> writes:
> On Thu, Feb 8, 2018 at 6:26 AM, Adrien Nayrat <adrien.nayrat@dalibo.com>
> wrote:
>> While reading [1] I notice $subject operators lacks of explanation in
>> documentation.

> I'd be inclined to remove those four operators from the spgist page's table
> and replace them with "LIKE".  Then in the text below the table explain
> that LIKE is implemented using a combination of those four operators.

I believe it's intentional that those operators aren't documented: we
don't want people to get in the habit of using them directly.  (These
days, if you actually need what they do, the approved way to spell it
is like 'x < y COLLATE "C"'.)

So actually, my inclination would be to remove them from the spgist table
and put nothing back.  Implying that spgist text_ops fully supports LIKE
would certainly be wrong/confusing --- we do not claim in the main part
of the docs that btree text_ops supports LIKE, even though it has a
comparable level of support as long as you're using C collation.

Since these operators are user-visible in EXPLAIN output, there might be
merit in mentioning them in passing in the LIKE docs.  But we should not
put them in a table with the LIKE ops themselves, IMO.  That would just
invite confusion about what they do and whether you're supposed to use
them directly.

			regards, tom lane