> ## 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.
> توثيق للدوال المستخدَمة في التعامل مع عناوين IPv4 وIPv6.
# دوال للتعامل مع عناوين IPv4 وIPv6
{/*AUTOGENERATED_START*/}
## IPv4CIDRToRange
أُضيفت في: v20.1.0
تأخذ عنوان IPv4 مع طول بادئة التوجيه غير الصنفي بين النطاقات (CIDR) الخاصة به، وتُرجع نطاق عناوين الشبكة الفرعية على هيئة Tuple من قيمتَي IPv4: أول عنوان وآخر عنوان في تلك الشبكة الفرعية.
للاطلاع على إصدار IPv6، انظر [`IPv6CIDRToRange`](#IPv4CIDRToRange).
**البنية**
```sql theme={null}
IPv4CIDRToRange(ipv4, cidr)
```
**المعاملات**
* `ipv4` — عنوان IPv4. [`IPv4`](/ar/reference/data-types/ipv4) أو [`String`](/ar/reference/data-types/string)
* `cidr` — قيمة CIDR. [`UInt8`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد قيمة Tuple تحتوي على عنواني IPv4 يمثّلان نطاق الشبكة الفرعية. [`Tuple(IPv4, IPv4)`](/ar/reference/data-types/tuple)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT IPv4CIDRToRange(toIPv4('192.168.5.2'), 16);
```
```response title=Response theme={null}
┌─IPv4CIDRToRange(toIPv4('192.168.5.2'), 16)─┐
│ ('192.168.0.0','192.168.255.255') │
└────────────────────────────────────────────┘
```
## IPv4NumToString
أُضيفت في: v1.1.0
تحوّل عددًا صحيحًا من 32 بت إلى التمثيل النصي لعنوان IPv4 بصيغة التدوين العشري المنقّط (بالتنسيق A.B.C.D).
وتفسّر الإدخال باستخدام ترتيب البايتات big-endian.
**البنية**
```sql theme={null}
IPv4NumToString(num)
```
**الأسماء البديلة**: `INET_NTOA`
**المعاملات**
* `num` — عنوان IPv4 بصيغة رقم `UInt32`. [`UInt32`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يُرجع رقمًا يمثّل عنوان MAC، أو `0` إذا كانت الصيغة غير صالحة. [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
IPv4NumToString(3232235521)
```
```response title=Response theme={null}
192.168.0.1
```
## IPv4NumToStringClassC
أُضيف في: v1.1.0
يحوّل عددًا صحيحًا من 32 بت إلى التمثيل النصي لعنوان IPv4 الخاص به بتدوين عشري منقّط (بالتنسيق A.B.C.D)،
على غرار [`IPv4NumToString`](#IPv4NumToString)، ولكن باستخدام `xxx` بدلًا من الأوكتيت الأخير.
**البنية**
```sql theme={null}
IPv4NumToStringClassC(num)
```
**المعاملات**
* `num` — عنوان IPv4 ممثَّلًا كرقم UInt32. [`UInt32`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد سلسلة نصية لعنوان IPv4 مع استبدال الثُّمانيّة الأخيرة بـ xxx. [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال أساسي مع التجميع**
```sql title=Query theme={null}
SELECT
IPv4NumToStringClassC(ClientIP) AS k,
count() AS c
FROM test.hits
GROUP BY k
ORDER BY c DESC
LIMIT 10
```
```response title=Response theme={null}
┌─k──────────────┬─────c─┐
│ 83.149.9.xxx │ 26238 │
│ 217.118.81.xxx │ 26074 │
│ 213.87.129.xxx │ 25481 │
│ 83.149.8.xxx │ 24984 │
│ 217.118.83.xxx │ 22797 │
│ 78.25.120.xxx │ 22354 │
│ 213.87.131.xxx │ 21285 │
│ 78.25.121.xxx │ 20887 │
│ 188.162.65.xxx │ 19694 │
│ 83.149.48.xxx │ 17406 │
└────────────────┴───────┘
```
## IPv4StringToNum
أُضيف في: v1.1.0
يحوّل سلسلة عنوان IPv4 المكتوبة بالتدوين العشري المنقّط (بالتنسيق A.B.C.D) إلى تمثيلها العددي الصحيح المقابل بطول 32 بت. (وهذا هو عكس [`IPv4NumToString`](#IPv4NumToString)).
إذا كان عنوان IPv4 بتنسيق غير صالح، فسيتم طرح استثناء.
**البنية**
```sql theme={null}
IPv4StringToNum(string)
```
**الأسماء البديلة**: `INET_ATON`
**المعاملات**
* `string` — سلسلة نصية لعنوان IPv4. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يُرجع عنوان IPv4. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
IPv4StringToNum('192.168.0.1')
```
```response title=Response theme={null}
3232235521
```
## IPv4StringToNumOrDefault
أُضيف في: v22.3.0
يحوّل سلسلة نصية لعنوان IPv4 مكتوبة بتدوين عشري منقّط (بتنسيق A.B.C.D) إلى التمثيل المقابل لها كعدد صحيح من 32 بت، ولكن إذا كان عنوان IPv4 بتنسيق غير صالح، فإنه يُرجع `0`.
**البنية**
```sql theme={null}
IPv4StringToNumOrDefault(string)
```
**المعاملات**
* `string` — عنوان IPv4 بصيغة نصية. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يُرجع عنوان IPv4، أو `0` إذا كان غير صالح. [`UInt32`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على عنوان غير صالح**
```sql title=Query theme={null}
SELECT
IPv4StringToNumOrDefault('127.0.0.1') AS valid,
IPv4StringToNumOrDefault('invalid') AS invalid;
```
```response title=Response theme={null}
┌──────valid─┬─invalid─┐
│ 2130706433 │ 0 │
└────────────┴─────────┘
```
## IPv4StringToNumOrNull
أُضيف في: v22.3.0
يحوّل عددًا صحيحًا من 32 بت إلى التمثيل النصي لعنوان IPv4 بتدوين عشري منقّط (بتنسيق A.B.C.D)، ولكن إذا كان عنوان IPv4 بتنسيق غير صالح، فإنه يُرجع `NULL`.
**البنية**
```sql theme={null}
IPv4StringToNumOrNull(string)
```
**المعاملات**
* `string` — سلسلة نصية لعنوان IPv4. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد عنوان IPv4، أو `NULL` إذا كان غير صالح. [`Nullable(UInt32)`](/ar/reference/data-types/nullable)
**أمثلة**
**مثال على عنوان غير صالح**
```sql title=Query theme={null}
SELECT
IPv4StringToNumOrNull('127.0.0.1') AS valid,
IPv4StringToNumOrNull('invalid') AS invalid;
```
```response title=Response theme={null}
┌──────valid─┬─invalid─┐
│ 2130706433 │ ᴺᵁᴸᴸ │
└────────────┴─────────┘
```
## IPv4ToIPv6
أُضيفت في: v1.1.0
تفسِّر عددًا بطول 32 بت (big endian) على أنه عنوان IPv4، ثم تفسِّره بوصفه عنوان IPv6 المقابل بتنسيق `FixedString(16)`.
**البنية**
```sql theme={null}
IPv4ToIPv6(x)
```
**المعاملات**
* `x` — عنوان IPv4. [`UInt32`](/ar/reference/data-types/int-uint)
**القيمة المعادة**
يعيد عنوان IPv6 بالتنسيق الثنائي. [`FixedString(16)`](/ar/reference/data-types/fixedstring)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT IPv6NumToString(IPv4ToIPv6(IPv4StringToNum('192.168.0.1'))) AS addr;
```
```response title=Response theme={null}
┌─addr───────────────┐
│ ::ffff:192.168.0.1 │
└────────────────────┘
```
## IPv6CIDRToRange
أُضيفت في: v20.1.0
تأخذ عنوان IPv6 مع طول بادئة CIDR، وتُرجع نطاق عناوين الشبكة الفرعية على شكل Tuple من عنوانَي IPv6: الأدنى والأعلى ضمن تلك الشبكة الفرعية.
للاطلاع على إصدار IPv4، راجع [`IPv4CIDRToRange`](#IPv4CIDRToRange).
**البنية**
```sql theme={null}
IPv6CIDRToRange(ipv6, cidr)
```
**المعاملات**
* `ipv6` — عنوان IPv6. [`IPv6`](/ar/reference/data-types/ipv6) أو [`String`](/ar/reference/data-types/string)
* `cidr` — قيمة CIDR. [`UInt8`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
تعيد قيمة من النوع Tuple تتضمن عنواني IPv6 يمثّلان نطاق الشبكة الفرعية. [`Tuple(IPv6, IPv6)`](/ar/reference/data-types/tuple)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT IPv6CIDRToRange(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32);
```
```response title=Response theme={null}
┌─IPv6CIDRToRange(toIPv6('2001:0db8:0000:85a3:0000:0000:ac1f:8001'), 32)─┐
│ ('2001:db8::','2001:db8:ffff:ffff:ffff:ffff:ffff:ffff') │
└────────────────────────────────────────────────────────────────────────┘
```
## IPv6NumToString
أُضيفت في: v1.1.0
يحوّل عنوان IPv6 من التنسيق الثنائي (FixedString(16)) إلى تمثيله النصي القياسي.
تُعرَض عناوين IPv6 المضمَّن فيها IPv4 بالتنسيق `::ffff:111.222.33.44`.
**البنية**
```sql theme={null}
IPv6NumToString(x)
```
**الأسماء البديلة**: `INET6_NTOA`
**المعاملات**
* `x` — عنوان IPv6 بتنسيق ثنائي. [`FixedString(16)`](/ar/reference/data-types/fixedstring) أو [`IPv6`](/ar/reference/data-types/ipv6)
**القيمة المُعادة**
يعيد سلسلة عنوان IPv6 بتنسيق نصي. [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT IPv6NumToString(toFixedString(unhex('2A0206B8000000000000000000000011'), 16)) AS addr;
```
```response title=Response theme={null}
┌─addr─────────┐
│ 2a02:6b8::11 │
└──────────────┘
```
**تحليل IPv6 باستخدام جدول hits**
```sql title=Query theme={null}
SELECT
IPv6NumToString(ClientIP6 AS k),
count() AS c
FROM hits_all
WHERE EventDate = today() AND substring(ClientIP6, 1, 12) != unhex('00000000000000000000FFFF')
GROUP BY k
ORDER BY c DESC
LIMIT 10
```
```response title=Response theme={null}
┌─IPv6NumToString(ClientIP6)──────────────┬─────c─┐
│ 2a02:2168:aaa:bbbb::2 │ 24695 │
│ 2a02:2698:abcd:abcd:abcd:abcd:8888:5555 │ 22408 │
│ 2a02:6b8:0:fff::ff │ 16389 │
│ 2a01:4f8:111:6666::2 │ 16016 │
│ 2a02:2168:888:222::1 │ 15896 │
│ 2a01:7e00::ffff:ffff:ffff:222 │ 14774 │
│ 2a02:8109:eee:ee:eeee:eeee:eeee:eeee │ 14443 │
│ 2a02:810b:8888:888:8888:8888:8888:8888 │ 14345 │
│ 2a02:6b8:0:444:4444:4444:4444:4444 │ 14279 │
│ 2a01:7e00::ffff:ffff:ffff:ffff │ 13880 │
└─────────────────────────────────────────┴───────┘
```
**عناوين IPv4 الممثلة بصيغة IPv6**
```sql title=Query theme={null}
SELECT
IPv6NumToString(ClientIP6 AS k),
count() AS c
FROM hits_all
WHERE EventDate = today()
GROUP BY k
ORDER BY c DESC
LIMIT 10
```
```response title=Response theme={null}
┌─IPv6NumToString(ClientIP6)─┬──────c─┐
│ ::ffff:94.26.111.111 │ 747440 │
│ ::ffff:37.143.222.4 │ 529483 │
│ ::ffff:5.166.111.99 │ 317707 │
│ ::ffff:46.38.11.77 │ 263086 │
│ ::ffff:79.105.111.111 │ 186611 │
│ ::ffff:93.92.111.88 │ 176773 │
│ ::ffff:84.53.111.33 │ 158709 │
│ ::ffff:217.118.11.22 │ 154004 │
│ ::ffff:217.118.11.33 │ 148449 │
│ ::ffff:217.118.11.44 │ 148243 │
└────────────────────────────┴────────┘
```
## IPv6StringToNum
أُضيف في: v1.1.0
يحوّل عنوان IPv6 من تمثيله النصي القياسي إلى تنسيق ثنائي (`FixedString(16)`).
يقبل عنوان IPv6 مضمَّن فيه IPv4 بالتنسيق `::ffff:111.222.33.44.`.
إذا كان عنوان IPv6 بتنسيق غير صالح، يتم طرح استثناء.
إذا كانت سلسلة الإدخال تحتوي على عنوان IPv4 صالح، فسيُرجِع مكافئه من IPv6.
يمكن أن تكون قيمة HEX بأحرف كبيرة أو صغيرة.
**البنية**
```sql theme={null}
IPv6StringToNum(string)
```
**الأسماء البديلة**: `INET6_ATON`
**المعاملات**
* `string` — سلسلة نصية لعنوان IPv6. [`String`](/ar/reference/data-types/string)
**القيمة المعادة**
تعيد عنوان IPv6 بصيغة ثنائية. [`FixedString(16)`](/ar/reference/data-types/fixedstring)
**أمثلة**
**مثال أساسي**
```sql title=Query theme={null}
SELECT addr, cutIPv6(IPv6StringToNum(addr), 0, 0) FROM (SELECT ['notaddress', '127.0.0.1', '1111::ffff'] AS addr) ARRAY JOIN addr;
```
```response title=Response theme={null}
┌─addr───────┬─cutIPv6(IPv6StringToNum(addr), 0, 0)─┐
│ notaddress │ :: │
│ 127.0.0.1 │ ::ffff:127.0.0.1 │
│ 1111::ffff │ 1111::ffff │
└────────────┴──────────────────────────────────────┘
```
## IPv6StringToNumOrDefault
قُدِّمت في: v22.3.0
تُحوِّل عنوان IPv6 من تمثيله النصي القياسي إلى تنسيق ثنائي (`FixedString(16)`).
تقبل عنوان IPv6 مضمَّن فيه IPv4 بالتنسيق `::ffff:111.222.33.44.`.
إذا كان عنوان IPv6 بتنسيق غير صالح، فستُرجع القيمة الافتراضية `::`.
**البنية**
```sql theme={null}
IPv6StringToNumOrDefault(string)
```
**المعاملات**
* `string` — سلسلة تمثل عنوان IPv6. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
عنوان IPv6 بتنسيق ثنائي، أو `FixedString(16)` مملوء بالأصفار إذا كان العنوان غير صالح. [`FixedString(16)`](/ar/reference/data-types/fixedstring)
**أمثلة**
**مثال أساسي على عنوان غير صالح**
```sql title=Query theme={null}
SELECT
IPv6NumToString(IPv6StringToNumOrDefault('2001:db8::1')) AS valid,
IPv6NumToString(IPv6StringToNumOrDefault('invalid')) AS invalid;
```
```response title=Response theme={null}
┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ :: │
└─────────────┴─────────┘
```
## IPv6StringToNumOrNull
استُحدث في: v22.3.0
يحوّل عنوان IPv6 من تمثيله النصي القياسي إلى صيغة ثنائية (`FixedString(16)`).
يقبل عنوان IPv6 مضمَّن فيه IPv4 بالتنسيق `::ffff:111.222.33.44.`.
إذا كان عنوان IPv6 بتنسيق غير صالح، فستُرجع `NULL`.
**البنية**
```sql theme={null}
IPv6StringToNumOrNull(string)
```
**المعاملات**
* `string` — سلسلة نصية لعنوان IPv6. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يُرجع عنوان IPv6 بصيغة ثنائية، أو `NULL` إذا كان غير صالح. [`Nullable(FixedString(16))`](/ar/reference/data-types/nullable)
**أمثلة**
**مثال أساسي بعنوان غير صالح**
```sql title=Query theme={null}
SELECT
IPv6NumToString(IPv6StringToNumOrNull('2001:db8::1')) AS valid,
IPv6StringToNumOrNull('invalid') AS invalid;
```
```response title=Response theme={null}
┌─valid───────┬─invalid─┐
│ 2001:db8::1 │ ᴺᵁᴸᴸ │
└─────────────┴─────────┘
```
## cutIPv6
استُحدث في: v1.1.0
يقبل قيمة `FixedString(16)` تحتوي على عنوان IPv6 بالتنسيق الثنائي.
يُرجع سلسلة نصية تحتوي على العنوان بعد إزالة العدد المحدد من البايتات منه، بتنسيق نصي.
**الصياغة**
```sql theme={null}
cutIPv6(x, bytesToCutForIPv6, bytesToCutForIPv4)
```
**الوسيطات**
* `x` — عنوان IPv6 بصيغة ثنائية. [`FixedString(16)`](/ar/reference/data-types/fixedstring) أو [`IPv6`](/ar/reference/data-types/ipv6)
* `bytesToCutForIPv6` — عدد البايتات المطلوب إزالتها من IPv6. [`UInt8`](/ar/reference/data-types/int-uint)
* `bytesToCutForIPv4` — عدد البايتات المطلوب إزالتها من IPv4. [`UInt8`](/ar/reference/data-types/int-uint)
**القيمة المعادة**
تُرجِع سلسلة نصية تحتوي على عنوان IPv6 بتنسيق نصي بعد إزالة البايتات المحددة. [`String`](/ar/reference/data-types/string)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
WITH
IPv6StringToNum('2001:0DB8:AC10:FE01:FEED:BABE:CAFE:F00D') AS ipv6,
IPv4ToIPv6(IPv4StringToNum('192.168.0.1')) AS ipv4
SELECT
cutIPv6(ipv6, 2, 0),
cutIPv6(ipv4, 0, 2)
```
```response title=Response theme={null}
┌─cutIPv6(ipv6, 2, 0)─────────────────┬─cutIPv6(ipv4, 0, 2)─┐
│ 2001:db8:ac10:fe01:feed:babe:cafe:0 │ ::ffff:192.168.0.0 │
└─────────────────────────────────────┴─────────────────────┘
```
## isIPAddressInRange
أُضيفت في: v21.4.0
يحدّد ما إذا كان عنوان IP يقع ضمن شبكة ممثّلة بترميز [Classless Inter-Domain Routing (CIDR)](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing).
تقبل هذه الدالة عناوين IPv4 وIPv6 (والشبكات) الممثّلة كسلاسل نصية. وتُرجع `0` إذا لم يتطابق إصدار IP للعنوان مع إصدار CIDR.
**الصيغة**
```sql theme={null}
isIPAddressInRange(address, prefix)
```
**الوسيطات**
* `address` — عنوان IPv4 أو IPv6. [`String`](/ar/reference/data-types/string)
* `prefix` — بادئة شبكة IPv4 أو IPv6 بتنسيق CIDR. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد `1` إذا كان إصدار IP للعنوان يطابق CIDR، وإلا `0`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**عنوان IPv4 ضمن النطاق**
```sql title=Query theme={null}
SELECT isIPAddressInRange('127.0.0.1', '127.0.0.0/8')
```
```response title=Response theme={null}
1
```
**عنوان IPv4 خارج النطاق**
```sql title=Query theme={null}
SELECT isIPAddressInRange('127.0.0.1', 'ffff::/16')
```
```response title=Response theme={null}
0
```
**عنوان IPv6 خارج النطاق**
```sql title=Query theme={null}
SELECT isIPAddressInRange('::ffff:192.168.0.1', '::ffff:192.168.0.4/128')
```
```response title=Response theme={null}
0
```
## isIPv4String
أُضيفت في: v21.1.0
تحدّد ما إذا كانت سلسلة الإدخال عنوان IPv4 أم لا.
للاطّلاع على إصدار IPv6، راجع [`isIPv6String`](#isIPv6String).
**الصيغة**
```sql theme={null}
isIPv4String(string)
```
**المعاملات**
* `string` — سلسلة نصية لعنوان IP المطلوب التحقق منه. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تُرجع `1` إذا كانت `string` عنوان IPv4، وإلا فتُرجع `0`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT addr, isIPv4String(addr)
FROM(
SELECT ['0.0.0.0', '127.0.0.1', '::ffff:127.0.0.1'] AS addr
)
ARRAY JOIN addr;
```
```response title=Response theme={null}
┌─addr─────────────┬─isIPv4String(addr)─┐
│ 0.0.0.0 │ 1 │
│ 127.0.0.1 │ 1 │
│ ::ffff:127.0.0.1 │ 0 │
└──────────────────┴────────────────────┘
```
## isIPv6String
أُضيف في: v21.1.0
يتحقق مما إذا كانت سلسلة الإدخال عنوان IPv6 أم لا.
للاطلاع على إصدار IPv4، راجع [`isIPv4String`](#isIPv4String).
**الصيغة**
```sql theme={null}
isIPv6String(string)
```
**الوسائط**
* `string` — سلسلة نصية لعنوان IP المراد التحقق منه. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
تُرجِع `1` إذا كانت `string` عنوان IPv6، وإلا فتُرجِع `0`. [`UInt8`](/ar/reference/data-types/int-uint)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT addr, isIPv6String(addr)
FROM(SELECT ['::', '1111::ffff', '::ffff:127.0.0.1', '127.0.0.1'] AS addr)
ARRAY JOIN addr;
```
```response title=Response theme={null}
┌─addr─────────────┬─isIPv6String(addr)─┐
│ :: │ 1 │
│ 1111::ffff │ 1 │
│ ::ffff:127.0.0.1 │ 1 │
│ 127.0.0.1 │ 0 │
└──────────────────┴────────────────────┘
```
## toIPv4
أُضيف في: v20.1.0
يحوّل سلسلة نصية أو عنوان IPv4 بصيغة `UInt32` إلى النوع IPv4.
وهو مشابه للدالتين [`IPv4StringToNum`](/ar/reference/functions/regular-functions/ip-address-functions#IPv4StringToNum) و[`IPv4NumToString`](/ar/reference/functions/regular-functions/ip-address-functions#IPv4NumToString)، لكنه يدعم نوعَي البيانات: السلاسل النصية والأعداد الصحيحة غير الموقَّعة كوسيطات إدخال.
**الصياغة**
```sql theme={null}
toIPv4(x)
```
**الوسيطات**
* `x` — عنوان IPv4 من نوع [`String`](/ar/reference/data-types/string) أو [`UInt8/16/32`](/ar/reference/data-types/int-uint)
**القيمة المعادة**
يعيد عنوان IPv4. [`IPv4`](/ar/reference/data-types/ipv4)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT toIPv4('171.225.130.45');
```
```response title=Response theme={null}
┌─toIPv4('171.225.130.45')─┐
│ 171.225.130.45 │
└──────────────────────────┘
```
**مقارنة بدالتي IPv4StringToNum و IPv4NumToString.**
```sql title=Query theme={null}
WITH
'171.225.130.45' AS IPv4_string
SELECT
hex(IPv4StringToNum(IPv4_string)),
hex(toIPv4(IPv4_string))
```
```response title=Response theme={null}
┌─hex(IPv4StringToNum(IPv4_string))─┬─hex(toIPv4(IPv4_string))─┐
│ ABE1822D │ ABE1822D │
└───────────────────────────────────┴──────────────────────────┘
```
**التحويل من عدد صحيح**
```sql title=Query theme={null}
SELECT toIPv4(2130706433);
```
```response title=Response theme={null}
┌─toIPv4(2130706433)─┐
│ 127.0.0.1 │
└────────────────────┘
```
## toIPv4OrDefault
أُضيف في: v22.3.0
يحوِّل سلسلة نصية أو قيمة من النوع UInt32 تمثّل عنوان IPv4 إلى النوع [`IPv4`](/ar/reference/data-types/ipv4).
إذا كان عنوان IPv4 بتنسيق غير صالح، فسيُرجِع `0.0.0.0` (IPv4 بقيمة 0) أو قيمة IPv4 الافتراضية المُقدَّمة.
**البنية**
```sql theme={null}
toIPv4OrDefault(string[, default])
```
**الوسائط**
* `string` — سلسلة عنوان IP المراد تحويلها. [`String`](/ar/reference/data-types/string)
* `default` — اختياري. القيمة التي تُعاد إذا كانت السلسلة عنوان IPv4 غير صالح. [`IPv4`](/ar/reference/data-types/ipv4)
**القيمة المعادة**
يُرجع عنوان IPv4 الناتج عن تحويل السلسلة، أو القيمة الافتراضية إذا فشل التحويل. [`IPv4`](/ar/reference/data-types/ipv4)
**أمثلة**
**سلاسل IPv4 صالحة وغير صالحة**
```sql title=Query theme={null}
WITH
'192.168.1.1' AS valid_IPv4_string,
'999.999.999.999' AS invalid_IPv4_string,
'not_an_ip' AS malformed_string
SELECT
toIPv4OrDefault(valid_IPv4_string) AS valid,
toIPv4OrDefault(invalid_IPv4_string) AS default_value,
toIPv4OrDefault(malformed_string, toIPv4('8.8.8.8')) AS provided_default;
```
```response title=Response theme={null}
┌─valid─────────┬─default_value─┬─provided_default─┐
│ 192.168.1.1 │ 0.0.0.0 │ 8.8.8.8 │
└───────────────┴───────────────┴──────────────────┘
```
## toIPv4OrNull
قُدِّمت في: v22.3.0
يحوّل قيمة الإدخال إلى قيمة من النوع `IPv4`، لكنه يعيد `NULL` في حال حدوث خطأ.
يشبه [`toIPv4`](#toIPv4)، لكنه يعيد `NULL` بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.
الوسيطات المدعومة:
* التمثيلات النصية لعناوين IPv4 بالتدوين العشري المنقّط.
* التمثيلات الصحيحة لعناوين IPv4.
الوسيطات غير المدعومة (تعيد `NULL`):
* تنسيقات عناوين IP غير الصالحة.
* عناوين IPv6.
* القيم الخارجة عن النطاق.
* العناوين غير الصحيحة.
**البنية**
```sql theme={null}
toIPv4OrNull(x)
```
**الوسيطات**
* `x` — عنوان IPv4 بصيغة نصية أو كعدد صحيح. [`String`](/ar/reference/data-types/string) أو [`Integer`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد عنوان IPv4 عند النجاح، وإلا `NULL`. [`IPv4`](/ar/reference/data-types/ipv4) أو [`NULL`](/ar/reference/syntax#null)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT
toIPv4OrNull('192.168.1.1') AS valid_ip,
toIPv4OrNull('invalid.ip') AS invalid_ip
```
```response title=Response theme={null}
┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ ᴺᵁᴸᴸ │
└─────────────┴────────────┘
```
## toIPv4OrZero
أُضيف في: v23.1.0
يحوّل قيمة إدخال إلى قيمة من النوع [IPv4](/ar/reference/data-types/ipv4)، لكنه يعيد عنوان IPv4 صفريًا في حال حدوث خطأ.
يشبه [`toIPv4`](#toIPv4)، لكنه يعيد عنوان IPv4 صفريًا (`0.0.0.0`) بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.
الوسيطات المدعومة:
* التمثيلات النصية لعناوين IPv4 بالتدوين العشري المنقّط.
* التمثيلات العددية الصحيحة لعناوين IPv4.
الوسيطات غير المدعومة (تعيد عنوان IPv4 صفريًا):
* تنسيقات عناوين IP غير الصالحة.
* عناوين IPv6.
* القيم الخارجة عن النطاق.
**البنية**
```sql theme={null}
toIPv4OrZero(x)
```
**المعاملات**
* `x` — تمثيل نصي أو عدد صحيح لعنوان IPv4. [`String`](/ar/reference/data-types/string) أو [`Integer`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يعيد عنوان IPv4 عند النجاح، وإلا فيُعيد عنوان IPv4 صفريًا (`0.0.0.0`). [`IPv4`](/ar/reference/data-types/ipv4)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT
toIPv4OrZero('192.168.1.1') AS valid_ip,
toIPv4OrZero('invalid.ip') AS invalid_ip
```
```response title=Response theme={null}
┌─valid_ip────┬─invalid_ip─┐
│ 192.168.1.1 │ 0.0.0.0 │
└─────────────┴────────────┘
```
## toIPv6
أُضيف في: v20.1.0
يحوّل سلسلة نصية أو عنوان IPv6 بصيغة `UInt128` إلى النوع [`IPv6`](/ar/reference/data-types/ipv6).
بالنسبة إلى السلاسل النصية، إذا كان عنوان IPv6 بتنسيق غير صالح، فستُعاد قيمة فارغة.
وهو مشابه للدالتين [`IPv6StringToNum`](/ar/reference/functions/regular-functions/ip-address-functions#IPv6StringToNum) و[`IPv6NumToString`](/ar/reference/functions/regular-functions/ip-address-functions#IPv6NumToString)، اللتين تحوّلان عنوان IPv6 من التنسيق الثنائي وإليه (أي `FixedString(16)`).
إذا احتوت سلسلة الإدخال على عنوان IPv4 صالح، فستُعاد الصيغة المكافئة له في IPv6.
**الصياغة**
```sql theme={null}
toIPv6(x)
```
**المعاملات**
* `x` — عنوان IP. [`String`](/ar/reference/data-types/string) أو [`UInt128`](/ar/reference/data-types/int-uint)
**القيمة المُعادة**
يُرجع عنوان IPv6. [`IPv6`](/ar/reference/data-types/ipv6)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
WITH '2001:438:ffff::407d:1bc1' AS IPv6_string
SELECT
hex(IPv6StringToNum(IPv6_string)),
hex(toIPv6(IPv6_string));
```
```response title=Response theme={null}
┌─hex(IPv6StringToNum(IPv6_string))─┬─hex(toIPv6(IPv6_string))─────────┐
│ 20010438FFFF000000000000407D1BC1 │ 20010438FFFF000000000000407D1BC1 │
└───────────────────────────────────┴──────────────────────────────────┘
```
**مطابقة IPv4 مع IPv6**
```sql title=Query theme={null}
SELECT toIPv6('127.0.0.1');
```
```response title=Response theme={null}
┌─toIPv6('127.0.0.1')─┐
│ ::ffff:127.0.0.1 │
└─────────────────────┘
```
## toIPv6OrDefault
قُدِّمت في: v22.3.0
يحوّل سلسلة نصية أو قيمة UInt128 تمثّل عنوان IPv6 إلى النوع [`IPv6`](/ar/reference/data-types/ipv6).
إذا كان عنوان IPv6 بتنسيق غير صالح، فسيُرجِع `::` (IPv6 بقيمة 0) أو قيمة IPv6 الافتراضية المُحدَّدة.
**البنية**
```sql theme={null}
toIPv6OrDefault(string[, default])
```
**المعاملات**
* `string` — سلسلة عنوان IP المراد تحويلها. - `default` — اختياري. القيمة المطلوب إرجاعها إذا كانت `string` ذات تنسيق غير صالح.
**القيمة المُعادة**
يُرجع عنوان IPv6، وإلا فيُرجع `::` أو قيمة `default` الاختيارية المُقدَّمة إذا كانت الوسيطة `string` ذات تنسيق غير صالح. [`IPv6`](/ar/reference/data-types/ipv6)
**أمثلة**
**سلاسل IPv6 صالحة وغير صالحة**
```sql title=Query theme={null}
WITH
'2001:0db8:85a3:0000:0000:8a2e:0370:7334' AS valid_IPv6_string,
'2001:0db8:85a3::8a2e:370g:7334' AS invalid_IPv6_string,
'not_an_ipv6' AS malformed_string
SELECT
toIPv6OrDefault(valid_IPv6_string) AS valid,
toIPv6OrDefault(invalid_IPv6_string) AS default_value,
toIPv6OrDefault(malformed_string, toIPv6('::1')) AS provided_default;
```
```response title=Response theme={null}
┌─valid──────────────────────────────────┬─default_value─┬─provided_default─┐
│ 2001:db8:85a3::8a2e:370:7334 │ :: │ ::1 │
└────────────────────────────────────────┴───────────────┴──────────────────┘
```
## toIPv6OrNull
أُضيف في: v22.3.0
يحوّل قيمة الإدخال إلى قيمة من النوع `IPv6`، لكنه يعيد `NULL` عند حدوث خطأ.
يشبه [`toIPv6`](#toIPv6)، لكنه يعيد `NULL` بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.
الوسائط المدعومة:
* التمثيلات النصية لعناوين IPv6 بالتدوين القياسي.
* التمثيلات النصية لعناوين IPv4 (تُحوَّل إلى IPv4-mapped IPv6).
* التمثيلات الثنائية لعناوين IPv6.
الوسائط غير المدعومة (تعيد `NULL`):
* تنسيقات عناوين IP غير الصالحة.
* عناوين IPv6 سيئة التكوين.
* القيم الخارجة عن النطاق.
* تدوين غير صالح.
**البنية**
```sql theme={null}
toIPv6OrNull(x)
```
**الوسيطات**
* `x` — تمثيل نصي لعنوان IPv6 أو IPv4. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد عنوان IPv6 عند النجاح، وإلا يُرجع `NULL`. [`IPv6`](/ar/reference/data-types/ipv6) أو [`NULL`](/ar/reference/syntax#null)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT
toIPv6OrNull('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
toIPv6OrNull('invalid::ip') AS invalid_ipv6
```
```response title=Response theme={null}
┌─valid_ipv6──────────────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ ᴺᵁᴸᴸ │
└─────────────────────────────────────┴──────────────┘
```
## toIPv6OrZero
أُضيف في: v23.1.0
يحوّل قيمة الإدخال إلى قيمة من النوع [IPv6](/ar/reference/data-types/ipv6)، لكنه يعيد عنوان IPv6 الصفري في حال حدوث خطأ.
وهو يشبه [`toIPv6`](#toIPv6)، لكنه يعيد عنوان IPv6 الصفري (`::`) بدلًا من رفع استثناء عند حدوث أخطاء في التحويل.
الوسيطات المدعومة:
* تمثيلات نصية لعناوين IPv6 بالتدوين القياسي.
* تمثيلات نصية لعناوين IPv4 (تُحوَّل إلى IPv4-mapped IPv6).
* تمثيلات ثنائية لعناوين IPv6.
الوسيطات غير المدعومة (تعيد عنوان IPv6 الصفري):
* تنسيقات عناوين IP غير صالحة.
* عناوين IPv6 غير صحيحة البنية.
* قيم خارج النطاق.
**الصيغة**
```sql theme={null}
toIPv6OrZero(x)
```
**الوسيطات**
* `x` — تمثيل نصي لعنوان IPv6 أو IPv4. [`String`](/ar/reference/data-types/string)
**القيمة المُعادة**
يعيد عنوان IPv6 عند النجاح، وإلا يعيد عنوان IPv6 صفريًا (`::`). [`IPv6`](/ar/reference/data-types/ipv6)
**أمثلة**
**مثال على الاستخدام**
```sql title=Query theme={null}
SELECT
toIPv6OrZero('2001:0db8:85a3:0000:0000:8a2e:0370:7334') AS valid_ipv6,
toIPv6OrZero('invalid::ip') AS invalid_ipv6
```
```response title=Response theme={null}
┌─valid_ipv6──────────────────────────┬─invalid_ipv6─┐
│ 2001:db8:85a3::8a2e:370:7334 │ :: │
└─────────────────────────────────────┴──────────────┘
```