Subject: Re: [PATCHES] Partitioning docs
From: Simon Riggs <simon@2ndquadrant.com>
To: Neil Conway <neilc@samurai.com>
Cc: pgsql-patches@postgresql.org, pgsql-docs@postgresql.org
In-Reply-To: <1130887177.6884.38.camel@localhost.localdomain>
References: <1130726816.8300.1377.camel@localhost.localdomain>
	<1130798509.8300.1536.camel@localhost.localdomain>
	<1130887177.6884.38.camel@localhost.localdomain>
Content-Type: text/plain
Organization: 2nd Quadrant
Date: Wed, 02 Nov 2005 19:55:18 +0000
Message-Id: <1130961318.8300.1794.camel@localhost.localdomain>
Mime-Version: 1.0
Content-Transfer-Encoding: 7bit

On Tue, 2005-11-01 at 18:19 -0500, Neil Conway wrote:
> On Mon, 2005-31-10 at 22:41 +0000, Simon Riggs wrote: 
> > I believe this is now complete and ready for application.
> 
> Comments:
> 
> - INSERT, UPDATE, etc. should be marked with <command/>, unless <xref/>
> would be more appropriate
> 
> - The names of GUC variables should be marked up with <varname/>, unless
> <xref/> would be more appropriate
> 
> - <xref> tags that link to the reference page of an SQL command should
> be of the form: <xref linkend="sql-..." endterm="sql-...-title"> -- the
> endterm attribute should not be omitted.
> 
> - "PostgreSQL" should be marked-up with <productname/>
> 
> - In text like "You can use RULEs to ...", "rules" would be better.
> 
> - The word following a colon should not be capitalized
> 
> - "&mdash;" is an em dash, "--" and "---" are not
> 
> - "indexes", not "indices"

Thanks very much for a thorough review.

> - Why "Constraint Exclusion" (or worse, "the Constraint Exclusion
> feature") rather than simply "constraint exclusion"? 

OK

> (I'm not even sure
> it's a good idea to mention this term in end-user documentation.)

We now have a parameter called constraint_exclusion, so the term already
exists and so requires explanation. I would have had no objection to
modifications of that term, but it has been in use now for 4 months, so
changing it doesn't seem practical.

> - I removed a few statements and paragraphs I thought were unnecessary
> (e.g. Postgres was the first DBMS to have inheritance, some vague and
> IMHO useless advice about query optimization differences with inherited
> tables, etc.). Feel free to resubmit them if you disagree (although
> perhaps not for 8.1.0).

Trying to identify which bit of advice you refer to.... I put some
comments in based upon feedback from the beta on specific queries that
were not optimised the same as non-inherited tables. If thats what
you're talking about, then I'd like to put that back. The manuals aren't
written for you and me; why let others stumble when they could have it
in black and white?

> + All constraints on all partitions of the master table are considered
> for
> + Constraint Exclusion, so large numbers of partitions are likely to 
> + increase query parse time considerably.
> 
> Wouldn't it primarily increase planning time, not parsing time?

Yes. ....What generic term would you use for query compilation? query
preparation? The distinction of parsing/planning/optimization etc is
lost on most people.

> + <para>
> +  CE only works when the query directly matches a constant. A
> +  constant bound to a parameterised query will not work in the same way
> +  since the plan is fixed and would need to vary with each execution.
> +  Also, stable constants such as CURRENT_DATE may not be used, since
> +  these are constant only for during the execution of a single query.
> +  Joins conditions will not allow CE to work either.
> + </para>
> 
> I'm not sure what the last sentence is intended to mean.

OK, I'll work on a longer explanation of that.

> Revised patch attached and applied. There are at least a few more things
> that need cleaning up -- if no one beats me to it I'll do that shortly.

Best Regards, Simon Riggs