begriffs open source - ai-pg/blob - full-docs/txt/when-can-parallel-query-be-used.txt

   1
   2 15.2. When Can Parallel Query Be Used? #
   3
   4    There are several settings that can cause the query planner not to
   5    generate a parallel query plan under any circumstances. In order for
   6    any parallel query plans whatsoever to be generated, the following
   7    settings must be configured as indicated.
   8      * max_parallel_workers_per_gather must be set to a value that is
   9        greater than zero. This is a special case of the more general
  10        principle that no more workers should be used than the number
  11        configured via max_parallel_workers_per_gather.
  12
  13    In addition, the system must not be running in single-user mode. Since
  14    the entire database system is running as a single process in this
  15    situation, no background workers will be available.
  16
  17    Even when it is in general possible for parallel query plans to be
  18    generated, the planner will not generate them for a given query if any
  19    of the following are true:
  20      * The query writes any data or locks any database rows. If a query
  21        contains a data-modifying operation either at the top level or
  22        within a CTE, no parallel plans for that query will be generated.
  23        As an exception, the following commands, which create a new table
  24        and populate it, can use a parallel plan for the underlying SELECT
  25        part of the query:
  26           + CREATE TABLE ... AS
  27           + SELECT INTO
  28           + CREATE MATERIALIZED VIEW
  29           + REFRESH MATERIALIZED VIEW
  30      * The query might be suspended during execution. In any situation in
  31        which the system thinks that partial or incremental execution might
  32        occur, no parallel plan is generated. For example, a cursor created
  33        using DECLARE CURSOR will never use a parallel plan. Similarly, a
  34        PL/pgSQL loop of the form FOR x IN query LOOP .. END LOOP will
  35        never use a parallel plan, because the parallel query system is
  36        unable to verify that the code in the loop is safe to execute while
  37        parallel query is active.
  38      * The query uses any function marked PARALLEL UNSAFE. Most
  39        system-defined functions are PARALLEL SAFE, but user-defined
  40        functions are marked PARALLEL UNSAFE by default. See the discussion
  41        of Section 15.4.
  42      * The query is running inside of another query that is already
  43        parallel. For example, if a function called by a parallel query
  44        issues an SQL query itself, that query will never use a parallel
  45        plan. This is a limitation of the current implementation, but it
  46        may not be desirable to remove this limitation, since it could
  47        result in a single query using a very large number of processes.
  48
  49    Even when a parallel query plan is generated for a particular query,
  50    there are several circumstances under which it will be impossible to
  51    execute that plan in parallel at execution time. If this occurs, the
  52    leader will execute the portion of the plan below the Gather node
  53    entirely by itself, almost as if the Gather node were not present. This
  54    will happen if any of the following conditions are met:
  55      * No background workers can be obtained because of the limitation
  56        that the total number of background workers cannot exceed
  57        max_worker_processes.
  58      * No background workers can be obtained because of the limitation
  59        that the total number of background workers launched for purposes
  60        of parallel query cannot exceed max_parallel_workers.
  61      * The client sends an Execute message with a non-zero fetch count.
  62        See the discussion of the extended query protocol. Since libpq
  63        currently provides no way to send such a message, this can only
  64        occur when using a client that does not rely on libpq. If this is a
  65        frequent occurrence, it may be a good idea to set
  66        max_parallel_workers_per_gather to zero in sessions where it is
  67        likely, so as to avoid generating query plans that may be
  68        suboptimal when run serially.