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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>15.2. When Can Parallel Query Be Used?</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works" /><link rel="next" href="parallel-plans.html" title="15.3. Parallel Plans" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">15.2. When Can Parallel Query Be Used?</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><th width="60%" align="center">Chapter 15. Parallel Query</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="parallel-plans.html" title="15.3. Parallel Plans">Next</a></td></tr></table><hr /></div><div class="sect1" id="WHEN-CAN-PARALLEL-QUERY-BE-USED"><div class="titlepage"><div><div><h2 class="title" style="clear: both">15.2. When Can Parallel Query Be Used? <a href="#WHEN-CAN-PARALLEL-QUERY-BE-USED" class="id_link">#</a></h2></div></div></div><p>
   3     There are several settings that can cause the query planner not to
   4     generate a parallel query plan under any circumstances.  In order for
   5     any parallel query plans whatsoever to be generated, the following
   6     settings must be configured as indicated.
   7   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
   8         <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> must be set to a
   9         value that is greater than zero. This is a special case of the more
  10         general principle that no more workers should be used than the number
  11         configured via <code class="varname">max_parallel_workers_per_gather</code>.
  12       </p></li></ul></div><p>
  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 situation,
  15     no background workers will be available.
  16   </p><p>
  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
  19     if any of the following are true:
  20   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  21         The query writes any data or locks any database rows. If a query
  22         contains a data-modifying operation either at the top level or within
  23         a CTE, no parallel plans for that query will be generated.  As an
  24         exception, the following commands, which create a new table and populate
  25         it, can use a parallel plan for the underlying <code class="literal">SELECT</code>
  26         part of the query:
  27
  28         </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><code class="command">CREATE TABLE ... AS</code></p></li><li class="listitem"><p><code class="command">SELECT INTO</code></p></li><li class="listitem"><p><code class="command">CREATE MATERIALIZED VIEW</code></p></li><li class="listitem"><p><code class="command">REFRESH MATERIALIZED VIEW</code></p></li></ul></div><p>
  29       </p></li><li class="listitem"><p>
  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 <a class="link" href="sql-declare.html" title="DECLARE">DECLARE CURSOR</a> will never use
  34         a parallel plan. Similarly, a PL/pgSQL loop of the form
  35         <code class="literal">FOR x IN query LOOP .. END LOOP</code> will never use a
  36         parallel plan, because the parallel query system is unable to verify
  37         that the code in the loop is safe to execute while parallel query is
  38         active.
  39       </p></li><li class="listitem"><p>
  40         The query uses any function marked <code class="literal">PARALLEL UNSAFE</code>.
  41         Most system-defined functions are <code class="literal">PARALLEL SAFE</code>,
  42         but user-defined functions are marked <code class="literal">PARALLEL
  43         UNSAFE</code> by default. See the discussion of
  44         <a class="xref" href="parallel-safety.html" title="15.4. Parallel Safety">Section 15.4</a>.
  45       </p></li><li class="listitem"><p>
  46         The query is running inside of another query that is already parallel.
  47         For example, if a function called by a parallel query issues an SQL
  48         query itself, that query will never use a parallel plan. This is a
  49         limitation of the current implementation, but it may not be desirable
  50         to remove this limitation, since it could result in a single query
  51         using a very large number of processes.
  52       </p></li></ul></div><p>
  53     Even when a parallel query plan is generated for a particular query, there
  54     are several circumstances under which it will be impossible to execute
  55     that plan in parallel at execution time.  If this occurs, the leader
  56     will execute the portion of the plan below the <code class="literal">Gather</code>
  57     node entirely by itself, almost as if the <code class="literal">Gather</code> node were
  58     not present.  This will happen if any of the following conditions are met:
  59   </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  60         No background workers can be obtained because of the limitation that
  61         the total number of background workers cannot exceed
  62         <a class="xref" href="runtime-config-resource.html#GUC-MAX-WORKER-PROCESSES">max_worker_processes</a>.
  63       </p></li><li class="listitem"><p>
  64         No background workers can be obtained because of the limitation that
  65         the total number of background workers launched for purposes of
  66         parallel query cannot exceed <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS">max_parallel_workers</a>.
  67       </p></li><li class="listitem"><p>
  68         The client sends an Execute message with a non-zero fetch count.
  69         See the discussion of the
  70         <a class="link" href="protocol-flow.html#PROTOCOL-FLOW-EXT-QUERY" title="54.2.3. Extended Query">extended query protocol</a>.
  71         Since <a class="link" href="libpq.html" title="Chapter 32. libpq — C Library">libpq</a> currently provides no way to
  72         send such a message, this can only occur when using a client that
  73         does not rely on libpq.  If this is a frequent
  74         occurrence, it may be a good idea to set
  75         <a class="xref" href="runtime-config-resource.html#GUC-MAX-PARALLEL-WORKERS-PER-GATHER">max_parallel_workers_per_gather</a> to zero in
  76         sessions where it is likely, so as to avoid generating query plans
  77         that may be suboptimal when run serially.
  78       </p></li></ul></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="how-parallel-query-works.html" title="15.1. How Parallel Query Works">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="parallel-query.html" title="Chapter 15. Parallel Query">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel-plans.html" title="15.3. Parallel Plans">Next</a></td></tr><tr><td width="40%" align="left" valign="top">15.1. How Parallel Query Works </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> 15.3. Parallel Plans</td></tr></table></div></body></html>