0001 ---
0002 layout: global
0003 title: CLUSTER BY Clause
0004 displayTitle: CLUSTER BY Clause
0005 license: |
0006 Licensed to the Apache Software Foundation (ASF) under one or more
0007 contributor license agreements. See the NOTICE file distributed with
0008 this work for additional information regarding copyright ownership.
0009 The ASF licenses this file to You under the Apache License, Version 2.0
0010 (the "License"); you may not use this file except in compliance with
0011 the License. You may obtain a copy of the License at
0012
0013 http://www.apache.org/licenses/LICENSE-2.0
0014
0015 Unless required by applicable law or agreed to in writing, software
0016 distributed under the License is distributed on an "AS IS" BASIS,
0017 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
0018 See the License for the specific language governing permissions and
0019 limitations under the License.
0020 ---
0021
0022 ### Description
0023
0024 The `CLUSTER BY` clause is used to first repartition the data based
0025 on the input expressions and then sort the data within each partition. This is
0026 semantically equivalent to performing a
0027 [DISTRIBUTE BY](sql-ref-syntax-qry-select-distribute-by.html) followed by a
0028 [SORT BY](sql-ref-syntax-qry-select-sortby.html). This clause only ensures that the
0029 resultant rows are sorted within each partition and does not guarantee a total order of output.
0030
0031 ### Syntax
0032
0033 ```sql
0034 CLUSTER BY { expression [ , ... ] }
0035 ```
0036
0037 ### Parameters
0038
0039 * **expression**
0040
0041 Specifies combination of one or more values, operators and SQL functions that results in a value.
0042
0043 ### Examples
0044
0045 ```sql
0046 CREATE TABLE person (name STRING, age INT);
0047 INSERT INTO person VALUES
0048 ('Zen Hui', 25),
0049 ('Anil B', 18),
0050 ('Shone S', 16),
0051 ('Mike A', 25),
0052 ('John A', 18),
0053 ('Jack N', 16);
0054
0055 -- Reduce the number of shuffle partitions to 2 to illustrate the behavior of `CLUSTER BY`.
0056 -- It's easier to see the clustering and sorting behavior with less number of partitions.
0057 SET spark.sql.shuffle.partitions = 2;
0058
0059 -- Select the rows with no ordering. Please note that without any sort directive, the results
0060 -- of the query is not deterministic. It's included here to show the difference in behavior
0061 -- of a query when `CLUSTER BY` is not used vs when it's used. The query below produces rows
0062 -- where age column is not sorted.
0063 SELECT age, name FROM person;
0064 +---+-------+
0065 |age| name|
0066 +---+-------+
0067 | 16|Shone S|
0068 | 25|Zen Hui|
0069 | 16| Jack N|
0070 | 25| Mike A|
0071 | 18| John A|
0072 | 18| Anil B|
0073 +---+-------+
0074
0075 -- Produces rows clustered by age. Persons with same age are clustered together.
0076 -- In the query below, persons with age 18 and 25 are in first partition and the
0077 -- persons with age 16 are in the second partition. The rows are sorted based
0078 -- on age within each partition.
0079 SELECT age, name FROM person CLUSTER BY age;
0080 +---+-------+
0081 |age| name|
0082 +---+-------+
0083 | 18| John A|
0084 | 18| Anil B|
0085 | 25|Zen Hui|
0086 | 25| Mike A|
0087 | 16|Shone S|
0088 | 16| Jack N|
0089 +---+-------+
0090 ```
0091
0092 ### Related Statements
0093
0094 * [SELECT Main](sql-ref-syntax-qry-select.html)
0095 * [WHERE Clause](sql-ref-syntax-qry-select-where.html)
0096 * [GROUP BY Clause](sql-ref-syntax-qry-select-groupby.html)
0097 * [HAVING Clause](sql-ref-syntax-qry-select-having.html)
0098 * [ORDER BY Clause](sql-ref-syntax-qry-select-orderby.html)
0099 * [SORT BY Clause](sql-ref-syntax-qry-select-sortby.html)
0100 * [DISTRIBUTE BY Clause](sql-ref-syntax-qry-select-distribute-by.html)
0101 * [LIMIT Clause](sql-ref-syntax-qry-select-limit.html)
