Thread: Partitioning docs WIP
I've been working on some docs for Constraining Exclusion & Partitioning for some time now. Deadlines seem to be looming, or may even have passed, so it seems sensible to submit what I have now. It's still a WIP: The final section on queries is not yet complete, but the overall structure and flow makes sense now. Many thanks to Josh Berkus for providing the numbered section on implementation process, which was the starting point I'd been looking for to describe everything else. Any comments welcome now... flames expected for lateness. Best Regards, Simon Riggs
Attachment
On Mon, 2005-10-31 at 02:46 +0000, Simon Riggs wrote: > I've been working on some docs for Constraining Exclusion & Partitioning > for some time now. Deadlines seem to be looming, or may even have > passed, so it seems sensible to submit what I have now. > Many thanks to Josh Berkus for providing the numbered section on > implementation process, which was the starting point I'd been looking > for to describe everything else. I believe this is now complete and ready for application. - passes sgml make against cvstip - spellchecked - all code executed correctly against RC1 Comments please? Apart from the obvious, so why did it take you so long. Apologies to the translators. Best Regards, Simon Riggs
Attachment
On Mon, 2005-31-10 at 22:41 +0000, Simon Riggs wrote: > I believe this is now complete and ready for application. The changes need a fair bit of copy editing and SGML policy work, but that is probably easier to do once it has been applied. Barring any objections I'll apply the patch within 24 hours. -Neil
Neil Conway <neilc@samurai.com> writes:
> On Mon, 2005-31-10 at 22:41 +0000, Simon Riggs wrote:
>> I believe this is now complete and ready for application.
> The changes need a fair bit of copy editing and SGML policy work, but
> that is probably easier to do once it has been applied. Barring any
> objections I'll apply the patch within 24 hours.
I'd argue for editing first and then applying. I'll take up the job
if you don't have time for the editing part... I'm hoping to spend most
of this week on docs editing anyway, since anything else will raise
Marc's hackles about whether we need another RC ;-)
regards, tom lane
On Mon, 2005-31-10 at 23:15 -0500, Tom Lane wrote: > I'd argue for editing first and then applying. I'll take up the job > if you don't have time for the editing part Okay. I'll do a round of copy editing and then commit to CVS -- there will likely be room for additional improvements, so once it's in CVS anyone else who's interested can have at it. -Neil
On Mon, 2005-10-31 at 23:27 -0500, Neil Conway wrote: > On Mon, 2005-31-10 at 23:15 -0500, Tom Lane wrote: > > I'd argue for editing first and then applying. I'll take up the job > > if you don't have time for the editing part > > Okay. I'll do a round of copy editing and then commit to CVS -- there > will likely be room for additional improvements, so once it's in CVS > anyone else who's interested can have at it. Thanks guys. Best Regards, Simon Riggs
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 - "—" is an em dash, "--" and "---" are not - "indexes", not "indices" - Why "Constraint Exclusion" (or worse, "the Constraint Exclusion feature") rather than simply "constraint exclusion"? (I'm not even sure it's a good idea to mention this term in end-user documentation.) - 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). + 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? + <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. 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. -Neil
Attachment
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 > > - "—" 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
On Wed, 2005-02-11 at 19:55 +0000, Simon Riggs wrote: > 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. ISTM that query optimization *always* works differently for inherited versus non-inherited tables, so there are a wide variety of queries you could describe like that. The other problem is the documentation is sufficiently vague that it is of little use, IMHO. Simply saying "query X is optimized differently" without explaining what causes the difference, what the performance impact is likely to be, or how to workaround the problem isn't likely to be very helpful. -Neil