Обсуждение: Remove name as valid parameter for catalog functions
Patch attached which corrects the docs where catalog functions no longer accept values of type name. Originally a note submitted by someone on the docs, but this affects more than just the one they mentioned. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
Вложения
Thom Brown <thom@linux.com> writes: > Patch attached which corrects the docs where catalog functions no > longer accept values of type name. Originally a note submitted by > someone on the docs, but this affects more than just the one they > mentioned. The reason those are phrased as "OID or name" is that what they take is regclass, which means that things like pg_total_relation_size('table_name') do in fact work. I think the proposed wording would leave people with the idea that they had to supply a numeric OID, which is a PITA and not by any means the expected usage. I agree that maybe the original wording could use some improvement, but I don't think that just removing "or name" is an improvement. regards, tom lane
On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Thom Brown <thom@linux.com> writes: >> Patch attached which corrects the docs where catalog functions no >> longer accept values of type name. Originally a note submitted by >> someone on the docs, but this affects more than just the one they >> mentioned. > > The reason those are phrased as "OID or name" is that what they take is > regclass, which means that things like pg_total_relation_size('table_name') > do in fact work. I think the proposed wording would leave people with > the idea that they had to supply a numeric OID, which is a PITA and not > by any means the expected usage. I agree that maybe the original > wording could use some improvement, but I don't think that just removing > "or name" is an improvement. That's fair enough, but it still needs changing, as whilst an OID won't cause an error, a field with the type of name will. Is it reasonable to refer to a parameter as required to be of type regclass? -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
Thom Brown <thom@linux.com> writes: > On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote: >> The reason those are phrased as "OID or name" is that what they take is >> regclass, which means that things like pg_total_relation_size('table_name') >> do in fact work. I think the proposed wording would leave people with >> the idea that they had to supply a numeric OID, which is a PITA and not >> by any means the expected usage. I agree that maybe the original >> wording could use some improvement, but I don't think that just removing >> "or name" is an improvement. > That's fair enough, but it still needs changing, as whilst an OID > won't cause an error, a field with the type of name will. Is it > reasonable to refer to a parameter as required to be of type regclass? Well, the table entries for those functions already show that the parameter is of type regclass. I think the purpose of the text descriptions is to help out people who might not immediately get the implications of that. Maybe we could say "the name or OID of a table", or some such phrase, so as to subtly avoid the expectation that what is being referred to is the datatype named "name"? regards, tom lane
On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Thom Brown <thom@linux.com> writes: >> On 7 March 2011 20:49, Tom Lane <tgl@sss.pgh.pa.us> wrote: >>> The reason those are phrased as "OID or name" is that what they take is >>> regclass, which means that things like pg_total_relation_size('table_name') >>> do in fact work. I think the proposed wording would leave people with >>> the idea that they had to supply a numeric OID, which is a PITA and not >>> by any means the expected usage. I agree that maybe the original >>> wording could use some improvement, but I don't think that just removing >>> "or name" is an improvement. > >> That's fair enough, but it still needs changing, as whilst an OID >> won't cause an error, a field with the type of name will. Is it >> reasonable to refer to a parameter as required to be of type regclass? > > Well, the table entries for those functions already show that the > parameter is of type regclass. I think the purpose of the text > descriptions is to help out people who might not immediately get the > implications of that. > > Maybe we could say "the name or OID of a table", or some such phrase, > so as to subtly avoid the expectation that what is being referred to > is the datatype named "name"? Yes, that would remove the ambiguity. :) -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935
Thom Brown <thom@linux.com> writes: > On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote: >> Maybe we could say "the name or OID of a table", or some such phrase, >> so as to subtly avoid the expectation that what is being referred to >> is the datatype named "name"? > Yes, that would remove the ambiguity. :) That wording turned out not to work well in context, at least not without major surgery on the containing sentences. I decided that the best way was to just say "specified table" in the function tables, and then borrow the paragraph that explains about regclass arguments from the sequence-functions page. http://git.postgresql.org/gitweb?p=postgresql.git;a=commitdiff;h=cfcdc99db67172d46a5e226375fa97e5c5a62267 regards, tom lane
On 8 March 2011 02:54, Tom Lane <tgl@sss.pgh.pa.us> wrote: > Thom Brown <thom@linux.com> writes: >> On 7 March 2011 23:30, Tom Lane <tgl@sss.pgh.pa.us> wrote: >>> Maybe we could say "the name or OID of a table", or some such phrase, >>> so as to subtly avoid the expectation that what is being referred to >>> is the datatype named "name"? > >> Yes, that would remove the ambiguity. :) > > That wording turned out not to work well in context, at least not > without major surgery on the containing sentences. I decided that > the best way was to just say "specified table" in the function tables, > and then borrow the paragraph that explains about regclass > arguments from the sequence-functions page. Thanks Tom. -- Thom Brown Twitter: @darkixion IRC (freenode): dark_ixion Registered Linux user: #516935