When (and whether) should we improve the chapter on parallel query to accommodate parallel data updates?
Hello,
While I'm reviewing patches for parallel operations, it occured to me that we may need to correct the words and enrich content in "15. Parallel Query". I don't have a concrete image of how the content should be yet, and I think the documentation may be improved after the feature freeze (i.e. April.) Is anyone already doing this kind of modifications?
First, as parallel data updates are being introduced, the chapter title "Parallel Query" should be changed to "Parallel Execution" or "Parallel Operation". It's confusing to see that Postgres uses "query" to also mean statements other than SELECT, but the SQL standard seems to differentiate them; SELECT is explained in "7 Query expressions" and INSERT/DELETE/UPDATE etc. are described in "14 Data manipulation". Following the SQL standard, Postgres manual have separate chapters "6. Data Manipulation" and "7. Queries". (e.g. query plan in EXPLAIN should have been execution plan? But it's too late now.) The chapter content should also be changed to use appropriate words carefully.
FYI, Oracle wisely give the chapter title "8 Using Parallel Execution" [1]8 Using Parallel Execution https://docs.oracle.com/en/database/oracle/oracle-database/21/vldbg/using-parallel.html#GUID-3E2AE088-2505-465E-A8B2-AC38813EA355. SQL Server isn't very clear, but it seems that it doesn't use "query" for INSERT, like in "The TABLOCK hint can enable parallel insert operations." [2]Query Processing Architecture Guide https://docs.microsoft.com/en-us/sql/relational-databases/query-processing-architecture-guide?view=sql-server-ver15 [3]INSERT (Transact-SQL) https://docs.microsoft.com/en-us/sql/t-sql/statements/insert-transact-sql?view=sql-server-ver15#best-practices
Second, I expected to see descriptions in "15. Parallel Query" that there are other (recently added) parallel operations such as parallel index build and parallel VACUUM, but I didn't find them. Also, I couldn't find information on parallelism in possible chapters such as "11. Indexes" or "25. Routine Database Maintenance Tasks". Where can users notice that they can parallelize and speed up those operations? Only in reference pages? I think it's better to have those descriptions in the Parallel Query chapter.
If nobody hasn't started making this kind of modifications, can we deter it after the feature freeze? Or should people involved in developing parallel features cooperate to revise the manual as part of their patches?
Regards
Takayuki Tsunakawa
[1]: 8 Using Parallel Execution https://docs.oracle.com/en/database/oracle/oracle-database/21/vldbg/using-parallel.html#GUID-3E2AE088-2505-465E-A8B2-AC38813EA355
8 Using Parallel Execution
https://docs.oracle.com/en/database/oracle/oracle-database/21/vldbg/using-parallel.html#GUID-3E2AE088-2505-465E-A8B2-AC38813EA355
[2]: Query Processing Architecture Guide https://docs.microsoft.com/en-us/sql/relational-databases/query-processing-architecture-guide?view=sql-server-ver15
Query Processing Architecture Guide
https://docs.microsoft.com/en-us/sql/relational-databases/query-processing-architecture-guide?view=sql-server-ver15
[3]: INSERT (Transact-SQL) https://docs.microsoft.com/en-us/sql/t-sql/statements/insert-transact-sql?view=sql-server-ver15#best-practices
INSERT (Transact-SQL)
https://docs.microsoft.com/en-us/sql/t-sql/statements/insert-transact-sql?view=sql-server-ver15#best-practices
Regards
Takayuki Tsunakawa
On Wed, Jan 6, 2021 at 12:13 PM tsunakawa.takay@fujitsu.com
<tsunakawa.takay@fujitsu.com> wrote:
Second, I expected to see descriptions in "15. Parallel Query" that there are other (recently added) parallel operations such as parallel index build and parallel VACUUM, but I didn't find them. Also, I couldn't find information on parallelism in possible chapters such as "11. Indexes" or "25. Routine Database Maintenance Tasks". Where can users notice that they can parallelize and speed up those operations? Only in reference pages? I think it's better to have those descriptions in the Parallel Query chapter.
I think it is in the respective pages of those operations. Forex. the
information about parallel vacuum can be found in the Vacuum page [1]https://www.postgresql.org/docs/devel/sql-vacuum.html.
If nobody hasn't started making this kind of modifications, can we deter it after the feature freeze? Or should people involved in developing parallel features cooperate to revise the manual as part of their patches?
I think each feature should develop the docs as part of feature
development but if we want to see some additional work like improving
overall docs for parallel execution as you are suggesting then it can
be done separately as well.
I think you have a valid point but maybe it would be better to do the
improvements you are suggesting once the parallel inserts related work
is committed.
[1]: https://www.postgresql.org/docs/devel/sql-vacuum.html
--
With Regards,
Amit Kapila.
From: Amit Kapila <amit.kapila16@gmail.com>
I think each feature should develop the docs as part of feature
development but if we want to see some additional work like improving
overall docs for parallel execution as you are suggesting then it can
be done separately as well.I think you have a valid point but maybe it would be better to do the
improvements you are suggesting once the parallel inserts related work
is committed.
OK. I think at least the words query, statement, execution, and/or operation should be used appropriately before RC (ideally, before beta). Maybe parallel copy should also be put in the chapter. Anyway, I agree that each developer focuses on their features for the moment (parallel insert select, parallel copy, parallel CTAS, etc), and then make the documentation consistent and well-organized after they've settled. (I just felt a bit uneasy to say "this patch looks good" while leaving the document consistency.)
Regards
Takayuki Tsunakawa