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

> Formata as linhas de cada grupo usando um formato de saída e retorna os dados formatados como uma string.

# groupFormat

Formata as linhas de cada grupo usando um formato de saída e retorna os dados formatados como uma string. É semelhante a `formatRow`, mas funciona com o grupo inteiro e pode usar formatos baseados em blocos.

<Warning>
  Todas as linhas de cada grupo são acumuladas em memória antes de a string formatada ser produzida. Em grupos com um número muito grande de linhas, isso pode consumir uma quantidade significativa de memória. Considere usar `LIMIT` em subconsultas ou dividir grupos grandes para manter o uso de memória sob controle.
</Warning>

<div id="syntax">
  ## Sintaxe
</div>

```sql theme={null}
groupFormat(format)(x, y, ...)
```

<div id="parameters">
  ## Parâmetros
</div>

* `format` — Nome do formato de saída, por exemplo `JSONEachRow`, `CSV`, `TabSeparated`.

<div id="arguments">
  ## Argumentos
</div>

* `x, y, ...` — Expressões a serem formatadas como linhas. Pelo menos um argumento é obrigatório.

<div id="returned-value">
  ## Valor retornado
</div>

* Uma [String](/docs/pt-BR/reference/data-types/string) contendo a saída formatada do grupo.

<Note>
  Os nomes das colunas na saída formatada são gerados como `c1`, `c2`, ... na ordem dos argumentos.

  A ordem exata das linhas formatadas não é garantida.

  As configurações de formato da consulta (por exemplo, `format_csv_delimiter` ou `output_format_json_quote_64bit_integers`) são capturadas quando a função de agregação é inicializada e usadas para gerar a saída. A configuração `output_format_write_statistics` é sempre desabilitada, portanto a string formatada nunca contém uma seção de estatísticas.
</Note>

<div id="null-handling">
  ## Tratamento de NULL
</div>

Assim como `groupArray` e `groupConcat`, `groupFormat` ignora uma linha quando qualquer um dos seus argumentos é `NULL`; essas linhas não aparecem na saída formatada. Quando um argumento é do tipo `Nullable`, o tipo de resultado é `Nullable(String)`, e um grupo em que todas as linhas são ignoradas — assim como um argumento `NULL` literal sem tipo do tipo `Nullable(Nothing)` — retorna `NULL` por meio do combinador genérico `Null`.

```sql theme={null}
SELECT groupFormat('JSONEachRow')(if(number = 0, NULL, number))
FROM numbers(3);
-- {"c1":1}
-- {"c1":2}
```

<div id="examples">
  ## Exemplos
</div>

<div id="example-json">
  ### Uso básico com JSONEachRow
</div>

```sql theme={null}
SELECT groupFormat('JSONEachRow')(number, toString(number))
FROM numbers(3);
```

Resultado:

```text theme={null}
{"c1":0,"c2":"0"}
{"c1":1,"c2":"1"}
{"c1":2,"c2":"2"}
```

<div id="groupFormat">
  ## groupFormat
</div>

Introduzido em: v

Formata as linhas de cada grupo usando o formato de saída especificado e retorna o resultado como uma string.

O nome do formato é passado como parâmetro, e os argumentos são as colunas a serem formatadas.
Os nomes das colunas são gerados como c1, c2, ... na saída formatada.

**Sintaxe**

```sql theme={null}
groupFormat(format)(x, y, ...)
```

**Parâmetros**

* `format` — Nome do formato de saída. Por exemplo, JSONEachRow, CSV, TabSeparated. [`String`](/docs/pt-BR/reference/data-types/string)

**Argumentos**

* `x, y, ...` — Expressões a serem formatadas como linhas. [`Any`](/docs/pt-BR/reference/data-types/index)

**Valor retornado**

Saída formatada do grupo. [`String`](/docs/pt-BR/reference/data-types/string)

**Exemplos**

**Uso básico**

```sql title=Query theme={null}
SELECT groupFormat('JSONEachRow')(number, toString(number))
FROM numbers(3)
```

```response title=Response theme={null}
{"c1":0,"c2":"0"}
{"c1":1,"c2":"1"}
{"c1":2,"c2":"2"}
```