> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> توثيق دوال استبدال السلاسل النصية

# دوال استبدال السلاسل النصية

[دوال السلاسل النصية العامة](/ar/reference/functions/regular-functions/string-functions) و[دوال البحث داخل السلاسل النصية](/ar/reference/functions/regular-functions/string-search-functions) موضَّحة كلٌّ على حدة.

<Note>
  تُولَّد الوثائق أدناه من جدول النظام `system.functions`.
</Note>

{/*AUTOGENERATED_START*/}

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

قُدِّم في: v20.1.0

نسّق سلسلة `pattern` باستخدام القيم (السلاسل النصية، والأعداد الصحيحة، وما إلى ذلك) المدرجة في الوسيطات، بطريقة مشابهة للتنسيق في بايثون.
يمكن أن تحتوي سلسلة النمط على حقول استبدال محاطة بأقواس معقوفة `{}`.
ويُعدّ أي شيء غير موجود داخل الأقواس نصًا حرفيًا، ويُنسخ كما هو إلى المخرجات.
يمكن تمثيل القوس المعقوف الحرفي باستخدام قوسين: `{{` و `}}`.
يمكن أن تكون أسماء الحقول أرقامًا (تبدأ من الصفر) أو فارغة (وفي هذه الحالة تُسنَد إليها ضمنيًا أرقام متزايدة بالتتابع).

**الصياغة**

```sql theme={null}
format(pattern, s0[, s1, ...])
```

**المعاملات**

* `pattern` — سلسلة التنسيق التي تحتوي على عناصر نائبة. [`String`](/ar/reference/data-types/string)
* `s0[, s1, ...]` — قيمة واحدة أو أكثر لإحلالها في النمط. [`Any`](/ar/reference/data-types/index)

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

تُرجع سلسلة نصية منسّقة. [`String`](/ar/reference/data-types/string)

**أمثلة**

**عناصر نائبة مرقّمة**

```sql title=Query theme={null}
SELECT format('{1} {0} {1}', 'World', 'Hello')
```

```response title=Response theme={null}
┌─format('{1} {0} {1}', 'World', 'Hello')─┐
│ Hello World Hello                       │
└─────────────────────────────────────────┘
```

**الترقيم الضمني**

```sql title=Query theme={null}
SELECT format('{} {}', 'Hello', 'World')
```

```response title=Response theme={null}
┌─format('{} {}', 'Hello', 'World')─┐
│ Hello World                       │
└───────────────────────────────────┘
```

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

قُدِّمت في: v24.9.0

يستبدل جزءًا من السلسلة `input` بسلسلة أخرى هي `replace`، بدءًا من الموضع `offset` المفهرس ابتداءً من 1.

**الصياغة**

```sql theme={null}
overlay(s, replace, offset[, length])
```

**المعاملات**

* `s` — سلسلة الإدخال. [`String`](/ar/reference/data-types/string)
* `replace` — سلسلة الاستبدال [`const String`](/ar/reference/data-types/string)
* `offset` — عدد صحيح من النوع `Int` (بفهرسة تبدأ من 1). إذا كانت قيمة `offset` سالبة، فيُحسب من نهاية السلسلة `s`. [`Int`](/ar/reference/data-types/int-uint)
* `length` — اختياري. عدد صحيح من النوع `Int`. يحدد `length` طول المقطع داخل سلسلة الإدخال `s` المراد استبداله. إذا لم يتم تحديد `length`، فإن عدد البايتات المحذوفة من `s` يساوي طول `replace`؛ وإلا تُحذف `length` بايت. [`Int`](/ar/reference/data-types/int-uint)

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

تعيد سلسلة بعد الاستبدال. [`String`](/ar/reference/data-types/string)

**أمثلة**

**استبدال بسيط**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'mother', 4) AS res;
```

```response title=Response theme={null}
┌─res──────────────────────┐
│ My mother is from Mexico.│
└──────────────────────────┘
```

**الاستبدال مع تحديد الطول**

```sql title=Query theme={null}
SELECT overlay('My father is from Mexico.', 'dad', 4, 6) AS res;
```

```response title=Response theme={null}
┌─res───────────────────┐
│ My dad is from Mexico.│
└───────────────────────┘
```

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

أُضيف في: v24.9.0

يستبدل جزءًا من السلسلة `s` بسلسلة أخرى هي `replace`، بدءًا من الفهرس `offset` ذي الأساس 1.
يفترض أن السلسلة تحتوي على نص مرمّز بترميز UTF-8 صالح.
إذا لم يتحقق هذا الافتراض، فلن يُطرَح أي استثناء وستكون النتيجة غير معرّفة.

**الصيغة**

```sql theme={null}
overlayUTF8(s, replace, offset[, length])
```

**الوسيطات**

* `s` — سلسلة الإدخال. [`String`](/ar/reference/data-types/string)
* `replace` — سلسلة الاستبدال. [`const String`](/ar/reference/data-types/string)
* `offset` — عدد صحيح من النوع `Int` (بفهرسة تبدأ من 1). إذا كانت قيمة `offset` سالبة، فيُحسب الموضع من نهاية سلسلة الإدخال `s`. [`(U)Int*`](/ar/reference/data-types/int-uint)
* `length` — اختياري. يحدد طول المقتطف داخل سلسلة الإدخال `s` المطلوب استبداله. إذا لم يتم تحديد `length`، فإن عدد الأحرف المُزالة من `s` يساوي طول `replace`، وإلا فتُزال `length` أحرف. [`(U)Int*`](/ar/reference/data-types/int-uint)

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

تعيد سلسلة نصية بعد الاستبدال. [`String`](/ar/reference/data-types/string)

**أمثلة**

**استبدال UTF-8**

```sql title=Query theme={null}
SELECT overlayUTF8('Mein Vater ist aus Österreich.', 'der Türkei', 20) AS res;
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Mein Vater ist aus der Türkei.│
└───────────────────────────────┘
```

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

أُضيف في: v24.8.0

تنسّق الدالة `printf` السلسلة المعطاة باستخدام القيم (مثل السلاسل النصية والأعداد الصحيحة والأعداد ذات الفاصلة العائمة وغيرها) المدرجة في الوسائط، على نحو مشابه لدالة printf في C++.
يمكن أن تحتوي سلسلة التنسيق على محددات تنسيق تبدأ بالمحرف `%`.
ويُعدّ أي شيء لا يقع ضمن `%` ومحدد التنسيق الذي يليه نصًا حرفيًا، ويُنسخ كما هو إلى المخرجات.
يمكن إفلات المحرف `%` الحرفي باستخدام `%%`.
يمكن أن تكون سلسلة التنسيق إما ثابتًا أو تعبير عمود، مما يتيح استخدام أنماط تنسيق مختلفة لكل صف.

**البنية**

```sql theme={null}
printf(format[, sub1, sub2, ...])
```

**الوسائط**

* `format` — سلسلة التنسيق التي تحتوي على محددات `%`. [`String`](/ar/reference/data-types/string)
* `sub1, sub2, ...` — اختياري. صفر أو أكثر من القيم لإدراجها في سلسلة التنسيق. [`Any`](/ar/reference/data-types/index)

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

يعيد سلسلة منسّقة. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تنسيق بأسلوب C++**

```sql title=Query theme={null}
SELECT printf('%%%s %s %d', 'Hello', 'World', 2024);
```

```response title=Response theme={null}
┌─printf('%%%s %s %d', 'Hello', 'World', 2024)─┐
│ %Hello World 2024                            │
└──────────────────────────────────────────────┘
```

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

أُضيف في: v20.1.0

يضيف شرطة مائلة عكسية قبل هذه المحارف ذات المعنى الخاص في التعبيرات النمطية: `\0`, `\\`, `|`, `(`, `)`, `^`, `$`, `.`, `[`, `]`, `?`, `*`, `+`, `{`, `:`, `-`.
ويختلف هذا التنفيذ قليلًا عن re2::RE2::QuoteMeta.
فهو يهرّب البايت الصفري على هيئة `\0` بدلًا من `\x00`، ولا يهرّب إلا المحارف المطلوبة.

**الصياغة**

```sql theme={null}
regexpQuoteMeta(s)
```

**المعاملات**

* `s` — سلسلة الإدخال النصية التي تحتوي على أحرف يجب عمل escape لها في التعابير النمطية. [`String`](/ar/reference/data-types/string)

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

يُرجع سلسلة نصية مع عمل escape للأحرف الخاصة في التعابير النمطية. [`String`](/ar/reference/data-types/string)

**أمثلة**

**عمل escape للأحرف الخاصة في التعابير النمطية**

```sql title=Query theme={null}
SELECT regexpQuoteMeta('Hello. [World]? (Yes)*') AS res
```

```response title=Response theme={null}
┌─res───────────────────────────┐
│ Hello\. \[World\]\? \(Yes\)\* │
└───────────────────────────────┘
```

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

أُضيف في: v1.1.0

يستبدل جميع حالات ظهور السلسلة الفرعية `pattern` في `haystack` بالسلسلة `replacement`.

**البنية**

```sql theme={null}
replaceAll(haystack, pattern, replacement)
```

**الأسماء المستعارة**: `replace`

**الوسيطات**

* `haystack` — سلسلة الإدخال المراد البحث فيها. [`String`](/ar/reference/data-types/string)
* `pattern` — السلسلة الفرعية المطلوب العثور عليها واستبدالها. [`const String`](/ar/reference/data-types/string)
* `replacement` — السلسلة التي سيُستبدل بها النمط. [`const String`](/ar/reference/data-types/string)

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

تُرجِع سلسلة استُبدلت فيها جميع تكرارات النمط. [`String`](/ar/reference/data-types/string)

**أمثلة**

**استبدال جميع التكرارات**

```sql title=Query theme={null}
SELECT replaceAll('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res──────────┐
│ Hi, Hi world │
└──────────────┘
```

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

تم تقديمه في: v1.1.0

يستبدل أول ظهور للسلسلة الفرعية `pattern` في `haystack` بالسلسلة `replacement`.

**الصيغة**

```sql theme={null}
replaceOne(haystack, pattern, replacement)
```

**الوسائط**

* `haystack` — سلسلة الإدخال المراد البحث فيها. [`String`](/ar/reference/data-types/string)
* `pattern` — السلسلة الفرعية المطلوب العثور عليها واستبدالها. [`const String`](/ar/reference/data-types/string)
* `replacement` — السلسلة التي سيُستبدل بها النمط. [`const String`](/ar/reference/data-types/string)

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

يعيد سلسلة نصية بعد استبدال أول ظهور للنمط. [`String`](/ar/reference/data-types/string)

**أمثلة**

**استبدال أول ظهور**

```sql title=Query theme={null}
SELECT replaceOne('Hello, Hello world', 'Hello', 'Hi') AS res;
```

```response title=Response theme={null}
┌─res─────────────┐
│ Hi, Hello world │
└─────────────────┘
```

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

طُرحت في: v1.1.0

تشبه `replaceRegexpOne`، لكنها تستبدل جميع حالات ظهور النمط.
واستثناءً من ذلك، إذا طابق تعبير نمطي سلسلة فرعية فارغة، فلا يُجرى الاستبدال أكثر من مرة واحدة.

**الصيغة**

```sql theme={null}
replaceRegexpAll(haystack, pattern, replacement)
```

**الأسماء البديلة**: `REGEXP_REPLACE`

**الوسيطات**

* `haystack` — سلسلة الإدخال المراد البحث فيها. [`String`](/ar/reference/data-types/string)
* `pattern` — نمط التعبير النمطي المراد العثور عليه. [`const String`](/ar/reference/data-types/string)
* `replacement` — السلسلة التي سيُستبدل بها النمط، وقد تحتوي على استبدالات. [`const String`](/ar/reference/data-types/string)

**القيمة المرجعة**

يعيد سلسلةً استُبدلت فيها جميع المطابقات للتعبير النمطي. [`String`](/ar/reference/data-types/string)

**أمثلة**

**استبدال جميع الأحرف بنسخة مضاعفة**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello123', '.', '\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res──────────────────┐
│ HHeelllloo112233     │
└──────────────────────┘
```

**مثال على استبدال سلسلة فرعية فارغة**

```sql title=Query theme={null}
SELECT replaceRegexpAll('Hello, World!', '^', 'here: ') AS res
```

```response title=Response theme={null}
┌─res─────────────────┐
│ here: Hello, World! │
└─────────────────────┘
```

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

أُضيف في: v1.1.0

يستبدل أول ظهور للسلسلة الفرعية المطابقة للتعبير النمطي `pattern` (بصيغة re2) في `haystack` بالسلسلة `replacement`.
يمكن أن تحتوي `replacement` على استبدالات `\0-\9`.
تقابل الاستبدالات `\1-\9` المجموعة الملتقِطة الأولى حتى التاسعة (المطابقة الفرعية)، بينما يقابل الاستبدال `\0` المطابقة كاملةً.
لاستخدام المحرف `\` حرفيًا في السلسلتين `pattern` أو `replacement`، قم بتهريبه باستخدام `\`.
ضع في اعتبارك أيضًا أن القيم الحرفية النصية تتطلب تهريبًا إضافيًا.

**الصيغة**

```sql theme={null}
replaceRegexpOne(haystack, pattern, replacement)
```

**الوسائط**

* `haystack` — سلسلة الإدخال المراد البحث فيها. [`String`](/ar/reference/data-types/string)
* `pattern` — نمط التعبير النمطي المطلوب العثور عليه. [`const String`](/ar/reference/data-types/string)
* `replacement` — السلسلة التي سيُستبدل بها النمط، وقد تتضمن استبدالات. [`const String`](/ar/reference/data-types/string)

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

يعيد سلسلة جرى فيها استبدال أول تطابق للتعبير النمطي. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تحويل تواريخ ISO إلى التنسيق الأمريكي**

```sql title=Query theme={null}
SELECT DISTINCT
    EventDate,
    replaceRegexpOne(toString(EventDate), '(\\d{4})-(\\d{2})-(\\d{2})', '\\2/\\3/\\1') AS res
FROM test.hits
LIMIT 7
FORMAT TabSeparated
```

```response title=Response theme={null}
2014-03-17      03/17/2014
2014-03-18      03/18/2014
2014-03-19      03/19/2014
2014-03-20      03/20/2014
2014-03-21      03/21/2014
2014-03-22      03/22/2014
2014-03-23      03/23/2014
```

**نسخ سلسلة نصية عشر مرات**

```sql title=Query theme={null}
SELECT replaceRegexpOne('Hello, World!', '.*', '\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0\\\\0') AS res
```

```response title=Response theme={null}
┌─res────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┐
│ Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World!Hello, World! │
└────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
```

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

أُضيفت في: v22.7.0

تستبدل الأحرف في السلسلة `s` باستخدام مطابقة أحرف واحدًا لواحد تحددها السلسلتان `from` و`to`.
يجب أن تكون `from` و`to` سلسلتين ثابتتين من نوع ASCII.
إذا كان حجم `from` و`to` متساويًا، فسيُستبدل كل ظهور لأول حرف من `first` في `s` بأول حرف من `to`، ويُستبدل كل ظهور لثاني حرف من `first` في `s` بثاني حرف من `to`، وهكذا.
إذا كانت `from` تحتوي على أحرف أكثر من `to`، فستُحذف من `s` جميع ظهورات الأحرف الموجودة في نهاية `from` التي لا يقابلها حرف في `to`.
لا تعدّل الدالة الأحرف غير التابعة لـ ASCII في `s`.

**البنية**

```sql theme={null}
translate(s, from, to)
```

**الوسيطات**

* `s` — سلسلة الإدخال المراد ترجمتها. [`String`](/ar/reference/data-types/string)
* `from` — سلسلة ASCII ثابتة تحتوي على الأحرف المراد استبدالها. [`const String`](/ar/reference/data-types/string)
* `to` — سلسلة ASCII ثابتة تحتوي على أحرف الاستبدال. [`const String`](/ar/reference/data-types/string)

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

تعيد سلسلة بعد تطبيق تحويلات الأحرف عليها. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تعيين الأحرف**

```sql title=Query theme={null}
SELECT translate('Hello, World!', 'delor', 'DELOR') AS res
```

```response title=Response theme={null}
┌─res───────────┐
│ HELLO, WORLD! │
└───────────────┘
```

**أطوال متفاوتة**

```sql title=Query theme={null}
SELECT translate('clickhouse', 'clickhouse', 'CLICK') AS res
```

```response title=Response theme={null}
┌─res───┐
│ CLICK │
└───────┘
```

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

ظهر في: v22.7.0

مثل [`translate`](#translate)، لكنه يفترض أن `s` و`from` و`to` سلاسل نصية مرمّزة بترميز UTF-8.

**الصياغة**

```sql theme={null}
translateUTF8(s, from, to)
```

**الوسائط**

* `s` — سلسلة UTF-8 المُدخلة المراد تحويلها. [`String`](/ar/reference/data-types/string)
* `from` — سلسلة UTF-8 ثابتة تحتوي على الأحرف المراد استبدالها. [`const String`](/ar/reference/data-types/string)
* `to` — سلسلة UTF-8 ثابتة تحتوي على أحرف الاستبدال. [`const String`](/ar/reference/data-types/string)

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

تعيد قيمة من نوع البيانات `String`. [`String`](/ar/reference/data-types/string)

**أمثلة**

**تحويل أحرف UTF-8**

```sql title=Query theme={null}
SELECT translateUTF8('Münchener Straße', 'üß', 'us') AS res;
```

```response title=Response theme={null}
┌─res──────────────┐
│ Munchener Strase │
└──────────────────┘
```