> ## 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, ...` — تعبيرات تُنسَّق على شكل صفوف. يجب توفير وسيط واحد على الأقل.

<div id="returned-value">
  ## القيمة المعادة
</div>

* ‏[String](/docs/ar/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)`، كما أن المجموعة التي يتم تخطّي جميع صفوفها — وكذلك وسيطة `NULL` غير محددة النوع بوصفها قيمة حرفية من النوع `Nullable(Nothing)` — تُرجِع القيمة `NULL` عبر المُركِّب العام `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/ar/reference/data-types/string)

**الوسائط**

* `x, y, ...` — تعبيرات لتنسيقها على شكل صفوف. [`Any`](/docs/ar/reference/data-types/index)

**القيمة المُعادة**

الناتج المنسّق للمجموعة. [`String`](/docs/ar/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"}
```