Re: Documentation/help for materialized and recursive views

Is there a particular reason why CREATE RECURSIVE VIEW is part of the
help for CREATE VIEW, but CREATE MATERIALIZED VIEW doesn't show up
there?

I realize the technical reason (they're different man pages, and that
also controls what's in \h in psql which is where I ran into it), but
was there any particular reason to split those up in the first place?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

2013/6/27 Magnus Hagander <magnus(at)hagander(dot)net>:

> Is there a particular reason why CREATE RECURSIVE VIEW is part of the
> help for CREATE VIEW, but CREATE MATERIALIZED VIEW doesn't show up
> there?
>
> I realize the technical reason (they're different man pages, and that
> also controls what's in \h in psql which is where I ran into it), but
> was there any particular reason to split those up in the first place?

Normal views are an abstraction layer, while materialized views
(despite containing the word “view”) are mainly a performance tool (in
a way similar to indexes).

The functionality of materialized views will (over time) totally swamp
that of normal views, so mixing all the corresponding documentation
with the documentation for normal views probably doesn’t make things
easier for people that are only interested in normal views.

Nicolas

--
A. Because it breaks the logical sequence of discussion.
Q. Why is top posting bad?

On Thu, Jun 27, 2013 at 10:56 AM, Nicolas Barbier
<nicolas(dot)barbier(at)gmail(dot)com> wrote:
> 2013/6/27 Magnus Hagander <magnus(at)hagander(dot)net>:
>
>> Is there a particular reason why CREATE RECURSIVE VIEW is part of the
>> help for CREATE VIEW, but CREATE MATERIALIZED VIEW doesn't show up
>> there?
>>
>> I realize the technical reason (they're different man pages, and that
>> also controls what's in \h in psql which is where I ran into it), but
>> was there any particular reason to split those up in the first place?
>
> Normal views are an abstraction layer, while materialized views
> (despite containing the word “view”) are mainly a performance tool (in
> a way similar to indexes).

Oh yes, I'm well aware of this of course.

> The functionality of materialized views will (over time) totally swamp
> that of normal views, so mixing all the corresponding documentation
> with the documentation for normal views probably doesn’t make things
> easier for people that are only interested in normal views.

That's a better point I think. That said, it would be very useful if
it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
should just add the syntax to that page, and then link said future
information on a separate page somehow?

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

On Thu, Jun 27, 2013 at 5:29 AM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>> The functionality of materialized views will (over time) totally swamp
>> that of normal views, so mixing all the corresponding documentation
>> with the documentation for normal views probably doesn’t make things
>> easier for people that are only interested in normal views.
>
> That's a better point I think. That said, it would be very useful if
> it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
> should just add the syntax to that page, and then link said future
> information on a separate page somehow?

IMHO, it's better to keep them separate; they are very different beasts.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> Magnus Hagander <magnus(at)hagander(dot)net> wrote:

>>> The functionality of materialized views will (over time) totally swamp
>>> that of normal views, so mixing all the corresponding documentation
>>> with the documentation for normal views probably doesn’t make things
>>> easier for people that are only interested in normal views.
>>
>> That's a better point I think. That said, it would be very useful if
>> it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
>> should just add the syntax to that page, and then link said future
>> information on a separate page somehow?
>
> IMHO, it's better to keep them separate; they are very different beasts.

+1

Although I wonder whether we shouldn't cross-link those pages....

 
--
Kevin Grittner
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On Fri, Jun 28, 2013 at 5:54 AM, Kevin Grittner <kgrittn(at)ymail(dot)com> wrote:
> Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
>> Magnus Hagander <magnus(at)hagander(dot)net> wrote:
>
>>>> The functionality of materialized views will (over time) totally swamp
>>>> that of normal views, so mixing all the corresponding documentation
>>>> with the documentation for normal views probably doesn’t make things
>>>> easier for people that are only interested in normal views.
>>>
>>> That's a better point I think. That said, it would be very useful if
>>> it actually showed up in "\h CREATE VIEW" in psql - I wonder if we
>>> should just add the syntax to that page, and then link said future
>>> information on a separate page somehow?
>>
>> IMHO, it's better to keep them separate; they are very different beasts.
>
>
> +1
>
> Although I wonder whether we shouldn't cross-link those pages....

They are already crosslinked under "see also". But that doesn't really
help the guy doing "\h CREATE VIEW" in psql, which was the case where
it was brought to my attention.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

Magnus Hagander escribió:

> They are already crosslinked under "see also". But that doesn't really
> help the guy doing "\h CREATE VIEW" in psql, which was the case where
> it was brought to my attention.

Maybe \h should somehow display the "see also" section?

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

On Fri, Jun 28, 2013 at 4:49 PM, Alvaro Herrera
<alvherre(at)2ndquadrant(dot)com> wrote:
> Magnus Hagander escribió:
>
>> They are already crosslinked under "see also". But that doesn't really
>> help the guy doing "\h CREATE VIEW" in psql, which was the case where
>> it was brought to my attention.
>
> Maybe \h should somehow display the "see also" section?

I've been toying with the idea getting \h to show an actual http://
link to the reference page on the website, since most terminals lets
you deal with URLs easily lately. I haven't actually looked into how
feasible that would be though, but it would be interesting to check
out. (With a toggle to turn it on/off of course)

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

On 6/28/13 10:49 AM, Alvaro Herrera wrote:
> Magnus Hagander escribió:
>
>> They are already crosslinked under "see also". But that doesn't really
>> help the guy doing "\h CREATE VIEW" in psql, which was the case where
>> it was brought to my attention.
>
> Maybe \h should somehow display the "see also" section?

You can run \! man from within psql, which should give you everything
you need. It's admittedly a bit obscure, but it's there. Maybe it
ought to be added to the initial help output.

Peter Eisentraut escribió:
> On 6/28/13 10:49 AM, Alvaro Herrera wrote:
> > Magnus Hagander escribió:
> >
> >> They are already crosslinked under "see also". But that doesn't really
> >> help the guy doing "\h CREATE VIEW" in psql, which was the case where
> >> it was brought to my attention.
> >
> > Maybe \h should somehow display the "see also" section?
>
> You can run \! man from within psql, which should give you everything
> you need. It's admittedly a bit obscure, but it's there. Maybe it
> ought to be added to the initial help output.

That's a neat trick, but obviously it won't work in Windows. Maybe we
ought to have \man ..

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services

On Fri, Jun 28, 2013 at 01:34:17PM -0400, Peter Eisentraut wrote:
> On 6/28/13 10:49 AM, Alvaro Herrera wrote:
> > Magnus Hagander escribió:
> >
> >> They are already crosslinked under "see also". But that doesn't
> >> really help the guy doing "\h CREATE VIEW" in psql, which was the
> >> case where it was brought to my attention.
> >
> > Maybe \h should somehow display the "see also" section?
>
> You can run \! man from within psql,

And if you're on Windows, you're Sadly Out of Luck with that. Is
there an equivalent we could #ifdef in for that platform?

Cheers,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david(dot)fetter(at)gmail(dot)com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

On 6/28/13 2:27 PM, David Fetter wrote:
>> You can run \! man from within psql,
> And if you're on Windows, you're Sadly Out of Luck with that. Is
> there an equivalent we could #ifdef in for that platform?

If you are using psql on Windows extensively, you probably have one of
mingw, cygwin, or pgadmin handy, all of which can get you to the
documentation. I don't think it's worth devising a mechanism for those
not covered by this.

On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:
> On 6/28/13 2:27 PM, David Fetter wrote:
> >> You can run \! man from within psql,
> > And if you're on Windows, you're Sadly Out of Luck with that. Is
> > there an equivalent we could #ifdef in for that platform?
>
> If you are using psql on Windows extensively, you probably have one of
> mingw, cygwin, or pgadmin handy, all of which can get you to the
> documentation. I don't think it's worth devising a mechanism for those
> not covered by this.

With deepest respect, failing to provide documentation to users on our
widest-deployed platform seems pretty hostile to me. There was an
earlier suggestion that we provide URLs, which seems like a decent way
forward as those environments so locked down as to disallow outbound
HTTP are pretty rare, and non-networked computers are even more rare.

Cheers,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david(dot)fetter(at)gmail(dot)com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

On 7/1/13 10:20 AM, David Fetter wrote:
> On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:
>> On 6/28/13 2:27 PM, David Fetter wrote:
>>>> You can run \! man from within psql,
>>> And if you're on Windows, you're Sadly Out of Luck with that. Is
>>> there an equivalent we could #ifdef in for that platform?
>>
>> If you are using psql on Windows extensively, you probably have one of
>> mingw, cygwin, or pgadmin handy, all of which can get you to the
>> documentation. I don't think it's worth devising a mechanism for those
>> not covered by this.
>
> With deepest respect, failing to provide documentation to users on our
> widest-deployed platform seems pretty hostile to me.

As I argue above, I don't think this is the widest-deployed platform.
The actual platform in use is either mingw, which has man, or
click-and-drool, which has pgadmin, both of which provide the documentation.

> There was an
> earlier suggestion that we provide URLs, which seems like a decent way
> forward as those environments so locked down as to disallow outbound
> HTTP are pretty rare, and non-networked computers are even more rare.

Does clicking on links in cmd.exe do anything useful?

On Mon, Jul 01, 2013 at 10:52:55AM -0400, Peter Eisentraut wrote:
> On 7/1/13 10:20 AM, David Fetter wrote:
> > On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:
> >> On 6/28/13 2:27 PM, David Fetter wrote:
> >>>> You can run \! man from within psql,
> >>> And if you're on Windows, you're Sadly Out of Luck with that.
> >>> Is there an equivalent we could #ifdef in for that platform?
> >>
> >> If you are using psql on Windows extensively, you probably have
> >> one of mingw, cygwin, or pgadmin handy, all of which can get you
> >> to the documentation. I don't think it's worth devising a
> >> mechanism for those not covered by this.
> >
> > With deepest respect, failing to provide documentation to users on
> > our widest-deployed platform seems pretty hostile to me.
>
> As I argue above, I don't think this is the widest-deployed
> platform. The actual platform in use is either mingw, which has
> man, or click-and-drool, which has pgadmin, both of which provide
> the documentation.

I'm not going to get into a big definitional wrangle here. "Has
available" (as in you could install software if you wanted to) is a
pretty long distance from "actually handy," which URLs are a bit
closer to.

> > There was an earlier suggestion that we provide URLs, which seems
> > like a decent way forward as those environments so locked down as
> > to disallow outbound HTTP are pretty rare, and non-networked
> > computers are even more rare.
>
> Does clicking on links in cmd.exe do anything useful?

Apparently

start URL

works for some large class of URLs. More details here:
http://www.dwheeler.com/essays/open-files-urls.html

Cheers,
David.
--
David Fetter <david(at)fetter(dot)org> http://fetter.org/
Phone: +1 415 235 3778 AIM: dfetter666 Yahoo!: dfetter
Skype: davidfetter XMPP: david(dot)fetter(at)gmail(dot)com
iCal: webcal://www.tripit.com/feed/ical/people/david74/tripit.ics

Remember to vote!
Consider donating to Postgres: http://www.postgresql.org/about/donate

On Mon, Jul 1, 2013 at 10:20 AM, David Fetter <david(at)fetter(dot)org> wrote:
> With deepest respect, failing to provide documentation to users on our
> widest-deployed platform seems pretty hostile to me.

Yes, that would be pretty hostile. However, we don't do anything that
remotely resembles that statement, nor has anyone proposed any such
thing.

Personally, I think this whole thread is much ado about nothing.
Magnus is basically arguing that people might expect that CREATE VIEW
ought to tell you about CREATE MATERIALIZED VIEW also, but I don't
find that argument to have a whole lot of merit. Views and
materialized views are pretty different things; it is a bit like
asking why Googling for "dog" does not give you information on hot
dogs. The output of psql's \h command is intended to be a succinct
synopsis summarizing the salient syntax (try saying that five times
fast), not a comprehensive reference. If you want the latter, read
the fine manual. I admit that this particular case is slightly more
prone to confusion than some, but I'm just not that exercised about
it. Every bit of detail we add to the \h output is better for the
people who otherwise would have been unhappy, but it's worse for all
the people who did need it because it's more to read through.

Regardless of whether you agree with or disagree with the above
statement, building a high-quality documentation reader into psql so
that users who are running Windows but not mingw, cygwin, or pgAdmin
can access the documentation more easily doesn't seem like the correct
solution to this problem. I don't really object if somebody wants to
do it (although someone else may object) but it's certainly taking the
long way around as far as this particular confusion is concerned.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 07/01/2013 03:26 PM, Robert Haas wrote:
> Regardless of whether you agree with or disagree with the above
> statement, building a high-quality documentation reader into psql so
> that users who are running Windows but not mingw, cygwin, or pgAdmin
> can access the documentation more easily doesn't seem like the correct
> solution to this problem. I don't really object if somebody wants to
> do it (although someone else may object) but it's certainly taking the
> long way around as far as this particular confusion is concerned.

FWIW, in my reasonably substantial experience, virtually every user on
Windows uses pgadmin3. Use of psql is fairly rare.

cheers

andrew

On Mon, Jul 1, 2013 at 9:26 PM, Robert Haas <robertmhaas(at)gmail(dot)com> wrote:
> On Mon, Jul 1, 2013 at 10:20 AM, David Fetter <david(at)fetter(dot)org> wrote:
>> With deepest respect, failing to provide documentation to users on our
>> widest-deployed platform seems pretty hostile to me.
>
> Yes, that would be pretty hostile. However, we don't do anything that
> remotely resembles that statement, nor has anyone proposed any such
> thing.
>
> Personally, I think this whole thread is much ado about nothing.
> Magnus is basically arguing that people might expect that CREATE VIEW
> ought to tell you about CREATE MATERIALIZED VIEW also, but I don't
> find that argument to have a whole lot of merit. Views and
> materialized views are pretty different things; it is a bit like

How different are they really? Yes, they are very different from an
implementation standpoint, from an enduser perspective they really are
not. If they were, they'd probably be called something else..

> asking why Googling for "dog" does not give you information on hot
> dogs. The output of psql's \h command is intended to be a succinct

I'd personally say it's more like googling for dog gives me hits
specifically around "dog breeding" and not just dogs themselves.

> synopsis summarizing the salient syntax (try saying that five times
> fast), not a comprehensive reference. If you want the latter, read
> the fine manual. I admit that this particular case is slightly more
> prone to confusion than some, but I'm just not that exercised about
> it. Every bit of detail we add to the \h output is better for the
> people who otherwise would have been unhappy, but it's worse for all
> the people who did need it because it's more to read through.

True.

> Regardless of whether you agree with or disagree with the above
> statement, building a high-quality documentation reader into psql so
> that users who are running Windows but not mingw, cygwin, or pgAdmin
> can access the documentation more easily doesn't seem like the correct
> solution to this problem. I don't really object if somebody wants to
> do it (although someone else may object) but it's certainly taking the
> long way around as far as this particular confusion is concerned.

I still think a better option to that would be to get psql to provide
a link to the full documentation there.

pgAdmin could also do that, but doesn't - it gets you a link to the
main documentation, but not a context sensitive one IIRC.

--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/

On Mon, Jul 1, 2013 at 3:57 PM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> How different are they really? Yes, they are very different from an
> implementation standpoint, from an enduser perspective they really are
> not. If they were, they'd probably be called something else.

They're different because they consume storage, require effort to
update, and aren't always up-to-date. Those things are all quite
user-visible.

> I still think a better option to that would be to get psql to provide
> a link to the full documentation there.

It seems like clutter to me, but I'll defer to whatever the consensus is.

--
Robert Haas
EnterpriseDB: http://www.enterprisedb.com
The Enterprise PostgreSQL Company

On 07/01/2013 07:20 AM, David Fetter wrote:
>
> On Mon, Jul 01, 2013 at 10:05:24AM -0400, Peter Eisentraut wrote:
>> On 6/28/13 2:27 PM, David Fetter wrote:
>>>> You can run \! man from within psql,
>>> And if you're on Windows, you're Sadly Out of Luck with that. Is
>>> there an equivalent we could #ifdef in for that platform?
>>
>> If you are using psql on Windows extensively, you probably have one of
>> mingw, cygwin, or pgadmin handy, all of which can get you to the
>> documentation. I don't think it's worth devising a mechanism for those
>> not covered by this.
>
> With deepest respect, failing to provide documentation to users on our
> widest-deployed platform seems pretty hostile to me. There was an
> earlier suggestion that we provide URLs, which seems like a decent way
> forward as those environments so locked down as to disallow outbound
> HTTP are pretty rare, and non-networked computers are even more rare.
>

Although I agree with the sentiment the idea that postgres more widely
deployed on windows than other platforms is rather laughable. The only
metrics we have are "downloads" which doesn't count cause linux ships
with postgres with a simple yum or apt-get.

Whatever solution we decide, we should not push this responsibility off
on pgadmin as pgadmin is not part of PostgreSQL but a third party tool.
The "standard" postgresql client is psql (for good or bad) and we should
support psql fully on all platforms.

Sincerely,

Joshua D. Drake

--
Command Prompt, Inc. - http://www.commandprompt.com/ 509-416-6579
PostgreSQL Support, Training, Professional Services and Development
High Availability, Oracle Conversion, Postgres-XC, @cmdpromptinc
For my dreams of your image that blossoms
a rose in the deeps of my heart. - W.B. Yeats

Robert Haas escribió:
> On Mon, Jul 1, 2013 at 3:57 PM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:

> > I still think a better option to that would be to get psql to provide
> > a link to the full documentation there.
>
> It seems like clutter to me, but I'll defer to whatever the consensus is.

I second the idea of having psql's \h provide a link to the command's
specific reference page.

--
Álvaro Herrera http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Training & Services