> ## Documentation Index
> Fetch the complete documentation index at: https://docs.e6data.com/llms.txt
> Use this file to discover all available pages before exploring further.

# STRING_AGG

> Concatenates non-NULL strings with a delimiter.

<div className="e6-meta"><span className="e6-eyebrow e6-eyebrow--quiet">Aggregate · Window</span></div>

**Aliases:** [`listagg`](/query/sql/functions/aggregate/listagg)

NULL values are skipped; NULL delimiter is rejected.

## Syntax

A window function keeps each input row and adds a result for that row. `PARTITION BY` groups rows with matching values; without it, all input rows form one group.

### String agg (aggregate)

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
string_agg([DISTINCT] value [, delimiter] [, max_elements] [ORDER BY ordering_key [, ...]])
```

* A literal row limit can be the second argument when the delimiter is omitted.

### String agg window

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
string_agg(value,delimiter,max_elements) OVER ([PARTITION BY key] [ORDER BY ordering_key] [ROWS frame])
```

* Window usage requires STRING\_AGG with all three arguments.
* Use a frame that includes all rows in the group or starts at the first row (`UNBOUNDED PRECEDING`). Sliding frames that drop earlier rows are not supported.

## Arguments

### String agg

| Name | Type | Required | Description |
| - | - | - | - |
| value | STRING | Yes | Values to concatenate. |
| delimiter | STRING literal | No | Separator. Must be a constant argument. Default: ''. |
| max\_elements | INTEGER literal | No | Maximum input elements retained; -1 is unlimited. Must be a constant argument. Default: -1. |

### String agg window

| Name | Type | Required | Description |
| - | - | - | - |
| value | STRING | Yes | Values to concatenate. |
| delimiter | STRING literal | Yes | Explicit separator. Must be a constant argument. |
| max\_elements | INTEGER literal | Yes | Explicit retained-element limit; use -1 for unlimited. Must be a constant argument. |

## Returns

* Type: STRING
* NULL behavior: NULL values are skipped; NULL delimiter is rejected.
* Empty input: Returns NULL on empty/all-NULL input.

## Properties

| Property | Value |
| - | - |
| Deterministic | Partial (Specify ordering to control concatenation order.) |
| Supports DISTINCT | Partial (Removes duplicates in grouped aggregation only.) |
| Supports window usage | Partial (Use the three-argument STRING\_AGG form.) |
| Supports window frames | Partial (The frame must start at the first row in the group. See Syntax.) |
| Exact result | Yes |

## Usage notes

* max\_elements limits input elements, not output characters or bytes; -1 means unlimited.
* If omitted, the delimiter is ''. Supply a STRING literal; a delimiter expression currently uses '' instead of its value.
* LISTAGG has no row-limit argument. STRING\_AGG accepts a literal row limit as its second or third argument.
* DISTINCT removes duplicates in grouped aggregation. Do not use it to remove duplicates in a window call.

## Examples

### STRING\_AGG row limit

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
WITH sample(v) AS (VALUES ('c'), ('a'), ('b'))
SELECT string_agg(v, ',', 2 ORDER BY v NULLS LAST) AS result
FROM sample;
```

| result |
| - |
| a,b |

### STRING\_AGG over all rows in each group

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
WITH sample(id, v) AS (VALUES (1, 'a'), (2, 'b'))
SELECT id, string_agg(v, ',', -1) OVER (ORDER BY id NULLS LAST ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS result
FROM sample
ORDER BY id NULLS LAST;
```

| id | result |
| - | - |
| 1 | a,b |
| 2 | a,b |

## Limitations

* Sliding frames that drop earlier rows and RANGE frames with numeric or time offsets are not supported.
* DISTINCT WITHIN GROUP ordering must use the aggregated expression.
* LISTAGG window calls currently fail. Use STRING\_AGG(value, delimiter, max\_elements) for window usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.