{"Entry":{"collection":"guc","key":"join_collapse_limit","name":"join_collapse_limit","aliases":[],"metadata":{"baseline":true,"boot_human":"Not specified","boot_val":null,"category":"Query Tuning / Other Planner Options","category_zh":"","changed_in":[],"changes":[{"documentation_changed":true,"fields":{},"from":"7.4","status":"changed","to":"8.0"},{"documentation_changed":true,"fields":{},"from":"8.1","status":"changed","to":"8.2"},{"documentation_changed":true,"fields":{},"from":"8.2","status":"changed","to":"8.3"},{"documentation_changed":true,"fields":{},"from":"8.3","status":"changed","to":"8.4"},{"documentation_changed":true,"fields":{},"from":"8.4","status":"changed","to":"9.0"},{"documentation_changed":true,"fields":{},"from":"9.0","status":"changed","to":"9.1"},{"documentation_changed":true,"fields":{},"from":"9.5","status":"changed","to":"9.6"},{"documentation_changed":true,"fields":{},"from":"13","status":"changed","to":"14"},{"documentation_changed":true,"fields":{},"from":"16","status":"changed","to":"17"}],"content_hash":"ce6ba8a89be7da5d9db6942e5f911b28270fa4079f240168982ac2700648c8ab","context":"","default_changed_in":[],"default_history":[{"from":"9.0","to":"19","value":"8"}],"editorial":{"advice":{"olap":"Analytical SQL can make join_collapse_limit more visible because joins, cursors, or recursion are larger. Benchmark the full statement family and inspect estimates rather than copying a single successful value.","oltp":"Keep join_collapse_limit at its upstream default unless representative plans show a repeatable, workload-wide problem. Test a local override first and include planning latency as well as execution latency.","small":"On a small host, avoid increasing planning search or memory pressure through join_collapse_limit without a measured benefit. Prefer query-local structure or a scoped role setting over a cluster-wide override."},"mechanism":["join_collapse_limit controls when explicit JOIN constructs, except FULL JOIN, are flattened into a reorderable FROM list. A value of 1 preserves the written explicit join order.","Flattening enlarges the set of join orders the planner can explore, improving opportunities at the cost of planning CPU and memory. Outer-join semantics still constrain legal reorderings.","The exposed item count interacts with from_collapse_limit and geqo_threshold. Using 1 as a manual join-order tool transfers responsibility to SQL authors and is not a general plan-stability guarantee. Its user context permits session- or transaction-local changes; newly performed or newly planned work sees the value."],"pitfalls":["Treating join_collapse_limit as an executor resource limit rather than a planning assumption or policy.","Testing only one parameter set or one data distribution.","Expecting an already cached plan to be rewritten automatically.","Using a global override to hide stale statistics or fragile SQL structure."],"references":[{"title":"PostgreSQL 19 Beta 4: join_collapse_limit","url":"https://www.postgresql.org/docs/19/runtime-config-query.html#GUC-JOIN-COLLAPSE-LIMIT"},{"title":"PostgreSQL 19 release notes","url":"https://www.postgresql.org/docs/19/release-19.html"}],"related":["from_collapse_limit","geqo_threshold","geqo","enable_hashjoin","enable_nestloop"],"summary":"join_collapse_limit — Sets the FROM-list size beyond which JOIN constructs are not flattened. Observed in PG9.0–19 Beta 4; its last measured boot default is 8 in PG19 Beta 4, with user context. This is a beta-snapshot fact and can change before PostgreSQL 19 GA."},"enumvals":[],"first_version":"7.4","group":"Query Tuning","group_slug":"query","imported_at":"2026-09-27T17:57:31.44864+08:00","intro_commit":{},"key":"join_collapse_limit","last_version":"20","max_val":"","min_val":"","name":"join_collapse_limit","position":200,"present_in":["7.4","8.0","8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6","10","11","12","13","14","15","16","17","18","19","20"],"short_desc":"The planner will rewrite explicit JOIN constructs (except FULL JOINs) into lists of FROM items whenever a list of no more than this many items would result.","short_desc_zh":"","source_rev":"english-manuals:71677d3f8397c4f29a9ba18fe6c9e50ff0f6b1ba0cc646db3583529b25b83e3f","unit":"","vartype":"integer"}},"Definition":{"Collection":"guc","Key":"join_collapse_limit","SourceDatabase":"center","Version":"18","SourceTable":"guc","SourceKey":"join_collapse_limit","SourceRevision":"english-manuals:71677d3f8397c4f29a9ba18fe6c9e50ff0f6b1ba0cc646db3583529b25b83e3f","Facts":{"boot_val":"8","category":"Query Tuning / Other Planner Options","context":"user","description":"The planner will rewrite explicit JOIN constructs (except FULL JOINs) into lists of FROM items whenever a list of no more than this many items would result. Smaller values reduce planning time but might yield inferior query plans. By default, this variable is set the same as from_collapse_limit, which is appropriate for most uses. Setting it to 1 prevents any reordering of explicit JOINs. Thus, the explicit join order specified in the query will be the actual order in which the relations are joined. Because the query planner does not always choose the optimal join order, advanced users can elect to temporarily set this variable to 1, and then specify the join order they desire explicitly. For more information see Section 14.3. Setting this value to geqo_threshold or more may trigger use of the GEQO planner, resulting in non-optimal plans. See Section 19.7.3.","doc":{"anchor":"GUC-JOIN-COLLAPSE-LIMIT","file":"runtime-config-query.html","lang":"en","sha256":"33456ca7ef52bf28e93e34b932a411db7a1b95800179add2cf867dc6ec9144bc","slug":"18"},"documented":true,"enumvals":null,"extra_desc":"The planner will flatten explicit JOIN constructs into lists of FROM items whenever a list of no more than this many items would result.","lang":"en","max_val":"2147483647","metadata_version":"18","min_val":"1","name":"join_collapse_limit","short_desc":"Sets the FROM-list size beyond which JOIN constructs are not flattened.","source":"pg-settings-source-snapshot","unit":null,"vartype":"integer"},"ManualEvidence":{"doc":{"anchor":"GUC-JOIN-COLLAPSE-LIMIT","file":"runtime-config-query.html","lang":"en","sha256":"33456ca7ef52bf28e93e34b932a411db7a1b95800179add2cf867dc6ec9144bc","slug":"18"}},"MeasuredEvidence":{"metadata_version":"18"}},"Text":{"Collection":"guc","Key":"join_collapse_limit","SourceDatabase":"pgweb","Version":"18","Locale":"zh-Hans","Title":"join_collapse_limit","Summary":"","BodyHTML":"\u003cp\u003e如果得出的列表中不超过这么多项，那么规划器将把显式\u003ccode\u003eJOIN\u003c/code\u003e（除了\u003ccode\u003eFULL JOIN\u003c/code\u003e）结构重写到 \u003ccode\u003eFROM\u003c/code\u003e项列表中。较小的值可减少规划时间，但是可能会生成差些的查询计划。\u003c/p\u003e\u003cp\u003e默认情况下，这个变量被设置成和\u003ccode\u003efrom_collapse_limit\u003c/code\u003e相同，这样适合大多数使用。把它设置为 1 可避免任何显式\u003ccode\u003eJOIN\u003c/code\u003e的重排序。因此查询中指定的显式连接顺序就是关系被连接的实际顺序。因为查询规划器并不是总能选取最优的连接顺序，高级用户可以选择暂时把这个变量设置为 1，然后显式地指定他们想要的连接顺序。更多信息请见\u003ca href=\"/docs/18/explicit-joins.html\" rel=\"nofollow\"\u003e第 14.3 节\u003c/a\u003e。\u003c/p\u003e\u003cp\u003e将这个值设置为\u003ca href=\"/docs/18/runtime-config-query.html#GUC-GEQO-THRESHOLD\" rel=\"nofollow\"\u003egeqo_threshold\u003c/a\u003e或更大，可能触发使用 GEQO 规划器，从而产生非最优计划。见\u003ca href=\"/docs/18/runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO\" rel=\"nofollow\"\u003e第 19.7.3 节\u003c/a\u003e。\u003c/p\u003e","SourceRevision":"2026-09-11@29c86d9","ContentHash":"8398598c471145160a6aa7386016a07d60767a793b173fe479e7405150ba0318","Payload":{"carried_from":"","carry_reason":"","doc_html":"\u003cp\u003e如果得出的列表中不超过这么多项，那么规划器将把显式\u003ccode class=\"literal\"\u003eJOIN\u003c/code\u003e（除了\u003ccode class=\"literal\"\u003eFULL JOIN\u003c/code\u003e）结构重写到 \u003ccode class=\"literal\"\u003eFROM\u003c/code\u003e项列表中。较小的值可减少规划时间，但是可能会生成差些的查询计划。\u003c/p\u003e\u003cp\u003e默认情况下，这个变量被设置成和\u003ccode class=\"varname\"\u003efrom_collapse_limit\u003c/code\u003e相同，这样适合大多数使用。把它设置为 1 可避免任何显式\u003ccode class=\"literal\"\u003eJOIN\u003c/code\u003e的重排序。因此查询中指定的显式连接顺序就是关系被连接的实际顺序。因为查询规划器并不是总能选取最优的连接顺序，高级用户可以选择暂时把这个变量设置为 1，然后显式地指定他们想要的连接顺序。更多信息请见\u003ca href=\"/docs/18/explicit-joins.html\" title=\"14.3. 用显式JOIN子句控制规划器\"\u003e第 14.3 节\u003c/a\u003e。\u003c/p\u003e\u003cp\u003e将这个值设置为\u003ca href=\"/docs/18/runtime-config-query.html#GUC-GEQO-THRESHOLD\"\u003egeqo_threshold\u003c/a\u003e或更大，可能触发使用 GEQO 规划器，从而产生非最优计划。见\u003ca href=\"/docs/18/runtime-config-query.html#RUNTIME-CONFIG-QUERY-GEQO\" title=\"19.7.3. 遗传查询优化器\"\u003e第 19.7.3 节\u003c/a\u003e。\u003c/p\u003e","doc_same_as":""}},"RequestedLocale":"zh-Hans","Fallback":false,"Versions":["10","11","12","13","14","15","16","17","18","19","20","7.4","8.0","8.1","8.2","8.3","8.4","9.0","9.1","9.2","9.3","9.4","9.5","9.6"],"Locales":["en","zh-Hans"],"Signatures":null,"Spellings":null,"SQLState":null,"Evidence":null}