{
    "content": [
        {
            "type": "text",
            "text": "# CLUSTER (man)\n\n## NAME\n\nCLUSTER - cluster a table according to an index\n\n## SYNOPSIS\n\nCLUSTER [VERBOSE] tablename [ USING indexname ]\nCLUSTER ( option [, ...] ) tablename [ USING indexname ]\nCLUSTER [VERBOSE]\nwhere option can be one of:\nVERBOSE [ boolean ]\n\n## DESCRIPTION\n\nCLUSTER instructs PostgreSQL to cluster the table specified by tablename based on the index\nspecified by indexname. The index must already have been defined on tablename.\n\n## TLDR\n\n> Find clusters in a graph and augment the graph with this information.\n\n- Generate clusters that optimize modularity and print the result to `stdout`:\n  `cluster {{input.gv}}`\n- Specify a target number of [C]lusters (approximate) to generate (0 by default, meaning a number that approximately optimizes the modularity):\n  `cluster -C {{5}} {{input.gv}}`\n- Use a different [c]lustering method (0: modularity clustering, 1: modularity quality):\n  `cluster -c {{0|1}} {{input.gv}}`\n- Save the [o]utput to a file:\n  `cluster -o {{output.gv}} {{input.gv}}`\n- Enable [v]erbose mode:\n  `cluster -v {{input.gv}}`\n\n*Source: tldr-pages*\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **PARAMETERS**\n- **NOTES**\n- **EXAMPLES**\n- **COMPATIBILITY**\n- **SEE ALSO**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "CLUSTER",
        "section": "",
        "mode": "man",
        "summary": "CLUSTER - cluster a table according to an index",
        "synopsis": "CLUSTER [VERBOSE] tablename [ USING indexname ]\nCLUSTER ( option [, ...] ) tablename [ USING indexname ]\nCLUSTER [VERBOSE]\nwhere option can be one of:\nVERBOSE [ boolean ]",
        "tldr_summary": "Find clusters in a graph and augment the graph with this information.",
        "tldr_examples": [
            {
                "description": "Generate clusters that optimize modularity and print the result to `stdout`",
                "command": "cluster {{input.gv}}"
            },
            {
                "description": "Specify a target number of [C]lusters (approximate) to generate (0 by default, meaning a number that approximately optimizes the modularity)",
                "command": "cluster -C {{5}} {{input.gv}}"
            },
            {
                "description": "Use a different [c]lustering method (0: modularity clustering, 1: modularity quality)",
                "command": "cluster -c {{0|1}} {{input.gv}}"
            },
            {
                "description": "Save the [o]utput to a file",
                "command": "cluster -o {{output.gv}} {{input.gv}}"
            },
            {
                "description": "Enable [v]erbose mode",
                "command": "cluster -v {{input.gv}}"
            }
        ],
        "tldr_source": "official",
        "flags": [],
        "examples": [
            "Cluster the table employees on the basis of its index employeesind:",
            "CLUSTER employees USING employeesind;",
            "Cluster the employees table using the same index that was used before:",
            "CLUSTER employees;",
            "Cluster all tables in the database that have previously been clustered:",
            "CLUSTER;"
        ],
        "see_also": [
            {
                "name": "clusterdb",
                "section": "1",
                "url": "https://www.chedong.com/phpMan.php/man/clusterdb/1/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 24,
                "subsections": []
            },
            {
                "name": "PARAMETERS",
                "lines": 14,
                "subsections": []
            },
            {
                "name": "NOTES",
                "lines": 37,
                "subsections": []
            },
            {
                "name": "EXAMPLES",
                "lines": 12,
                "subsections": []
            },
            {
                "name": "COMPATIBILITY",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 5,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "CLUSTER - cluster a table according to an index\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "CLUSTER [VERBOSE] tablename [ USING indexname ]\nCLUSTER ( option [, ...] ) tablename [ USING indexname ]\nCLUSTER [VERBOSE]\n\nwhere option can be one of:\n\nVERBOSE [ boolean ]\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "CLUSTER instructs PostgreSQL to cluster the table specified by tablename based on the index\nspecified by indexname. The index must already have been defined on tablename.\n\nWhen a table is clustered, it is physically reordered based on the index information.\nClustering is a one-time operation: when the table is subsequently updated, the changes are\nnot clustered. That is, no attempt is made to store new or updated rows according to their\nindex order. (If one wishes, one can periodically recluster by issuing the command again.\nAlso, setting the table's fillfactor storage parameter to less than 100% can aid in\npreserving cluster ordering during updates, since updated rows are kept on the same page if\nenough space is available there.)\n\nWhen a table is clustered, PostgreSQL remembers which index it was clustered by. The form\nCLUSTER tablename reclusters the table using the same index as before. You can also use the\nCLUSTER or SET WITHOUT CLUSTER forms of ALTER TABLE to set the index to be used for future\ncluster operations, or to clear any previous setting.\n\nCLUSTER without any parameter reclusters all the previously-clustered tables in the current\ndatabase that the calling user owns, or all such tables if called by a superuser. This form\nof CLUSTER cannot be executed inside a transaction block.\n\nWhen a table is being clustered, an ACCESS EXCLUSIVE lock is acquired on it. This prevents\nany other database operations (both reads and writes) from operating on the table until the\nCLUSTER is finished.\n",
                "subsections": []
            },
            "PARAMETERS": {
                "content": "tablename\nThe name (possibly schema-qualified) of a table.\n\nindexname\nThe name of an index.\n\nVERBOSE\nPrints a progress report as each table is clustered.\n\nboolean\nSpecifies whether the selected option should be turned on or off. You can write TRUE, ON,\nor 1 to enable the option, and FALSE, OFF, or 0 to disable it. The boolean value can also\nbe omitted, in which case TRUE is assumed.\n",
                "subsections": []
            },
            "NOTES": {
                "content": "In cases where you are accessing single rows randomly within a table, the actual order of the\ndata in the table is unimportant. However, if you tend to access some data more than others,\nand there is an index that groups them together, you will benefit from using CLUSTER. If you\nare requesting a range of indexed values from a table, or a single indexed value that has\nmultiple rows that match, CLUSTER will help because once the index identifies the table page\nfor the first row that matches, all other rows that match are probably already on the same\ntable page, and so you save disk accesses and speed up the query.\n\nCLUSTER can re-sort the table using either an index scan on the specified index, or (if the\nindex is a b-tree) a sequential scan followed by sorting. It will attempt to choose the\nmethod that will be faster, based on planner cost parameters and available statistical\ninformation.\n\nWhen an index scan is used, a temporary copy of the table is created that contains the table\ndata in the index order. Temporary copies of each index on the table are created as well.\nTherefore, you need free space on disk at least equal to the sum of the table size and the\nindex sizes.\n\nWhen a sequential scan and sort is used, a temporary sort file is also created, so that the\npeak temporary space requirement is as much as double the table size, plus the index sizes.\nThis method is often faster than the index scan method, but if the disk space requirement is\nintolerable, you can disable this choice by temporarily setting enablesort to off.\n\nIt is advisable to set maintenanceworkmem to a reasonably large value (but not more than\nthe amount of RAM you can dedicate to the CLUSTER operation) before clustering.\n\nBecause the planner records statistics about the ordering of tables, it is advisable to run\nANALYZE on the newly clustered table. Otherwise, the planner might make poor choices of query\nplans.\n\nBecause CLUSTER remembers which indexes are clustered, one can cluster the tables one wants\nclustered manually the first time, then set up a periodic maintenance script that executes\nCLUSTER without any parameters, so that the desired tables are periodically reclustered.\n\nEach backend running CLUSTER will report its progress in the pgstatprogresscluster view.\nSee Section 28.4.4 for details.\n",
                "subsections": []
            },
            "EXAMPLES": {
                "content": "Cluster the table employees on the basis of its index employeesind:\n\nCLUSTER employees USING employeesind;\n\nCluster the employees table using the same index that was used before:\n\nCLUSTER employees;\n\nCluster all tables in the database that have previously been clustered:\n\nCLUSTER;\n",
                "subsections": []
            },
            "COMPATIBILITY": {
                "content": "There is no CLUSTER statement in the SQL standard.\n\nThe syntax\n\nCLUSTER indexname ON tablename\n\nis also supported for compatibility with pre-8.3 PostgreSQL versions.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "clusterdb(1), Section 28.4.4\n\n\n\nPostgreSQL 14.23                                2026                                      CLUSTER(7)",
                "subsections": []
            }
        }
    }
}