update outdated comments related to local_execution (#3759)

src/backend/distributed/executor/local_executor.c

@@ -60,13 +60,17 @@
  *		Note that for read-only queries, after the local execution, there is no
  *      need to kick in adaptive executor.
  *
+ * (4) Execution of multi shards local queries and
+ *     remote multi-shard queries within a transaction block
+ *
+ *      We prefer local execution when we are inside a transaction block, because not using
+ *      local execution might create some limitations for other commands in the transaction
+ *      block. To simplify things, whenever we are inside a transaction block, we prefer local
+ *      execution if possible.
+ *
  *  There are also a few limitations/trade-offs that are worth mentioning.
  *  - The local execution on multiple shards might be slow because the execution
  *  has to happen one task at a time (e.g., no parallelism).
- *  - If a transaction block/CTE starts with a multi-shard command, we do not
- *  use local query execution since local execution is sequential. Basically,
- *  we do not want to lose parallelism across local tasks by switching to local
- *  execution.
  *  - The local execution cannot be mixed with the executors other than adaptive,
  *  namely task-tracker executor.
  *  - Related with the previous item, COPY command cannot be mixed with local

src/test/regress/expected/local_shard_utility_command_execution.out

@@ -122,8 +122,8 @@ INSERT INTO ref_table VALUES(2);
 NOTICE:  executing the command locally: INSERT INTO local_commands_test_schema.ref_table_1500000 (a) VALUES (2)
 INSERT INTO dist_table VALUES(2);
 NOTICE:  executing the command locally: INSERT INTO local_commands_test_schema.dist_table_1500025 (a) VALUES (2)
--- However, SELECT would access local placements via remote connections
+-- SELECT would access local placements via local execution as that is
--- for regular distributed tables, TRUNCATE would also be executed remotely.
+-- in a transaction block even though it contains multi local shards.
 BEGIN;
   SELECT COUNT(*) FROM dist_table;
 NOTICE:  executing the command locally: SELECT count(*) AS count FROM local_commands_test_schema.dist_table_1500001 dist_table WHERE true
@@ -180,9 +180,9 @@ SELECT COUNT(*) FROM dist_table;
 -- insert some data
 INSERT INTO ref_table VALUES(4);
 NOTICE:  executing the command locally: INSERT INTO local_commands_test_schema.ref_table_1500000 (a) VALUES (4)
--- However, creating a dist. table is handled by remote connections.
+-- Creating a dist. table is handled by local execution inside a transaction block.
 -- Hence, the commands following it (INSERT & TRUNCATE) would also be
--- handled remotely.
+-- handled via local execution.
 BEGIN;
   CREATE TABLE ref_table_1(a int);
   SELECT create_reference_table('ref_table_1');
@@ -206,8 +206,8 @@ NOTICE:  executing the command locally: SELECT count(*) AS count FROM local_comm
      0
 (1 row)
 
--- However, as SELECT would access local placements via remote parallel
+-- However, as SELECT would access local placements via local execution
--- connections for regular distributed tables, below TRUNCATE would error
+-- for regular distributed tables, below TRUNCATE would error
 -- out
 BEGIN;
   SELECT COUNT(*) FROM dist_table;

src/test/regress/sql/local_shard_utility_command_execution.sql

@@ -64,8 +64,8 @@ SELECT COUNT(*) FROM dist_table;
 INSERT INTO ref_table VALUES(2);
 INSERT INTO dist_table VALUES(2);
 
--- However, SELECT would access local placements via remote connections
+-- SELECT would access local placements via local execution as that is
--- for regular distributed tables, TRUNCATE would also be executed remotely.
+-- in a transaction block even though it contains multi local shards.
 BEGIN;
   SELECT COUNT(*) FROM dist_table;
   TRUNCATE dist_table;
@@ -88,9 +88,9 @@ SELECT COUNT(*) FROM dist_table;
 -- insert some data
 INSERT INTO ref_table VALUES(4);
 
--- However, creating a dist. table is handled by remote connections.
+-- Creating a dist. table is handled by local execution inside a transaction block.
 -- Hence, the commands following it (INSERT & TRUNCATE) would also be
--- handled remotely.
+-- handled via local execution.
 BEGIN;
   CREATE TABLE ref_table_1(a int);
   SELECT create_reference_table('ref_table_1');
@@ -104,8 +104,8 @@ COMMIT;
 -- show that TRUNCATE is successfull
 SELECT COUNT(*) FROM ref_table_1;
 
--- However, as SELECT would access local placements via remote parallel
+-- However, as SELECT would access local placements via local execution
--- connections for regular distributed tables, below TRUNCATE would error
+-- for regular distributed tables, below TRUNCATE would error
 -- out
 BEGIN;
   SELECT COUNT(*) FROM dist_table;