docs/topics/impala_group_concat.xml

<?xml version="1.0" encoding="UTF-8"?>
<!--
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE concept PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept rev="1.2" id="group_concat">

  <title>GROUP_CONCAT Function</title>
  <titlealts audience="PDF"><navtitle>GROUP_CONCAT</navtitle></titlealts>
  <prolog>
    <metadata>
      <data name="Category" value="Impala"/>
      <data name="Category" value="SQL"/>
      <data name="Category" value="Impala Functions"/>
      <data name="Category" value="Aggregate Functions"/>
      <data name="Category" value="Querying"/>
      <data name="Category" value="Developers"/>
      <data name="Category" value="Data Analysts"/>
    </metadata>
  </prolog>

  <conbody>

    <p>
      <indexterm audience="Cloudera">group_concat() function</indexterm>
      An aggregate function that returns a single string representing the argument value concatenated together for
      each row of the result set. If the optional separator string is specified, the separator is added between
      each pair of concatenated values. The default separator is a comma followed by a space.
    </p>

    <p conref="../shared/impala_common.xml#common/syntax_blurb"/>

<!-- Might allow DISTINCT at some point. Check: does it allow ALL now? -->

<codeblock>GROUP_CONCAT([ALL] <varname>expression</varname> [, <varname>separator</varname>])</codeblock>

    <p conref="../shared/impala_common.xml#common/concat_blurb"/>

    <p>
      By default, returns a single string covering the whole result set. To include other columns or values in the
      result set, or to produce multiple concatenated strings for subsets of rows, include a <codeph>GROUP
      BY</codeph> clause in the query.
    </p>

    <p>
      <b>Return type:</b> <codeph>STRING</codeph>
    </p>

    <p conref="../shared/impala_common.xml#common/restrictions_blurb"/>

    <p>
      You cannot apply the <codeph>DISTINCT</codeph> operator to the argument of this function.
    </p>

    <p conref="../shared/impala_common.xml#common/analytic_not_allowed_caveat"/>

    <p>
      Currently, Impala returns an error if the result value grows larger than 1 GiB.
    </p>

    <p conref="../shared/impala_common.xml#common/example_blurb"/>

    <p>
      The following examples illustrate various aspects of the <codeph>GROUP_CONCAT()</codeph> function.
    </p>

    <p>
      You can call the function directly on a <codeph>STRING</codeph> column. To use it with a numeric column, cast
      the value to <codeph>STRING</codeph>.
    </p>

<codeblock>[localhost:21000] &gt; create table t1 (x int, s string);
[localhost:21000] &gt; insert into t1 values (1, "one"), (3, "three"), (2, "two"), (1, "one");
[localhost:21000] &gt; select group_concat(s) from t1;
+----------------------+
| group_concat(s)      |
+----------------------+
| one, three, two, one |
+----------------------+
[localhost:21000] &gt; select group_concat(cast(x as string)) from t1;
+---------------------------------+
| group_concat(cast(x as string)) |
+---------------------------------+
| 1, 3, 2, 1                      |
+---------------------------------+
</codeblock>

    <p>
      The optional separator lets you format the result in flexible ways. The separator can be an arbitrary string
      expression, not just a single character.
    </p>

<codeblock>[localhost:21000] &gt; select group_concat(s,"|") from t1;
+----------------------+
| group_concat(s, '|') |
+----------------------+
| one|three|two|one    |
+----------------------+
[localhost:21000] &gt; select group_concat(s,'---') from t1;
+-------------------------+
| group_concat(s, '---')  |
+-------------------------+
| one---three---two---one |
+-------------------------+
</codeblock>

    <p>
      The default separator is a comma followed by a space. To get a comma-delimited result without extra spaces,
      specify a delimiter character that is only a comma.
    </p>

<codeblock>[localhost:21000] &gt; select group_concat(s,',') from t1;
+----------------------+
| group_concat(s, ',') |
+----------------------+
| one,three,two,one    |
+----------------------+
</codeblock>

    <p>
      Including a <codeph>GROUP BY</codeph> clause lets you produce a different concatenated result for each group
      in the result set. In this example, the only <codeph>X</codeph> value that occurs more than once is
      <codeph>1</codeph>, so that is the only row in the result set where <codeph>GROUP_CONCAT()</codeph> returns a
      delimited value. For groups containing a single value, <codeph>GROUP_CONCAT()</codeph> returns the original
      value of its <codeph>STRING</codeph> argument.
    </p>

<codeblock>[localhost:21000] &gt; select x, group_concat(s) from t1 group by x;
+---+-----------------+
| x | group_concat(s) |
+---+-----------------+
| 2 | two             |
| 3 | three           |
| 1 | one, one        |
+---+-----------------+
</codeblock>
  </conbody>
</concept>