> ## 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.

> 各グループ内の行を出力フォーマットを使って整形し、その結果を文字列として返します。

# groupFormat

各グループ内の行を出力フォーマットを使って整形し、その結果を文字列として返します。`formatRow` と似ていますが、グループ全体に対して動作し、ブロックベースのフォーマットを使用できます。

<Warning>
  整形後の文字列が生成される前に、各グループのすべての行がメモリに蓄積されます。非常に多くの行を含むグループでは、これにより大量のメモリを消費する可能性があります。メモリ使用量を抑えるには、サブクエリ内で `LIMIT` を使用するか、大きなグループを分割することを検討してください。
</Warning>

<div id="syntax">
  ## 構文
</div>

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

<div id="parameters">
  ## パラメータ
</div>

* `format` — 出力フォーマット名。たとえば `JSONEachRow`、`CSV`、`TabSeparated`。

<div id="arguments">
  ## 引数
</div>

* `x, y, ...` — 行形式でフォーマットする式。少なくとも1つの引数が必要です。

<div id="returned-value">
  ## 戻り値
</div>

* グループのフォーマット済み出力を含む [String](/docs/ja/reference/data-types/string)。

<Note>
  フォーマット済み出力内のカラム名は、引数の順序に従って `c1`、`c2`、... のように生成されます。

  フォーマットされた行の順序は保証されません。

  クエリのフォーマット設定 (たとえば `format_csv_delimiter` や `output_format_json_quote_64bit_integers`) は、集約関数の初期化時に取り込まれ、出力の生成に使用されます。`output_format_write_statistics` 設定は常に無効にされるため、フォーマット済み文字列に統計情報セクションが含まれることはありません。
</Note>

<div id="null-handling">
  ## NULL の処理
</div>

`groupArray` や `groupConcat` と同様に、`groupFormat` では、いずれかの引数が `NULL` の行はスキップされ、そのような行はフォーマットされた出力には含まれません。引数が Nullable の場合、結果の型は `Nullable(String)` になります。また、すべての行がスキップされるグループや、型 `Nullable(Nothing)` の型指定なしリテラル `NULL` 引数は、汎用の `Null` combinator によって `NULL` を返します。

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

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

<div id="example-json">
  ### JSONEachRowの基本的な使い方
</div>

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

結果:

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

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

導入バージョン: v

各グループの行を指定した出力フォーマットで整形し、その結果を文字列として返します。

フォーマット名はパラメータで渡し、引数には整形対象のカラムを指定します。
整形後の出力では、カラム名は c1, c2, ... として生成されます。

**構文**

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

**パラメータ**

* `format` — 出力フォーマット名。たとえば、JSONEachRow、CSV、TabSeparated。[`String`](/docs/ja/reference/data-types/string)

**引数**

* `x, y, ...` — 行としてフォーマットする式。[`Any`](/docs/ja/reference/data-types/index)

**戻り値**

グループ用にフォーマットされた出力。[`String`](/docs/ja/reference/data-types/string)

**例**

**基本的な使い方**

```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"}
```