الدوال الأخرى | ClickHouse Docs

FQDN

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

تعيد اسم النطاق المؤهل بالكامل لخادم ClickHouse.

الصياغة

FQDN()

الأسماء المستعارة: fullHostName

الوسائط

لا شيء.

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

تعيد اسم النطاق المؤهل بالكامل لخادم ClickHouse. String

أمثلة

مثال على الاستخدام

SELECT fqdn()

┌─FQDN()────────────────────────┐
│ clickhouse.us-east-2.internal │
└───────────────────────────────┘

MACNumToString

استُحدث في: v1.1.0

يفسّر العدد UInt64 على أنه عنوان MAC بتنسيق big-endian. ويُرجع عنوان MAC المقابل بالتنسيق AA:BB:CC:DD:EE:FF (قيم مفصولة بنقطتين بالصيغة الست عشرية) كسلسلة نصية.

الصياغة

MACNumToString(num)

المعاملات

num — عدد من نوع UInt64. UInt64

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

يُرجع عنوان MAC بالتنسيق AA:BB:CC:DD:EE:FF. String

أمثلة

مثال على الاستخدام

SELECT MACNumToString(149809441867716) AS mac_address;

┌─mac_address───────┐
│ 88:40:3A:91:07:C4 │
└───────────────────┘

MACStringToNum

أُضيفت في: v1.1.0

الدالة العكسية لـ MACNumToString. إذا كان عنوان MAC بتنسيق غير صالح، فستُرجع 0.

الصياغة

MACStringToNum(s)

الوسائط

s — سلسلة نصية لعنوان MAC. String

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

يعيد عددًا من النوع UInt64. UInt64

أمثلة

مثال على الاستخدام

SELECT MACStringToNum('01:02:03:04:05:06') AS mac_numeric;

1108152157446

MACStringToOUI

أُضيف في: v1.1.0

إذا أُعطي عنوان MAC بالتنسيق AA:BB:CC:DD:EE:FF (أرقام مفصولة بنقطتين بالصيغة السداسية العشرية)، فإنه يعيد أول ثلاثة أوكتيتات على هيئة رقم UInt64. وإذا كان عنوان MAC بتنسيق غير صالح، فإنه يعيد 0.

بنية الجملة

MACStringToOUI(s)

الوسائط

s — عنوان MAC كسلسلة نصية. String

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

أول ثلاث ثمانيات على هيئة عدد من نوع UInt64. UInt64

أمثلة

مثال على الاستخدام

SELECT MACStringToOUI('00:50:56:12:34:56') AS oui;

authenticatedUser

أُضيفت في: v25.11.0

إذا جرى تبديل مستخدم الجلسة باستخدام الأمر EXECUTE AS، فستُرجع هذه الدالة اسم المستخدم الأصلي الذي استُخدم للمصادقة وإنشاء الجلسة. الاسم البديل: authUser()

الصياغة

authenticatedUser()

الأسماء البديلة: authUser

الوسائط

لا يوجد.

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

اسم المستخدم الذي تمت المصادقة عليه. String

أمثلة

مثال على الاستخدام

CREATE USER u1;
EXECUTE AS u1 SELECT currentUser(), authenticatedUser();
DROP USER u1;

┌─currentUser()─┬─authenticatedUser()─┐
│ u1            │ default             │
└───────────────┴─────────────────────┘

bar

استُحدث في: v1.1.0

ينشئ مخططًا شريطيًا. يرسم شريطًا بعرض يتناسب مع (x - min)، ويكون مساويًا لعدد المحارف في width عندما تكون x = max. يُرسَم الشريط بدقة تصل إلى ثُمن المحرف.

البنية

bar(x, min, max[, width])

الوسيطات

x — الحجم المطلوب عرضه. (U)Int* أو Float* أو Decimal
min — الحد الأدنى للقيمة. (U)Int* أو Float* أو Decimal
max — الحد الأقصى للقيمة. (U)Int* أو Float* أو Decimal
width — اختياري. عرض الشريط بالأحرف. القيمة الافتراضية هي 80. const (U)Int* أو const Float* أو const Decimal

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

تُرجع سلسلة تمثل شريطًا مرسومًا بأحرف Unicode. String

أمثلة

مثال على الاستخدام

CREATE TABLE hits (EventTime DateTime('UTC')) ENGINE = Memory;

-- One row per page view, spread over the hours of a day.
INSERT INTO hits
SELECT toDateTime('2026-01-01 00:00:00', 'UTC') + toIntervalHour(hour)
FROM (
    SELECT
        number AS hour,
        [293, 181, 115, 85, 69, 78, 113, 171, 278, 391, 458, 494, 510, 523, 540, 528, 539, 524, 506, 521, 522, 542, 494, 400][number + 1] AS count
    FROM numbers(24)
)
ARRAY JOIN range(count);

SELECT
toHour(EventTime) AS h,
count() AS c,
bar(c, 0, 600, 20) AS bar
FROM hits
GROUP BY h
ORDER BY h ASC

┌──h─┬───c─┬─bar────────────────┐
│  0 │ 293 │ █████████▊         │
│  1 │ 181 │ ██████             │
│  2 │ 115 │ ███▊               │
│  3 │  85 │ ██▊                │
│  4 │  69 │ ██▎                │
│  5 │  78 │ ██▌                │
│  6 │ 113 │ ███▊               │
│  7 │ 171 │ █████▋             │
│  8 │ 278 │ █████████▎         │
│  9 │ 391 │ █████████████      │
│ 10 │ 458 │ ███████████████▎   │
│ 11 │ 494 │ ████████████████▍  │
│ 12 │ 510 │ █████████████████  │
│ 13 │ 523 │ █████████████████▍ │
│ 14 │ 540 │ ██████████████████ │
│ 15 │ 528 │ █████████████████▌ │
│ 16 │ 539 │ █████████████████▉ │
│ 17 │ 524 │ █████████████████▍ │
│ 18 │ 506 │ ████████████████▊  │
│ 19 │ 521 │ █████████████████▎ │
│ 20 │ 522 │ █████████████████▍ │
│ 21 │ 542 │ ██████████████████ │
│ 22 │ 494 │ ████████████████▍  │
│ 23 │ 400 │ █████████████▎     │
└────┴─────┴────────────────────┘

blockNumber

أُضيف في: v1.1.0

يعيد رقمًا تسلسليًا يزداد باطراد لـالكتلة التي تحتوي على الصف. ويُحدَّث رقم الكتلة المُعاد قدر الإمكان، أي قد لا يكون دقيقًا تمامًا.

الصياغة

blockNumber()

الوسائط

لا شيء.

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

الرقم التسلسلي لكتلة البيانات التي يقع فيها الصف. UInt64

أمثلة

الاستخدام الأساسي

SELECT blockNumber()
FROM
(
    SELECT *
    FROM system.numbers
    LIMIT 10
) SETTINGS max_block_size = 2

┌─blockNumber()─┐
│             6 │
│             6 │
│             7 │
│             7 │
│             8 │
│             8 │
│             9 │
│             9 │
│            10 │
│            10 │
└───────────────┘

blockSerializedSize

أُضيف في: v20.3.0

يعيد الحجم غير المضغوط، بالبايت، لكتلة من القيم على القرص.

الصياغة

blockSerializedSize(x1[, x2[, ...]])

الوسائط

x1[, x2, ...] — أي عدد من القيم المطلوب الحصول على الحجم غير المضغوط للكتلة الخاصة بها. Any

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

يعيد عدد البايتات التي ستُكتب إلى القرص لكتلة من القيم من دون ضغط. UInt64

أمثلة

مثال على الاستخدام

SELECT blockSerializedSize(maxState(1)) AS x;

┌─x─┐
│ 2 │
└───┘

blockSize

أُضيفت في: v1.1.0

في ClickHouse، تُعالَج الاستعلامات على شكل كتل (chunks). تُرجِع هذه الدالة حجم الكتلة (عدد الصفوف) التي استُدعيت عليها.

الصياغة

blockSize()

الوسائط

لا يوجد.

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

يعيد عدد الصفوف في الكتلة الحالية. UInt64

أمثلة

مثال على الاستخدام

SELECT blockSize()
FROM system.numbers LIMIT 5

┌─blockSize()─┐
│           5 │
│           5 │
│           5 │
│           5 │
│           5 │
└─────────────┘

buildId

قُدِّمت في: v20.5.0

تُرجِع معرّف البناء الذي يُنشئه مصرّف للملف التنفيذي لخادم ClickHouse قيد التشغيل. إذا نُفِّذت في سياق جدول موزّع، فستُنشئ هذه الدالة عمودًا عاديًا بقيم مرتبطة بكل shard. وإلا فإنها تُنتج قيمة ثابتة.

الصياغة

buildId()

الوسائط

لا توجد.

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

يُرجع معرّف البناء. String

أمثلة

مثال على الاستخدام

SELECT buildId()

┌─buildId()────────────────────────────────┐
│ B49BA4BC500E5E850F832BEC918885516B22FC0E │
└──────────────────────────────────────────┘

byteSize

أُضيفت في: v21.1.0

تعيد تقديرًا لحجم البايت غير المضغوط لوسيطاتها في الذاكرة. بالنسبة إلى الوسيطات من النوع String، تعيد الدالة طول السلسلة + 8 (الطول). إذا كانت للدالة عدة وسيطات، فإنها تحسب مجموع أحجام البايت الخاصة بها.

البنية

byteSize(arg1[, arg2, ...])

الوسائط

arg1[, arg2, ...] — قيم من أي نوع بيانات يُراد تقدير حجمها بالبايت في صورتها غير المضغوطة. Any

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

تعيد تقديرًا لحجم الوسائط بالبايت في الذاكرة. UInt64

أمثلة

مثال على الاستخدام

SELECT byteSize('string')

┌─byteSize('string')─┐
│                 14 │
└────────────────────┘

وسائط متعددة

SELECT byteSize(NULL, 1, 0.3, '')

┌─byteSize(NULL, 1, 0.3, '')─┐
│                         18 │
└────────────────────────────┘

catboostEvaluate

أُضيف في: v22.9.0

قيِّم نموذج CatBoost خارجيًا. CatBoost مكتبة تعزيز تدرّجي مفتوحة المصدر طوّرتها Yandex للتعلّم الآلي. تقبل مسارًا إلى نموذج CatBoost ووسيطات النموذج (السمات).

المتطلبات المسبقة

ابنِ مكتبة تقييم CatBoost

قبل تقييم نماذج CatBoost، يجب إتاحة المكتبة libcatboostmodel.<so|dylib>. راجع توثيق CatBoost لمعرفة كيفية تجميعها.

بعد ذلك، حدِّد المسار إلى libcatboostmodel.<so|dylib> في تهيئة ClickHouse:

<clickhouse>
...
    <catboost_lib_path>/path/to/libcatboostmodel.so</catboost_lib_path>
...
</clickhouse>

لأسباب تتعلق بالأمان والعزل، لا يُجرى تقييم النموذج داخل عملية الخادم، بل داخل عملية clickhouse-library-bridge. عند أول تنفيذ للدالة catboostEvaluate()، يبدأ الخادم عملية جسر المكتبة إذا لم تكن قيد التشغيل بالفعل. وتتواصل العمليتان باستخدام واجهة HTTP. يُستخدم المنفذ 9012 افتراضيًا. ويمكن تحديد منفذ مختلف كما يلي - ويكون ذلك مفيدًا إذا كان المنفذ 9012 مخصّصًا بالفعل لخدمة مختلفة.

<library_bridge>
    <port>9019</port>
</library_bridge>

درّب نموذج CatBoost باستخدام libcatboost

راجع تدريب النماذج وتطبيقها لمعرفة كيفية تدريب نماذج CatBoost انطلاقًا من مجموعة بيانات تدريب.

يجب أن يكون ملف النموذج موجودًا داخل دليل user_files، كما هو الحال مع الدالة file.

الصياغة

catboostEvaluate(path_to_model, feature_1[, feature_2, ..., feature_n])

الوسائط

path_to_model — مسار إلى نموذج catboost، الموجود داخل الدليل user_files. const String
feature — سمة واحدة أو أكثر من سمات/وسائط النموذج. Float*

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

يعيد نتيجة تقييم النموذج. Float64

أمثلة

catboostEvaluate

SELECT catboostEvaluate('/var/lib/clickhouse/user_files/occupy.bin', Temperature, Humidity, Light, CO2, HumidityRatio) AS prediction FROM occupancy LIMIT 1

4.695691092573497

colorOKLABToSRGB

أُضيفت في: v26.2.0

تحوّل لونًا من فضاء الألوان الإدراكي OKLab إلى فضاء الألوان sRGB.

يُحدَّد لون الإدخال في فضاء الألوان OKLab. إذا كانت قيم الإدخال خارج نطاقات OKLab المعتادة، فتُحدَّد النتيجة وفقًا للتنفيذ.

يستخدم OKLab ثلاثة مكوّنات:

L: الإضاءة الإدراكية (عادةً في النطاق [0..1])
a: المحور التقابلي الأخضر-الأحمر
b: المحور التقابلي الأزرق-الأصفر

مكوّنا a و b غير محدودين نظريًا، لكنهما عمليًا يقعان بين -0.4 و 0.4. صُمّم OKLab ليكون موحّدًا إدراكيًا مع بقائه قليل الكلفة حسابيًا.

يُفترض أن يكون هذا التحويل معكوسًا لـ colorSRGBToOKLAB، ويتكوّن من المراحل التالية:

التحويل من OKLab إلى Linear sRGB.
التحويل من Linear sRGB إلى sRGB مُرمَّز بالغاما.

تحدّد وسيطة gamma الاختيارية الأس المستخدم عند التحويل من Linear sRGB إلى قيم RGB مُرمَّزة بالغاما. وإذا لم تُحدَّد، فتُستخدم قيمة gamma افتراضية لضمان الاتساق مع colorSRGBToOKLAB.

لمزيد من المعلومات حول فضاء الألوان OKLab وعلاقته بـ sRGB، راجع https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Values/color_value/oklab .

الصياغة

colorOKLABToSRGB(tuple [, gamma])

الوسائط

tuple — قيمة Tuple تتألف من ثلاث قيم رقمية هي L وa وb، حيث تقع L ضمن النطاق [0...1]. Tuple(Float64, Float64, Float64)
gamma — اختياري. الأسّ المستخدم لتحويل Linear sRGB مرة أخرى إلى sRGB عبر تطبيق (x ^ (1 / gamma)) * 255 على كل قناة x. القيمة الافتراضية هي 2.2. Float64

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

تعيد قيمة Tuple بالشكل (R, G, B) تمثل قيم ألوان sRGB. Tuple(Float64, Float64, Float64)

أمثلة

تحويل OKLAB إلى sRGB (Float)

SELECT colorOKLABToSRGB((0.4466, 0.0991, 0.44)) AS rgb;

┌─rgb──────────────────────┐
│ (198.07056923258935,0,0) │
└──────────────────────────┘

تحويل OKLAB إلى sRGB ‏(UInt8)

WITH colorOKLABToSRGB((0.7, 0.1, 0.54)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB───────┐
│ (255,0,0) │
└───────────┘

colorOKLCHToSRGB

أُضيف في: v25.7.0

يحوّل لونًا من فضاء الألوان الإدراكي OKLCH إلى فضاء الألوان sRGB المألوف.

إذا كانت L خارج النطاق [0...1]، أو كانت C سالبة، أو كانت H خارج النطاق [0...360]، فإن النتيجة تكون مُعرَّفة بحسب التنفيذ.

التحويل هو معكوس colorSRGBToOKLCH:

من OKLCH إلى OKLab.
من OKLab إلى Linear sRGB
من Linear sRGB إلى sRGB

تُستخدم الوسيطة الثانية gamma في المرحلة الأخيرة.

للاطلاع على أمثلة مرجعية للألوان في فضاء OKLCH، وكيفية توافقها مع ألوان sRGB، يُرجى مراجعة https://oklch.com/.

الصياغة

colorOKLCHToSRGB(tuple [, gamma])

الوسائط

tuple — قيمة من النوع Tuple تتألف من ثلاث قيم رقمية L وC وH، حيث تكون L ضمن النطاق [0...1]، وC >= 0، وH ضمن النطاق [0...360]. Tuple(Float64, Float64, Float64)
gamma — اختياري. الأسّ المستخدم لتحويل Linear sRGB إلى sRGB مرة أخرى، وذلك بتطبيق (x ^ (1 / gamma)) * 255 على كل قناة x. القيمة الافتراضية هي 2.2. Float64

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

تعيد قيمة من النوع Tuple ‏(R, G, B) تمثل قيم ألوان sRGB. Tuple(Float64, Float64, Float64)

أمثلة

تحويل OKLCH إلى sRGB

SELECT colorOKLCHToSRGB((0.6, 0.12, 40)) AS rgb;

┌─rgb───────────────────────────────────────────────────────┐
│ (186.02058688365264,100.68677189684993,71.67819977081575) │
└───────────────────────────────────────────────────────────┘

تحويل OKLCH إلى sRGB (UInt8)

WITH colorOKLCHToSRGB((0.6, 0.12, 40)) AS t
SELECT tuple(toUInt8(t.1), toUInt8(t.2), toUInt8(t.3)) AS RGB;

┌─RGB──────────┐
│ (186,100,71) │
└──────────────┘

colorSRGBToOKLAB

أُضيف في: v26.2.0

يحوّل لونًا مُرمَّزًا في فضاء الألوان sRGB إلى فضاء الألوان OKLAB المتجانس إدراكيًا.

إذا كانت أي قناة إدخال خارج [0...255] أو كانت قيمة gamma غير موجبة، فإن السلوك يعتمد على التنفيذ.

يتكوّن التحويل من مرحلتين:

sRGB إلى Linear sRGB
Linear sRGB إلى OKLab

الصياغة

colorSRGBToOKLAB(tuple[, gamma])

الوسائط

tuple — قيمة Tuple تتكوّن من ثلاث قيم: R وG وB ضمن النطاق [0...255]. Tuple(UInt8, UInt8, UInt8)
gamma — اختياري. الأسّ المستخدَم لجعل sRGB خطيًا عبر تطبيق (x / 255)^gamma على كل قناة x. القيمة الافتراضية هي 2.2. Float64

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

يعيد قيمة tuple ‏(L وa وb) تمثّل قيم فضاء الألوان OKLAB. Tuple(Float64, Float64, Float64)

أمثلة

تحويل sRGB إلى OKLAB

SELECT colorSRGBToOKLAB((128, 64, 32), 2.2) AS lab;

┌─lab──────────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.07266246769242975,0.07500108778529994) │
└──────────────────────────────────────────────────────────────┘

colorSRGBToOKLCH

أُضيف في: v25.7.0

يحوّل لونًا مُرمَّزًا في فضاء الألوان sRGB إلى فضاء الألوان OKLCH المتجانس إدراكيًا.

إذا كانت أي قناة إدخال خارج النطاق [0...255] أو كانت قيمة gamma غير موجبة، فإن السلوك يعتمد على التنفيذ.

يتكوّن التحويل من ثلاث مراحل:

من sRGB إلى Linear sRGB
من Linear sRGB إلى OKLab
من OKLab إلى OKLCH.

للاطلاع على مراجع الألوان في فضاء OKLCH وكيف تقابل ألوانَ sRGB، يُرجى مراجعة https://OKLCH.com/.

الصياغة

colorSRGBToOKLCH(tuple[, gamma])

الوسائط

tuple — قيمة من النوع Tuple تتكوّن من ثلاث قيم R وG وB ضمن النطاق [0...255]. Tuple(UInt8, UInt8, UInt8)
gamma — اختياري. الأسّ المُستخدم لتحويل sRGB إلى تمثيل خطي عبر تطبيق (x / 255)^gamma على كل قناة x. القيمة الافتراضية هي 2.2. Float64

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

تعيد قيمة ثلاثية (L, C, H) تمثّل قيم فضاء الألوان OKLCH. Tuple(Float64, Float64, Float64)

أمثلة

تحويل sRGB إلى OKLCH

SELECT colorSRGBToOKLCH((128, 64, 32), 2.2) AS lch;

┌─lch───────────────────────────────────────────────────────┐
│ (0.4436238384931984,0.1044269954567863,45.90734548193018) │
└───────────────────────────────────────────────────────────┘

connectionId

أُضيفت في: v21.3.0

تعيد معرّف الاتصال للعميل الذي أرسل الاستعلام الحالي. تكون هذه الدالة مفيدة بشكل خاص في سيناريوهات تصحيح الأخطاء. أُنشئت للتوافق مع الدالة CONNECTION_ID في MySQL. ولا تُستخدم عادةً في استعلامات الإنتاج.

البنية

connectionId()

المعاملات

لا يوجد.

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

يُرجِع معرّف اتصال العميل الحالي. UInt64

أمثلة

مثال على الاستخدام

SELECT connectionId();

┌─connectionId()─┐
│              0 │
└────────────────┘

countDigits

أُضيفت في: v20.8.0

تعيد عدد الخانات اللازمة لتمثيل قيمة بالصيغة العشرية.

البنية

countDigits(x)

المعاملات

x — قيمة صحيحة أو عشرية. (U)Int* أو Decimal

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

يُرجع عدد الخانات اللازمة لتمثيل x. UInt8

أمثلة

مثال للاستخدام

SELECT countDigits(toDecimal32(1, 9)), countDigits(toDecimal32(-1, 9)),
       countDigits(toDecimal64(1, 18)), countDigits(toDecimal64(-1, 18)),
       countDigits(toDecimal128(1, 38)), countDigits(toDecimal128(-1, 38));

┌─countDigits(toDecimal32(1, 9))─┬─countDigits(toDecimal32(-1, 9))─┬─countDigits(toDecimal64(1, 18))─┬─countDigits(toDecimal64(-1, 18))─┬─countDigits(toDecimal128(1, 38))─┬─countDigits(toDecimal128(-1, 38))─┐
│                             10 │                              10 │                              19 │                               19 │                               39 │                                39 │
└────────────────────────────────┴─────────────────────────────────┴─────────────────────────────────┴──────────────────────────────────┴──────────────────────────────────┴───────────────────────────────────┘

currentDatabase

أُضيف في: v1.1.0

يُرجع اسم قاعدة البيانات الحالية. ويفيد ذلك في معاملات محرك الجدول ضمن استعلامات CREATE TABLE عندما تحتاج إلى تحديد قاعدة البيانات.

راجع أيضًا عبارة SET.

الصياغة

currentDatabase()

الأسماء البديلة: current_database, DATABASE, SCHEMA

المعاملات

لا شيء.

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

يُرجع اسم قاعدة البيانات الحالية. String

أمثلة

مثال على الاستخدام

SELECT currentDatabase()

┌─currentDatabase()─┐
│ default           │
└───────────────────┘

صياغة SQL القياسية من دون أقواس

SELECT CURRENT_DATABASE

┌─CURRENT_DATABASE─┐
│ default          │
└──────────────────┘

currentHandler

أُضيف في: v26.6.0

يعيد اسم معالج HTTP المعرّف بلغة SQL (والمنشأ باستخدام CREATE HANDLER) الذي استدعى الاستعلام. يعيد سلسلة فارغة إذا لم يُستدعَ الاستعلام عبر معالج من هذا النوع.

يفيد في تخصيص سلوك الاستعلام بحسب المعالج الذي استدعاه.

الصياغة

currentHandler()

وسيطات الدالة

لا شيء.

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

تُرجع اسم المعالج الحالي. String

أمثلة

مثال على الاستخدام

SELECT currentHandler()

currentProfiles

قُدِّم في: v21.9.0

يعيد مصفوفة من ملفات تعريف الإعدادات الخاصة بالمستخدم الحالي.

الصياغة

currentProfiles()

الوسائط

لا توجد.

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

يعيد مصفوفة من ملفات تعريف الإعدادات للمستخدم الحالي. Array(String)

أمثلة

مثال على الاستخدام

SELECT currentProfiles();

┌─currentProfiles()─┐
│ ['default']       │
└───────────────────┘

currentQueryID

قُدِّم في: v25.2.0

يعيد معرّف الاستعلام الحالي.

البنية

currentQueryID()

الأسماء المستعارة: current_query_id

الوسائط

لا يوجد.

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

أمثلة

مثال

SELECT currentQueryID();

┌─currentQueryID()─────────────────────┐
│ 1280d0e8-1a08-4524-be6e-77975bb68e7d │
└──────────────────────────────────────┘

currentRequestURL

أُضيف في: v26.6.0

تعيد URL لطلب HTTP (المسار وسلسلة الاستعلام) الذي استدعى الاستعلام. تعيد سلسلة فارغة إذا لم يُستدعَ الاستعلام عبر HTTP.

تكون مفيدة، بالاقتران مع معالجات HTTP المعرّفة باستخدام SQL (CREATE HANDLER)، لاستخراج المعلمات المضمّنة في مسار الطلب.

الصياغة

currentRequestURL()

وسيطات الدالة

None.

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

تُرجع عنوان URL لطلب HTTP الحالي. String

أمثلة

مثال على الاستخدام

SELECT currentRequestURL()

currentRoles

أُضيفت في: v21.9.0

تُرجِع مصفوفة بالأدوار المُعيَّنة للمستخدم الحالي.

الصياغة

currentRoles()

المعاملات

لا يوجد.

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

تُرجع مصفوفة بالأدوار المُسندة إلى المستخدم الحالي. Array(String)

أمثلة

مثال على الاستخدام

SELECT currentRoles();

┌─currentRoles()─┐
│ []             │
└────────────────┘

currentSchemas

أُضيف في: v23.7.0

مماثلة للدالة currentDatabase، ولكنها

تقبل وسيطة من نوع Boolean يتم تجاهلها
تُرجع اسم قاعدة البيانات في مصفوفة تحتوي على قيمة واحدة.

الدالة currentSchemas موجودة فقط للتوافق مع PostgreSQL. يُرجى استخدام currentDatabase بدلًا منها.

انظر أيضًا إلى عبارة SET.

الصياغة

currentSchemas(bool)

الأسماء المستعارة: current_schemas

الوسائط

bool — قيمة منطقية يتم تجاهلها. Bool

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

تُرجِع مصفوفةً ذات عنصر واحد تحتوي على اسم قاعدة البيانات الحالية. Array(String)

أمثلة

مثال على الاستخدام

SELECT currentSchemas(true)

┌─currentSchemas(true)─┐
│ ['default']          │
└──────────────────────┘

currentUser

أُضيف في: v20.1.0

يعيد اسم المستخدم الحالي. في حال كان الاستعلام موزعًا، يُعاد اسم المستخدم الذي بدأ الاستعلام.

البنية

currentUser()

الأسماء البديلة: session_user, current_user, user

الوسائط

لا شيء.

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

يعيد اسم المستخدم الحالي، أو اسم تسجيل الدخول للمستخدم الذي بدأ الاستعلام. String

أمثلة

مثال على الاستخدام

SELECT currentUser()

┌─currentUser()─┐
│ default       │
└───────────────┘

صيغة SQL القياسية من دون أقواس

SELECT CURRENT_USER

┌─CURRENT_USER─┐
│ default      │
└──────────────┘

defaultProfiles

أُضيف في: v21.9.0

يُرجع مصفوفة بأسماء ملفات تعريف الإعدادات الافتراضية للمستخدم الحالي.

الصياغة

defaultProfiles()

الوسيطات

لا شيء.

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

يعيد مصفوفة من أسماء ملفات تعريف الإعدادات الافتراضية للمستخدم الحالي. Array(String)

أمثلة

مثال على الاستخدام

SELECT defaultProfiles();

┌─defaultProfiles()─┐
│ ['default']       │
└───────────────────┘

defaultRoles

أُضيف في: v21.9.0

يُرجع مصفوفة من الأدوار الافتراضية للمستخدم الحالي.

الصياغة

defaultRoles()

الوسيطات

لا توجد.

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

تعيد مصفوفة من الأدوار الافتراضية للمستخدم الحالي. Array(String)

أمثلة

مثال للاستخدام

SELECT defaultRoles();

┌─defaultRoles()─┐
│ []             │
└────────────────┘

defaultValueOfArgumentType

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

يعيد القيمة الافتراضية لنوع بيانات معيّن. ولا يشمل القيم الافتراضية للأعمدة المخصّصة التي يعيّنها المستخدم.

الصيغة

defaultValueOfArgumentType(expression)

المعاملات

expression — قيمة من أي نوع، أو تعبير يُنتج قيمة من أي نوع. Any

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

تعيد 0 للأرقام، أو سلسلة نصية فارغة للسلاسل النصية، أو NULL للأنواع Nullable. UInt8 أو String أو NULL

أمثلة

مثال على الاستخدام

SELECT defaultValueOfArgumentType(CAST(1 AS Int8));

┌─defaultValueOfArgumentType(CAST(1, 'Int8'))─┐
│                                           0 │
└─────────────────────────────────────────────┘

مثال على Nullable

SELECT defaultValueOfArgumentType(CAST(1 AS Nullable(Int8)));

┌─defaultValueOfArgumentType(CAST(1, 'Nullable(Int8)'))─┐
│                                                  ᴺᵁᴸᴸ │
└───────────────────────────────────────────────────────┘

defaultValueOfTypeName

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

تعيد القيمة الافتراضية للنوع ذي الاسم المحدد.

البنية

defaultValueOfTypeName(type)

الوسيطات

type — سلسلة نصية تمثل اسم نوع. String

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

تُرجع القيمة الافتراضية لاسم النوع المحدد: 0 للأرقام، وسلسلة فارغة للسلاسل النصية، أو NULL في حالة Nullable UInt8 أو String أو NULL

أمثلة

مثال على الاستخدام

SELECT defaultValueOfTypeName('Int8');

┌─defaultValueOfTypeName('Int8')─┐
│                              0 │
└────────────────────────────────┘

مثال على Nullable

SELECT defaultValueOfTypeName('Nullable(Int8)');

┌─defaultValueOfTypeName('Nullable(Int8)')─┐
│                                     ᴺᵁᴸᴸ │
└──────────────────────────────────────────┘

digits

أُضيف في: v26.7.0

يعيد الأرقام من العدد n بدءًا من الفهرس المحدد offset. يبدأ العد من 1 وفقًا للمنطق التالي:

إذا كانت قيمة offset هي 0، فسيُطرَح استثناء، لأن offset يعتمد ترقيمًا يبدأ من 1.
إذا كانت قيمة offset سالبة، فيبدأ العد بمقدار offset أرقام من نهاية العدد بدلًا من بدايته.
إذا كانت قيمة offset أكبر من عدد الأرقام في n، فستُعاد القيمة 0.

يخضع الوسيط الاختياري length للمنطق التالي:

إذا كانت قيمة length موجبة، فهذا يعني عدد الأرقام المطلوب أخذها بدءًا من offset
إذا كانت قيمة length سالبة، فهذا يعني عدد الأرقام التي يجب استبعادها من يمين العدد

راجع أيضًا الدالة substring، التي تنفذ العملية المناظرة على السلاسل النصية.

الصياغة

digits(n, offset[, length])

المعاملات

n — العدد الذي ستُستخرج منه الأرقام. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64
offset — موضع بداية الأرقام في n. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64
length — اختياري. الطول الأقصى للأرقام. (U)Int8 or (U)Int16 or (U)Int32 or (U)Int64

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

الأرقام المحددة من n، والمفسَّرة على أنها UInt64. تُرجع 0 إذا كان النطاق المحدد فارغًا. لا تُحفَظ الأصفار البادئة. UInt64

أمثلة

إزاحة موجبة

SELECT digits(1234567890, 7)

الإزاحة والطول الموجبان

SELECT digits(1234567890, 7, 2)

تُحسب الإزاحة السالبة من اليمين

SELECT digits(1234567890, -3)

الطول السالب يستبعد الأرقام من اليمين

SELECT digits(1234567890, 3, -2)

الإزاحة التي تتجاوز النهاية تُرجِع 0

SELECT digits(1234567890, 11)

displayName

أُضيف في: v22.11.0

يعيد قيمة display_name من config، أو الاسم المؤهل بالكامل للنطاق (FQDN) الخاص بالخادم إذا لم يتم تعيينه.

البنية

displayName()

الوسيطات

لا شيء.

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

تُعيد قيمة display_name من config، أو FQDN الخاص بالخادم إذا لم تكن مُعيّنة. String

أمثلة

مثال استخدام

SELECT displayName();

┌─displayName()─┐
│ production    │
└───────────────┘

dumpColumnStructure

أُضيف في: v1.1.0

يعرض وصفًا تفصيليًا للبنية الداخلية لعمود ونوع بياناته.

الصياغة

dumpColumnStructure(x)

المعاملات

x — القيمة المطلوب الحصول على وصف لها. Any

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

يعيد وصفًا لبنية العمود المستخدمة لتمثيل هذه القيمة. String

أمثلة

مثال على الاستخدام

SELECT dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'));

┌─dumpColumnStructure(CAST('2018-01-01 01:02:03', 'DateTime'))─┐
│ DateTime, Const(size = 1, UInt32(size = 1))                  │
└──────────────────────────────────────────────────────────────┘

enabledProfiles

أُضيف في: v21.9.0

يعيد مصفوفة من أسماء ملفات تعريف الإعدادات المُمكّنة للمستخدم الحالي.

البنية

enabledProfiles()

الوسائط

لا يوجد.

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

تُرجع مصفوفة بأسماء ملفات تعريف الإعدادات المُمكَّنة للمستخدم الحالي. Array(String)

أمثلة

مثال على الاستخدام

SELECT enabledProfiles();

┌─enabledProfiles()─┐
│ ['default']       │
└───────────────────┘

enabledRoles

أُضيفت في: v21.9.0

تعيد مصفوفة من الأدوار المُمكَّنة للمستخدم الحالي.

الصياغة

enabledRoles()

الوسيطات

لا شيء.

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

تُرجع مصفوفة بأسماء الأدوار المفعّلة للمستخدم الحالي. Array(String)

أمثلة

مثال على الاستخدام

SELECT enabledRoles();

┌─enabledRoles()─┐
│ []             │
└────────────────┘

errorCodeToName

أُضيف في: v20.12.0

يُرجع الاسم النصي لرمز خطأ رقمي في ClickHouse. يتوفر الربط بين رموز الخطأ الرقمية وأسماء الأخطاء هنا.

البنية

errorCodeToName(error_code)

الوسائط

error_code — رمز الخطأ في ClickHouse. (U)Int* أو Float* أو Decimal

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

يعيد الاسم النصي للرمز error_code. String

أمثلة

مثال على الاستخدام

SELECT errorCodeToName(252);

┌─errorCodeToName(252)─┐
│ TOO_MANY_PARTS       │
└──────────────────────┘

file

قُدِّم في: v21.3.0

يقرأ ملفًا على هيئة سلسلة نصية ويحمّل البيانات إلى العمود المحدد. لا يُفسَّر محتوى الملف.

راجع أيضًا دالة الجدول file.

البنية

file(path[, default])

الوسائط

path — مسار الملف بالنسبة إلى user_files_path. يدعم أحرف البدل *, **, ?, {abc,def} و {N..M}، حيث إن N وM عددان، و'abc' و'def' سلسلتان نصيتان. String
default — القيمة المُعادة إذا لم يكن الملف موجودًا أو تعذّر الوصول إليه. String أو NULL

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

يُرجع محتوى الملف على هيئة سلسلة نصية. String

أمثلة

إدراج ملفات في جدول

INSERT INTO FUNCTION file('a.txt', 'RawBLOB') SELECT 'Hello' SETTINGS engine_file_truncate_on_insert = 1;
INSERT INTO FUNCTION file('b.txt', 'RawBLOB') SELECT 'World!' SETTINGS engine_file_truncate_on_insert = 1;

CREATE TABLE data (a String, b String) ENGINE = Memory;
INSERT INTO data SELECT file('a.txt'), file('b.txt');

SELECT * FROM data;

┌─a─────┬─b──────┐
│ Hello │ World! │
└───────┴────────┘

filesystemAvailable

أُضيف في: v20.1.0

يعيد مقدار المساحة الحرة في نظام الملفات الذي يستضيف التخزين الدائم لقاعدة البيانات. تكون القيمة المعادة دائمًا أقل من إجمالي المساحة الحرة (filesystemUnreserved) لأن بعض المساحة تكون محجوزة لنظام التشغيل.

الصياغة

filesystemAvailable([disk_name])

الوسائط

disk_name — اختياري. اسم القرص المراد معرفة مقدار المساحة الحرة فيه. إذا لم يُحدَّد، فسيُستخدم القرص default. String أو FixedString

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

تعيد مقدار المساحة المتبقية المتاحة بالبايت. UInt64

أمثلة

مثال على الاستخدام

SELECT formatReadableSize(filesystemAvailable()) AS "Available space";

┌─Available space─┐
│ 30.75 GiB       │
└─────────────────┘

filesystemCapacity

أُضيفت في: v20.1.0

تعيد سعة نظام الملفات بالبايت. يتطلب ذلك تهيئة المسار الخاص بدليل البيانات.

الصياغة

filesystemCapacity([disk_name])

الوسائط

disk_name — اختياري. اسم القرص المطلوب الحصول على سعته. إذا لم يتم تحديده، فسيُستخدم القرص default. String أو FixedString

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

تعيد سعة نظام الملفات بالبايت. UInt64

أمثلة

مثال على الاستخدام

SELECT formatReadableSize(filesystemCapacity()) AS "Capacity";

┌─Capacity──┐
│ 39.32 GiB │
└───────────┘

filesystemUnreserved

قُدِّمت في: v22.12.0

تعيد إجمالي المساحة الحرة على نظام الملفات الذي يستضيف التخزين الدائم لقاعدة البيانات (وكان يُسمى سابقًا filesystemFree). انظر أيضًا filesystemAvailable.

الصياغة

filesystemUnreserved([disk_name])

الوسيطات

disk_name — اختياري. اسم القرص المطلوب معرفة إجمالي المساحة الحرة فيه. إذا لم يتم تحديده، فسيُستخدم القرص default. String أو FixedString

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

يعيد مقدار المساحة الحرة بالبايت. UInt64

أمثلة

مثال على الاستخدام

SELECT formatReadableSize(filesystemUnreserved()) AS "Free space";

┌─Free space─┐
│ 32.39 GiB  │
└────────────┘

finalizeAggregation

قُدِّمت في: v1.1.0

عند تمرير حالة تجميع، تُرجِع هذه الدالة نتيجة التجميع (أو الحالة المُنهية عند استخدام المُركِّب -State).

الصياغة

finalizeAggregation(state)

الوسائط

state — حالة التجميع. AggregateFunction

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

يعيد النتيجة النهائية للتجميع. Any

أمثلة

مثال على الاستخدام

SELECT finalizeAggregation(arrayReduce('maxState', [1, 2, 3]));

┌─finalizeAggregation(arrayReduce('maxState', [1, 2, 3]))─┐
│                                                       3 │
└─────────────────────────────────────────────────────────┘

بالاقتران مع initializeAggregation

SET allow_deprecated_error_prone_window_functions = 1;
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

flipCoordinates

أُضيفت في: v25.11.0

تبدّل هذه الدالة الإحداثيين x وy في الكائنات الهندسية. تؤدي هذه العملية إلى تبديل خط العرض وخط الطول، وهو ما يفيد عند التحويل بين أنظمة إحداثيات مختلفة أو تصحيح ترتيب الإحداثيات.

بالنسبة إلى Point، فهي تبدّل الإحداثيين x وy. وبالنسبة إلى الأشكال الهندسية الأكثر تعقيدًا (MultiPoint وLineString وPolygon وMultiPolygon وRing وMultiLineString)، فإنها تطبّق هذا التحويل تكراريًا على كل زوج من الإحداثيات.

تدعم الدالة كلاً من الأنواع الهندسية الفردية (Point وMultiPoint وRing وPolygon وMultiPolygon وLineString وMultiLineString) ونوع Geometry المتغاير.

الصياغة

flipCoordinates(geometry)

الوسائط

geometry — العنصر الهندسي المراد تحويله. الأنواع المدعومة: Point (Tuple(Float64, Float64))، وMultiPoint (Array(Point))، وRing (Array(Point))، وPolygon (Array(Ring))، وMultiPolygon (Array(Polygon))، وLineString (Array(Point))، وMultiLineString (Array(LineString))، أو Geometry (نوع Variant يحتوي على أي من هذه الأنواع).

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

العنصر الهندسي بإحداثيات معكوسة. نوع الإرجاع يطابق نوع الإدخال. Point أو MultiPoint أو Ring أو Polygon أو MultiPolygon أو LineString أو MultiLineString أو Geometry

أمثلة

basic_point

SELECT flipCoordinates((1.0, 2.0));

(2,1)

حلقة

SELECT flipCoordinates([(1.0, 2.0), (3.0, 4.0)]);

[(2,1),(4,3)]

polygon

SELECT flipCoordinates([[(1.0, 2.0), (3.0, 4.0)], [(5.0, 6.0), (7.0, 8.0)]]);

[[(2,1),(4,3)],[(6,5),(8,7)]]

geometry_wkt

SELECT flipCoordinates(readWkt('POINT(10 20)'));

(20,10)

geometry_polygon_wkt

SELECT flipCoordinates(readWkt('POLYGON((0 0, 5 0, 5 5, 0 5, 0 0))'));

[[(0,0),(0,5),(5,5),(5,0),(0,0)]]

formatQuery

استُحدثت في: v23.10.0

تعيد نسخة منسّقة من استعلام SQL المُعطى، وقد تكون متعددة الأسطر. وتُطلق استثناءً عند حدوث خطأ في التحليل. [example:multiline]

الصيغة

formatQuery(query)

الوسائط

query — استعلام SQL المراد تنسيقه. String

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

الاستعلام المنسّق String

أمثلة

متعدد الأسطر

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

formatQueryFromJSON

متاحة منذ: v26.8.0

تأخذ تمثيل JSON لبنية AST الخاصة باستعلام SQL (كما ينتجه parseQueryToJSON) وتُنسّقه مجددًا كسلسلة استعلام SQL.

باستخدام وسيطة واحدة، تُنتج استعلام SQL بتنسيق معياري. وباستخدام وسيطتين (json, original_query)، تحافظ، قدر الإمكان، على التعليقات والمسافات البيضاء والإزاحة من الاستعلام الأصلي.

تخضع بنية AST المفككة تسلسليًا لإعدادَي max_ast_depth وmax_ast_elements للجلسة الحالية. وبالاقتران مع parseQueryToJSON، تتيح هذه الدالة فحص الاستعلامات وتحويلها برمجيًا عبر تمثيل AST بتنسيق JSON.

الصياغة

formatQueryFromJSON(json[, original_query])

الوسائط

json — سلسلة JSON تمثل شجرة AST لاستعلام SQL. String
original_query — اختياري. استعلام SQL الأصلي للحفاظ على تنسيقه. String

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

سلسلة نصية لاستعلام SQL. String

أمثلة

تحويل ذهابًا وإيابًا

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a, b FROM t WHERE x > 1'))─┐
│ SELECT a, b FROM t WHERE x > 1                                          │
└─────────────────────────────────────────────────────────────────────────┘

الحفاظ على التنسيق

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t');

┌─formatQueryFromJSON(parseQueryToJSON('SELECT a FROM t'), 'SELECT /* comment */ a FROM t')─┐
│ SELECT /* comment */ a FROM t                                                             │
└───────────────────────────────────────────────────────────────────────────────────────────┘

formatQueryOrNull

أُضيفت في: v23.11.0

تعيد إصدارًا منسقًا، وقد يمتد على عدة أسطر، من استعلام SQL المحدد. وتعيد NULL عند حدوث خطأ في التحليل. [example:multiline]

البنية

formatQueryOrNull(query)

الوسائط

query — استعلام SQL المراد تنسيقه. String

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

الاستعلام المنسَّق من النوع String

أمثلة

متعدد الأسطر

SELECT formatQuery('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT\n    a,\n    b\nFROM tab\nWHERE (a > 3) AND (b < 3)

formatQuerySingleLine

أُضيف في: v23.10.0

مشابه لـ formatQuery()، لكن السلسلة المنسّقة المُعادة لا تحتوي على فواصل أسطر. ويُظهر خطأً عند حدوث خطأ في التحليل. [example:multiline]

الصياغة

formatQuerySingleLine(query)

الوسائط

query — استعلام SQL المطلوب تنسيقه. String

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

الاستعلام المنسّق String

أمثلة

متعدد الأسطر

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatQuerySingleLineOrNull

أُضيف في: v23.11.0

مثل formatQuery()، ولكن السلسلة المنسّقة المُعادة لا تحتوي على فواصل أسطر. ويُرجع NULL في حالة حدوث خطأ في التحليل. [example:multiline]

الصيغة

formatQuerySingleLineOrNull(query)

الوسائط

query — استعلام SQL المطلوب تنسيقه. String

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

الاستعلام المنسَّق String

أمثلة

متعدد الأسطر

SELECT formatQuerySingleLine('select a,    b FRom tab WHERE a > 3 and  b < 3');

SELECT a, b FROM tab WHERE (a > 3) AND (b < 3)

formatReadableDecimalSize

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

عند إعطائها حجمًا معيّنًا (عددًا من البايتات)، تُرجِع هذه الدالة حجمًا مقروءًا ومقرّبًا مع لاحقة (KB وMB وما إلى ذلك) على هيئة سلسلة نصية.

العمليات العكسية لهذه الدالة هي parseReadableSize.

الصياغة

formatReadableDecimalSize(value[, precision])

المعاملات

value — الحجم بالبايت. Int8 أو Int16 أو Int32 أو Int64 أو UInt8 أو UInt16 أو UInt32 أو UInt64 أو Float32 أو Float64 أو Decimal
precision — اختياري. عدد الخانات بعد الفاصلة العشرية. القيمة الافتراضية هي 2. const UInt8

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

تعيد حجمًا مقروءًا ومقربًا مع لاحقة، كسلسلة نصية. String

أمثلة

تنسيق أحجام الملفات

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableDecimalSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize──┐
│              1 │ 1.00 B    │
│           1024 │ 1.02 KB   │
│        1048576 │ 1.05 MB   │
│      192851925 │ 192.85 MB │
└────────────────┴───────────┘

مع تحديد الدقة بشكل صريح

SELECT
    formatReadableDecimalSize(192851925, 0) AS no_decimals,
    formatReadableDecimalSize(192851925, 4) AS four_decimals

┌─no_decimals─┬─four_decimals─┐
│ 193 MB      │ 192.8519 MB   │
└─────────────┴───────────────┘

formatReadableQuantity

أُضيفت في: v20.10.0

عند إعطائها رقمًا، تُرجِع هذه الدالة رقمًا مُقرَّبًا مع لاحقة (ألف، مليون، مليار، إلخ) في صورة سلسلة نصية.

تقبل هذه الدالة أي نوع رقمي كمدخل، لكنها تحوّله داخليًا إلى Float64. قد لا تكون النتائج مثالية مع القيم الكبيرة.

البنية

formatReadableQuantity(value[, precision])

الوسيطات

value — رقم مطلوب تنسيقه. Int8 أو Int16 أو Int32 أو Int64 أو UInt8 أو UInt16 أو UInt32 أو UInt64 أو Float32 أو Float64 أو Decimal
precision — اختياري. عدد الخانات بعد الفاصلة العشرية. القيمة الافتراضية هي 2. const UInt8

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

تُرجع رقمًا مُقرَّبًا مع لاحقة، على هيئة سلسلة نصية. String

أمثلة

تنسيق الأرقام باستخدام لواحق

SELECT
    arrayJoin([1024, 1234 * 1000, (4567 * 1000) * 1000, 98765432101234]) AS number,
    formatReadableQuantity(number) AS number_for_humans

┌─────────number─┬─number_for_humans─┐
│           1024 │ 1.02 thousand     │
│        1234000 │ 1.23 million      │
│     4567000000 │ 4.57 billion      │
│ 98765432101234 │ 98.77 trillion    │
└────────────────┴───────────────────┘

مع دقة محددة بوضوح

SELECT
    formatReadableQuantity(98765432101234, 0) AS no_decimals,
    formatReadableQuantity(98765432101234, 4) AS four_decimals

┌─no_decimals─┬─four_decimals────┐
│ 99 trillion │ 98.7654 trillion │
└─────────────┴──────────────────┘

formatReadableSize

أُضيفت في: v1.1.0

عند إعطائها حجمًا (عددًا من البايتات)، تُرجع هذه الدالة حجمًا مقروءًا ومقربًا مع لاحقة (KiB، MiB، إلخ) على هيئة سلسلة نصية.

العمليات العكسية لهذه الدالة هي parseReadableSize، وparseReadableSizeOrZero، وparseReadableSizeOrNull. تقبل هذه الدالة أي نوع رقمي كمدخل، لكنها تحوّله داخليًا إلى Float64. قد لا تكون النتائج مثالية مع القيم الكبيرة.

الصيغة

formatReadableSize(value[, precision])

الأسماء البديلة: FORMAT_BYTES

الوسيطات

value — الحجم بالبايت. Int8 أو Int16 أو Int32 أو Int64 أو UInt8 أو UInt16 أو UInt32 أو UInt64 أو Float32 أو Float64 أو Decimal
precision — اختياري. عدد الخانات بعد الفاصلة العشرية. القيمة الافتراضية هي 2. const UInt8

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

يعيد حجمًا مقروءًا ومقرّبًا مع لاحقة، على هيئة سلسلة نصية. String

أمثلة

تنسيق أحجام الملفات

SELECT
    arrayJoin([1, 1024, 1024*1024, 192851925]) AS filesize_bytes,
    formatReadableSize(filesize_bytes) AS filesize

┌─filesize_bytes─┬─filesize───┐
│              1 │ 1.00 B     │
│           1024 │ 1.00 KiB   │
│        1048576 │ 1.00 MiB   │
│      192851925 │ 183.92 MiB │
└────────────────┴────────────┘

مع تحديد الدقة صراحةً

SELECT
    formatReadableSize(192851925, 0) AS no_decimals,
    formatReadableSize(192851925, 4) AS four_decimals

┌─no_decimals─┬─four_decimals─┐
│ 184 MiB     │ 183.9179 MiB  │
└─────────────┴───────────────┘

formatReadableTimeDelta

أُضيفت في: v20.12.0

إذا أُعطيت هذه الدالة فترةً زمنية (delta) بالثواني أو تعبيرًا من نوع INTERVAL، فإنها تُرجع فرقًا زمنيًا كسلسلة نصية بصيغة year/month/day/hour/minute/second/millisecond/microsecond/nanosecond.

تقبل هذه الدالة أي نوع رقمي كمدخل، لكنها تحوّله داخليًا إلى Float64. وقد لا تكون النتائج مثالية مع القيم الكبيرة.

عند تمرير تعبير من نوع INTERVAL، تُحوَّل قيمته إلى ثوانٍ. ولا تكون وحدات interval من MONTH فما فوق (MONTH, QUARTER, YEAR) مدعومة، لأنها لا تمثل فترةً ثابتة المقدار بالثواني.

الصياغة

formatReadableTimeDelta(column[, maximum_unit, minimum_unit])

الوسيطات

column — عمود يحتوي على فرق زمني رقمي، أو تعبير INTERVAL. وحدات INTERVAL من MONTH فما فوق غير مدعومة. Float64 أو Interval
maximum_unit — اختياري. أكبر وحدة تُعرض. القيم المقبولة: nanoseconds، microseconds، milliseconds، seconds، minutes، hours، days، months، years. القيمة الافتراضية: years. const String
minimum_unit — اختياري. أصغر وحدة تُعرض. تُحذف جميع الوحدات الأصغر. القيم المقبولة: nanoseconds، microseconds، milliseconds، seconds، minutes، hours، days، months، years. إذا كانت القيمة المحددة صراحةً أكبر من maximum_unit، فسيُطلق استثناء. القيمة الافتراضية: seconds إذا كان maximum_unit يساوي seconds أو أكبر، وإلا nanoseconds. const String

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

تعيد فرقًا زمنيًا على هيئة سلسلة نصية. String

أمثلة

مثال على الاستخدام

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed) AS time_delta

┌───elapsed─┬─time_delta──────────────────────────────────────────────────────┐
│       100 │ 1 minute and 40 seconds                                         │
│     12345 │ 3 hours, 25 minutes and 45 seconds                              │
│ 432546534 │ 13 years, 8 months, 17 days, 7 hours, 48 minutes and 54 seconds │
└───────────┴─────────────────────────────────────────────────────────────────┘

مع تحديد أكبر وحدة

SELECT
    arrayJoin([100, 12345, 432546534]) AS elapsed,
    formatReadableTimeDelta(elapsed, 'minutes') AS time_delta

┌───elapsed─┬─time_delta─────────────────────┐
│       100 │ 1 minute and 40 seconds        │
│     12345 │ 205 minutes and 45 seconds     │
│ 432546534 │ 7209108 minutes and 54 seconds │
└───────────┴────────────────────────────────┘

باستخدام تعبير INTERVAL

SELECT formatReadableTimeDelta(INTERVAL 12345 SECOND) AS time_delta

┌─time_delta─────────────────────────┐
│ 3 hours, 25 minutes and 45 seconds │
└────────────────────────────────────┘

fuzzQuery

أُضيفت في: v26.2.0

تُحلِّل سلسلة الاستعلام المعطاة وتُطبِّق عليها طفرات عشوائية على AST (التشويش). وتُرجِع الاستعلام الناتج عن التشويش كسلسلة نصية. غير حتمي: قد يُنتِج كل استدعاء نتيجة مختلفة. وتتطلب allow_fuzz_query_functions = 1.

الصيغة

fuzzQuery(query)

المعاملات

query — استعلام SQL المراد إخضاعه للاختبار العشوائي. String

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

سلسلة الاستعلام بعد إخضاعها للاختبار العشوائي String

أمثلة

بسيط

SET allow_fuzz_query_functions = 1; SELECT fuzzQuery('SELECT 1');

generateRandomStructure

أُضيف في: v23.5.0

يولّد بنية جدول عشوائية بالتنسيق column1_name column1_type, column2_name column2_type, ....

الصياغة

generateRandomStructure([number_of_columns, seed])

الوسيطات

number_of_columns — العدد المطلوب من الأعمدة في بنية الجدول الناتجة. إذا ضُبطت القيمة على 0 أو Null، فسيكون عدد الأعمدة عشوائيًا بين 1 و128. القيمة الافتراضية: Null. UInt64
seed — بذرة عشوائية لإنتاج نتائج ثابتة. إذا لم يتم تحديد seed أو ضُبطت قيمته على Null، فسيتم توليدها عشوائيًا. UInt64

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

بنية جدول مُولَّدة عشوائيًا. String

أمثلة

مثال على الاستخدام

SELECT generateRandomStructure()

c1 Decimal32(5), c2 Date, c3 Tuple(LowCardinality(String), Int128, UInt64, UInt16, UInt8, IPv6), c4 Array(UInt128), c5 UInt32, c6 IPv4, c7 Decimal256(64), c8 Decimal128(3), c9 UInt256, c10 UInt64, c11 DateTime

بعدد أعمدة محدد

SELECT generateRandomStructure(1)

c1 Map(UInt256, UInt16)

باستخدام قيمة ابتدائية محددة

SELECT generateRandomStructure(NULL, 33)

c1 DateTime, c2 Enum8(\'c2V0\' = -123, \'c2V1\' = 94, \'c2V2\' = -105, \'c2V3\' = 67), c3 Nullable(UInt8), c4 String, c5 Nested(e1 IPv4, e2 UInt8, e3 UInt16, e4 UInt16, e5 Int32, e6 Map(Date, Decimal256(71))), c6 UInt32, c7 Bool, c8 Float64

generateSerialID

أُضيفت في: v25.1.0

تُولِّد هذه الدالة أرقامًا تسلسلية وتُعيدها بدءًا من قيمة العداد السابقة. تأخذ هذه الدالة وسيطًا نصيًا — معرّف السلسلة — وقيمة بدء اختيارية. يجب تهيئة الخادم لاستخدام Keeper. تُخزَّن السلاسل في عُقد Keeper تحت المسار، الذي يمكن تهيئته في series_keeper_path ضمن تهيئة الخادم.

البنية

generateSerialID(series_identifier[, start_value])

الوسيطات

series_identifier — معرّف السلسلة const String
start_value — اختياري. قيمة بداية العداد. القيمة الافتراضية هي 0. ملاحظة: لا تُستخدم هذه القيمة إلا عند إنشاء سلسلة جديدة، ويجري تجاهلها إذا كانت السلسلة موجودة بالفعل UInt*

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

يعيد أرقامًا متسلسلة تبدأ من قيمة العداد السابقة. UInt64

أمثلة

الاستدعاء الأول

SELECT generateSerialID('id1')

┌─generateSerialID('id1')─┐
│                       0 │
└─────────────────────────┘

الاستدعاء الثاني

SELECT generateSerialID('id1')

┌─generateSerialID('id1')─┐
│                       1 │
└─────────────────────────┘

استدعاء العمود

CREATE TABLE test_table (CounterID UInt32, UserID UInt32, ver UInt32) ENGINE = Memory;
INSERT INTO test_table VALUES (1, 3, 3), (1, 1, 1), (1, 2, 2), (1, 5, 5), (1, 4, 4);

SELECT *, generateSerialID('id1') FROM test_table

┌─CounterID─┬─UserID─┬─ver─┬─generateSerialID('id1')─┐
│         1 │      3 │   3 │                       2 │
│         1 │      1 │   1 │                       3 │
│         1 │      2 │   2 │                       4 │
│         1 │      5 │   5 │                       5 │
│         1 │      4 │   4 │                       6 │
└───────────┴────────┴─────┴─────────────────────────┘

مع قيمة ابتدائية

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)─┐
│                          100 │
└──────────────────────────────┘

مع قيمة البداية في الاستدعاء الثاني

SELECT generateSerialID('id2', 100)

┌─generateSerialID('id2', 100)─┐
│                          101 │
└──────────────────────────────┘

getClientHTTPHeader

أُضيفت في: v24.5.0

تجلب قيمة ترويسة HTTP. إذا لم تكن هذه الترويسة موجودة، أو إذا لم يُنفَّذ الطلب الحالي عبر واجهة HTTP، فستُرجِع الدالة سلسلة فارغة. تخضع بعض ترويسات HTTP (مثل Authorization وAuthentication وX-ClickHouse-*) لقيود.

ترويسات HTTP غير حساسة لحالة الأحرف وفقًا للوثيقة RFC 9110. إذا استُخدمت الدالة في سياق استعلام موزّع، فإنها لا تُرجِع قيمة غير فارغة إلا على العقدة المُبادِرة.

يقرأ getClientHTTPHeader ترويسات الطلب الحالي، لذلك لا يُرجِع قيمة غير فارغة إلا عندما يُرسَل الاستعلام عبر واجهة HTTP. على سبيل المثال، مرّر الترويسة مع الطلب ثم اقرأها مجددًا عبر HTTP:

echo "SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1" | \
    curl 'http://localhost:8123/' --data-binary @- -H 'Content-Type: application/x-www-form-urlencoded'

يعيد الأمر أعلاه application/x-www-form-urlencoded.

البنية

getClientHTTPHeader(name)

الوسيطات

name — اسم ترويسة HTTP. String

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

تعرض قيمة الترويسة. String

أمثلة

مثال على الاستخدام

-- Over a non-HTTP interface (such as `clickhouse-client` or `clickhouse-local`) there are
-- no request headers, so the function returns an empty string. See the description above
-- for an HTTP example that returns the actual header value.
SELECT getClientHTTPHeader('Content-Type') SETTINGS allow_get_client_http_header = 1

getMacro

أُضيف في: v20.1.0

يعيد قيمة ماكرو من ملف تهيئة الخادم. تُعرَّف وحدات الماكرو في قسم <macros> من ملف التهيئة، ويمكن استخدامها لتمييز الخوادم بأسماء مناسبة حتى لو كانت أسماء المضيفين الخاصة بها معقدة. إذا نُفِّذت الدالة في سياق جدول موزّع، فإنها تُنشئ عمودًا عاديًا بقيم مرتبطة بكل shard.

البنية

getMacro(name)

الوسيطات

name — اسم الماكرو المطلوب استرجاعه. const String

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

تُرجِع قيمة الماكرو المحدد. String

أمثلة

الاستخدام الأساسي

SELECT getMacro('test');

┌─getMacro('test')─┐
│ Value            │
└──────────────────┘

getMaxTableNameLengthForDatabase

أُضيف في: v25.1.0

يعيد الحد الأقصى لطول اسم الجدول في قاعدة بيانات محددة.

البنية

getMaxTableNameLengthForDatabase(database_name)

الوسيطات

database_name — اسم قاعدة البيانات المحددة. String

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

تعيد الحد الأقصى لطول اسم الجدول، وهو عدد صحيح

أمثلة

اعتيادي

SELECT getMaxTableNameLengthForDatabase('default');

┌─getMaxTableNameLengthForDatabase('default')─┐
│                                         206 │
└─────────────────────────────────────────────┘

getMergeTreeSetting

أُضيفت في: v25.6.0

تُرجع القيمة الحالية لأحد إعدادات MergeTree.

البنية

getMergeTreeSetting(setting_name)

الوسيطات

setting_name — اسم الإعداد. String

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

تُرجع القيمة الحالية لإعداد MergeTree.

أمثلة

مثال على الاستخدام

SELECT getMergeTreeSetting('index_granularity');

┌─getMergeTreeSetting('index_granularity')─┐
│                                     8192 │
└──────────────────────────────────────────┘

getOSKernelVersion

أُضيفت في: v21.11.0

تُرجع سلسلة نصية تحتوي على إصدار نواة نظام التشغيل.

البنية

getOSKernelVersion()

الوسيطات

لا شيء.

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

تعيد إصدار نواة نظام التشغيل الحالي. String

أمثلة

مثال على الاستخدام

SELECT getOSKernelVersion();

┌─getOSKernelVersion()────┐
│ Linux 4.15.0-55-generic │
└─────────────────────────┘

getServerPort

أُضيف في: v21.10.0

يعيد رقم منفذ الخادم للبروتوكول المحدد.

البنية

getServerPort(port_name)

الوسيطات

port_name — اسم المنفذ. String

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

تعيد رقم منفذ الخادم. UInt16

أمثلة

مثال للاستخدام

SELECT getServerPort('tcp_port');

┌─getServerPort('tcp_port')─┐
│                      9000 │
└───────────────────────────┘

getServerSetting

أُضيف في: v25.6.0

يعيد القيمة المعينة حاليًا عند تزويده باسم إعداد الخادم.

البنية

getServerSetting(setting_name')

الوسيطات

setting_name — اسم إعداد الخادم. String

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

تُرجع القيمة الحالية لإعداد الخادم. Any

أمثلة

مثال على الاستخدام

SELECT getServerSetting('allow_use_jemalloc_memory');

┌─getServerSetting('allow_use_jemalloc_memory')─┐
│ true                                          │
└───────────────────────────────────────────────┘

getSetting

أُضيف في: v20.7.0

يُرجع القيمة الحالية للإعداد.

البنية

getSetting(setting_name)

الوسيطات

setting_Name — اسم الإعداد. const String

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

تُرجع القيمة الحالية للإعداد. Any

أمثلة

مثال على الاستخدام

SELECT getSetting('enable_analyzer');
SET enable_analyzer = false;
SELECT getSetting('enable_analyzer');

┌─getSetting('enable_analyzer')─┐
│ true                          │
└───────────────────────────────┘
┌─getSetting('enable_analyzer')─┐
│ false                         │
└───────────────────────────────┘

getSettingOrDefault

أُضيف في: v24.10.0

تعيد القيمة الحالية لإعداد ما، أو تعيد القيمة الافتراضية المحددة في الوسيطة الثانية إذا لم يكن الإعداد معيّنًا في الملف الشخصي الحالي.

البنية

getSettingOrDefault(setting_name, default_value)

الوسيطات

setting_name — اسم الإعداد. String
default_value — القيمة التي ستُعاد إذا لم يتم تعيين custom_setting. ويمكن أن تكون هذه القيمة من أي نوع بيانات أو Null.

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

تُعيد القيمة الحالية للإعداد المحدد، أو default_value إذا لم يتم تعيين الإعداد.

أمثلة

مثال على الاستخدام

SELECT getSettingOrDefault('custom_undef1', 'my_value');
SELECT getSettingOrDefault('custom_undef2', 100);
SELECT getSettingOrDefault('custom_undef3', NULL);

my_value
100
\N

getSizeOfEnumType

أُضيف في: v1.1.0

يعيد عدد الحقول في Enum المعطى.

البنية

getSizeOfEnumType(x)

المعاملات

x — قيمة من النوع Enum. Enum

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

يُرجع عدد الحقول ذات قيم الإدخال من النوع Enum. UInt8/16

أمثلة

مثال على الاستخدام

SELECT getSizeOfEnumType(CAST('a' AS Enum8('a' = 1, 'b' = 2))) AS x;

┌─x─┐
│ 2 │
└───┘

getSubcolumn

أُضيف في: v23.3.0

يستقبل تعبيرًا أو معرّفًا، بالإضافة إلى سلسلة نصية ثابتة تمثل اسم العمود الفرعي.

يعيد العمود الفرعي المطلوب المستخرج من التعبير.

البنية

getSubcolumn(nested_value, subcolumn_name)

الوسيطات

لا شيء.

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

أمثلة

getSubcolumn

SELECT getSubcolumn(array_col, 'size0'), getSubcolumn(tuple_col, 'elem_name')
FROM values('array_col Array(UInt32), tuple_col Tuple(elem_name String)', ([1, 2, 3], tuple('abc')));

┌─getSubcolumn(array_col, 'size0')─┬─getSubcolumn(tuple_col, 'elem_name')─┐
│                                3 │ abc                                  │
└──────────────────────────────────┴──────────────────────────────────────┘

getTypeSerializationStreams

أُضيف في: v22.6.0

يسرد مسارات التدفق الخاصة بنوع البيانات. هذه الدالة مخصّصة لأغراض التطوير.

الصيغة

getTypeSerializationStreams(col)

الوسيطات

col — عمود أو تمثيل نصي لنوع بيانات يُكتشف منه نوع البيانات. Any

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

يعيد مصفوفة تحتوي على جميع مسارات التدفقات الفرعية الخاصة بالتسلسل. Array(String)

أمثلة

tuple

SELECT getTypeSerializationStreams(tuple('a', 1, 'b', 2))

['{TupleElement(1), InlinedStringSizes()}','{TupleElement(1), Regular}','{TupleElement(2), Regular}','{TupleElement(3), InlinedStringSizes()}','{TupleElement(3), Regular}','{TupleElement(4), Regular}']

map

SELECT getTypeSerializationStreams('Map(String, Int64)')

['{ArraySizes}','{ArrayElements, TupleElement(keys), InlinedStringSizes()}','{ArrayElements, TupleElement(keys), Regular}','{ArrayElements, TupleElement(values), Regular}']

globalVariable

قُدِّمت في: v20.5.0

تأخذ وسيطة String ثابتة وتُرجع قيمة المتغير العام الذي يحمل هذا الاسم. هذه الدالة مخصّصة للتوافق مع MySQL، وليست مطلوبة أو مفيدة للتشغيل العادي لـ ClickHouse. لا يوجد سوى عدد قليل من المتغيرات العامة الوهمية المعرَّفة.

البنية

globalVariable(name)

الوسائط

name — اسم المتغير العام. String

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

تعيد قيمة المتغير name. Any

أمثلة

globalVariable

SELECT globalVariable('max_allowed_packet')

67108864

hasColumnInTable

أُضيفت في: v1.1.0

يتحقق مما إذا كان عمود محدد موجودًا في جدول ضمن قاعدة بيانات. وبالنسبة إلى العناصر ضمن بنية بيانات متداخلة، تتحقق الدالة من وجود عمود. أما بنية البيانات المتداخلة نفسها، فتعيد الدالة القيمة 0.

البنية

hasColumnInTable(database, table, column)

الوسيطات

database — اسم قاعدة البيانات. const String
table — اسم الجدول. const String
column — اسم العمود. const String

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

يعيد 1 إذا كان العمود المحدد موجودًا، وإلا فيعيد 0. UInt8

أمثلة

التحقق من وجود عمود

SELECT hasColumnInTable('system','metrics','metric')

التحقق من عمود غير موجود

SELECT hasColumnInTable('system','metrics','non-existing_column')

hasThreadFuzzer

أُضيف في: v20.6.0

يعيد ما إذا كان thread fuzzer مفعّلًا. هذه الدالة مفيدة فقط للاختبار وتصحيح الأخطاء.

الصيغة

hasThreadFuzzer()

المعاملات

لا يوجد.

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

يعيد ما إذا كان Thread Fuzzer مفعّلًا. UInt8

أمثلة

التحقق من حالة Thread Fuzzer

SELECT hasThreadFuzzer()

┌─hasThreadFuzzer()─┐
│                 0 │
└───────────────────┘

highlightQuery

أُضيف في: v26.5.0

يحلّل سلسلة query في ClickHouse SQL ويُرجع Array من النطاقات المميّزة لاستخدامها في تمييز الصياغة. كل نطاق عبارة عن named tuple يتضمن موضع البداية (بالبايتات)، وموضع النهاية، ونوع التمييز. وتصف أنواع التمييز الدور النحوي للمقطع (keyword، أو identifier، أو function، وما إلى ذلك) ويمكن استخدامها لتعيين الألوان في واجهة المستخدم. داخل أنماط السلاسل النصية لـ LIKE وREGEXP، تُميَّز المحارف الفوقية وأحرف الإفلات كلٌّ على حدة.

الصياغة

highlightQuery(query)

المعاملات

query — سلسلة استعلام في ClickHouse SQL. String.

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

مصفوفة من Tuples مُسمّاة (begin UInt64, end UInt64, type Enum8(...)) تمثّل النطاقات المميّزة. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

أمثلة

بسيط

SELECT highlightQuery('SELECT 1')

[(0,6,'keyword'),(7,8,'number')]

hostName

أُضيفت في: v20.5.0

تعيد اسم المضيف الذي نُفِّذت عليه هذه الدالة. إذا نُفِّذت الدالة على خادم بعيد (المعالجة الموزعة)، فسيُعاد اسم الخادم البعيد. إذا نُفِّذت الدالة ضمن سياق جدول موزّع، فإنها تُنشئ عمودًا عاديًا بقيم تخص كل جزء. وفي غير ذلك، فإنها تُنتج قيمة ثابتة.

الصيغة

hostName()

الأسماء المستعارة: hostname

الوسيطات

لا شيء.

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

يعيد اسم المضيف. String

أمثلة

مثال على الاستخدام

SELECT hostName()

┌─hostName()─┐
│ clickhouse │
└────────────┘

icebergBucket

أُضيف في: v25.5.0

يُنفِّذ المنطق الخاص بـ تحويل bucket في Iceberg

البنية

icebergBucket(N, value)

الوسيطات

N — عدد الـ buckets، modulo. const (U)Int*
value — القيمة المراد تحويلها. (U)Int* أو Bool أو Decimal أو Float* أو String أو FixedString أو UUID أو Date أو Time أو DateTime

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

يعيد قيمة تجزئة بطول 32 بت للقيمة المصدرية. Int32

أمثلة

مثال

SELECT icebergBucket(5, 1.0 :: Float32)

icebergTruncate

أُضيف في: v25.3.0

يطبّق منطق تحويل truncate في Iceberg: https://iceberg.apache.org/spec/#truncate-transform-details.

البنية

icebergTruncate(N, value)

الوسيطات

value — القيمة المطلوب تحويلها. String أو (U)Int* أو Decimal

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

نفس نوع الوسيط

أمثلة

مثال

SELECT icebergTruncate(3, 'iceberg')

ice

identity

أُضيفت في: v1.1.0

تعيد هذه الدالة الوسيطة التي تمرّرها إليها، وهو ما يفيد في تصحيح الأخطاء والاختبار. كما تتيح لك تجاوز استخدام الفهرس لمعاينة أداء المسح الكامل بدلًا من ذلك. ويتجاهل محلل الاستعلام أي شيء داخل دوال identity عند البحث عن الفهارس التي سيستخدمها، كما يعطّل أيضًا طيّ الثوابت.

الصياغة

identity(x)

الوسيطات

x — قيمة الإدخال. Any

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

تعيد قيمة الإدخال دون تغيير. Any

أمثلة

مثال للاستخدام

SELECT identity(42)

ignore

استُحدث في: v1.1.0

يقبل أي وسيطات ويُرجع 0 دائمًا.

الصياغة

ignore(x)

الوسائط

x — قيمة إدخال غير مستخدمة، وتُمرَّر فقط لتجنّب حدوث خطأ نحوي. Any

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

تُعيد دائمًا 0. UInt8

أمثلة

مثال للاستخدام

SELECT ignore(0, 'ClickHouse', NULL)

┌─ignore(0, 'ClickHouse', NULL)─┐
│                             0 │
└───────────────────────────────┘

indexHint

أُضيف في: v1.1.0

هذه الدالة مخصّصة لأغراض تصحيح الأخطاء والفحص الداخلي. فهي تتجاهل وسيطها وتُرجع دائمًا 1. كما أن الوسائط لا تُقيَّم.

أثناء تحليل الفهرس، يُفترَض أن وسيط هذه الدالة ليس مغلّفًا داخل indexHint. ويتيح لك ذلك تحديد البيانات ضمن نطاقات الفهرس وفقًا للشرط المقابل، ولكن من دون إجراء تصفية إضافية بناءً على هذا الشرط. وبما أن الفهرس في ClickHouse متناثر، فإن استخدام indexHint سيؤدي إلى إرجاع بيانات أكثر من تحديد الشرط نفسه مباشرةً.

الشرح

عندما تُشغِّل:

SELECT * FROM test WHERE key = 123;

فإن ClickHouse يقوم بأمرين:

يستخدم الفهرس لتحديد الحبيبات (كتل تضم نحو 8192 صفًا) التي قد تحتوي على key = 123
يقرأ تلك الحبيبات ويصفّيها صفًا بصف لإرجاع الصفوف التي يكون فيها key = 123 فقط

لذا، حتى إذا قرأ 8,192 صفًا من القرص، فإنه لا يُرجع إلا الصف الوحيد المطابق فعليًا.

أما مع indexHint، فعندما تُشغِّل:

SELECT * FROM test WHERE indexHint(key = 123);

فإن ClickHouse يقوم بأمر واحد فقط:

يستخدم الفهرس لتحديد الحبيبات التي قد تحتوي على key = 123 ويُرجع جميع الصفوف من تلك الحبيبات من دون تصفية.

فهو يُرجع الصفوف الـ 8,192 كلها، بما في ذلك الصفوف التي فيها key = 456 وkey = 789 وما إلى ذلك. (أي كل ما صادف تخزينه في الحبيبة نفسها.) إن indexHint() ليس مخصّصًا للأداء، بل لتصحيح الأخطاء وفهم كيفية عمل فهرس ClickHouse:

ما الحبيبات التي يحدّدها الشرط الخاص بي؟
كم عدد الصفوف الموجودة في تلك الحبيبات؟
هل يُستخدم الفهرس لديّ بفاعلية؟

ملاحظة: لا يمكن تحسين أي استعلام باستخدام الدالة indexHint. فالدالة indexHint لا تحسّن الاستعلام، لأنها لا توفّر أي معلومات إضافية لتحليل الاستعلام. كما أن وضع تعبير داخل الدالة indexHint ليس أفضل بأي شكل من عدم استخدام الدالة indexHint. ولا يمكن استخدام الدالة indexHint إلا لأغراض الفحص الداخلي وتصحيح الأخطاء، وهي لا تحسّن الأداء. وإذا رأيت استخدام indexHint من أي جهة غير المساهمين في ClickHouse، فغالبًا ما يكون ذلك خطأً ويجب عليك إزالته.

الصياغة

indexHint(expression)

المعاملات

expression — أي تعبير لاختيار نطاق الفهرس. Expression

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

تعيد 1 في جميع الحالات. UInt8

أمثلة

مثال استخدام مع التصفية حسب التاريخ

-- `index_granularity` is lowered to 8 here only to keep the example small enough to follow.
-- Do not change it in production: the default of 8192 is what makes the index sparse and cheap,
-- and a small value makes the index large and slows queries down.
CREATE TABLE ontime (FlightDate Date, Carrier String)
ENGINE = MergeTree ORDER BY FlightDate
SETTINGS index_granularity = 8;

-- Ten flights on each of four days, so a granule of eight rows spans more than one day.
INSERT INTO ontime SELECT toDate('2025-09-14') + intDiv(number, 10), 'AA' FROM numbers(40);

-- The granules that hold the rows of 2025-09-15 also hold rows of the neighbouring days,
-- and `indexHint` returns all of them.
SELECT FlightDate AS k, count() FROM ontime WHERE indexHint(k = '2025-09-15') GROUP BY k ORDER BY k ASC;

┌──────────k─┬─count()─┐
│ 2025-09-14 │       2 │
│ 2025-09-15 │      10 │
│ 2025-09-16 │       4 │
└────────────┴─────────┘

initialQueryID

أُضيف في: v1.1.0

يُرجع معرّف الاستعلام الحالي الأوّلي. يمكن استخراج المعلمات الأخرى الخاصة بالاستعلام من الحقل initial_query_id في system.query_log.

بخلاف الدالة queryID، تُرجع initialQueryID النتائج نفسها على الشظايا المختلفة.

الصياغة

initialQueryID()

الأسماء المستعارة: initial_query_id

الوسيطات

لا شيء.

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

تعيد معرّف الاستعلام الحالي الأوّلي. String

أمثلة

مثال على الاستخدام

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

initialQueryStartTime

قُدِّم في: v25.4.0

يعيد وقت بدء الاستعلام الحالي الأوّلي. يعيد initialQueryStartTime النتائج نفسها على مختلف الشظايا.

الصياغة

initialQueryStartTime()

الأسماء المستعارة: initial_query_start_time

الوسيطات

لا يوجد.

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

تعيد وقت بدء الاستعلام الحالي الأوّلي. DateTime

أمثلة

مثال على الاستخدام

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT initialQueryStartTime() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                1 │
└──────────────────┘

initializeAggregation

أُضيفت في: v20.6.0

تحسب نتيجة دالة تجميعية استنادًا إلى قيمة واحدة. يمكن استخدام هذه الدالة لتهيئة دوال التجميع باستخدام المُركِّب -State. يمكنك إنشاء حالات لدوال التجميع وإدراجها في أعمدة من النوع AggregateFunction، أو استخدام التجميعات المُهيّأة كقيم افتراضية.

البنية

initializeAggregation(aggregate_function, arg1[, arg2, ...])

الوسيطات

aggregate_function — اسم دالة التجميع المراد تهيئتها. String
arg1[, arg2, ...] — وسيطات دالة التجميع. Any

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

تُرجع نتيجة التجميع لكل صف يُمرَّر إلى الدالة. ويكون نوع الإرجاع مطابقًا لنوع الإرجاع الخاص بالدالة التي تأخذها initializeAggregation بوصفها الوسيط الأول. Any

أمثلة

الاستخدام الأساسي مع uniqState

SELECT uniqMerge(state) FROM (SELECT initializeAggregation('uniqState', number % 3) AS state FROM numbers(10000));

┌─uniqMerge(state)─┐
│                3 │
└──────────────────┘

استخدام sumState و finalizeAggregation

SELECT finalizeAggregation(state), toTypeName(state) FROM (SELECT initializeAggregation('sumState', number % 3) AS state FROM numbers(5));

┌─finalizeAggregation(state)─┬─toTypeName(state)─────────────┐
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
│                          2 │ AggregateFunction(sum, UInt8) │
│                          0 │ AggregateFunction(sum, UInt8) │
│                          1 │ AggregateFunction(sum, UInt8) │
└────────────────────────────┴───────────────────────────────┘

isConstant

قُدِّمت في: v20.3.0

تُرجع ما إذا كانت الوسيطة تعبيرًا ثابتًا. والتعبير الثابت هو تعبير تكون نتيجته معروفة أثناء تحليل الاستعلام، أي قبل التنفيذ. على سبيل المثال، تُعدّ التعبيرات المبنية على القيم الحرفية تعبيرات ثابتة. تُستخدم هذه الدالة غالبًا لأغراض التطوير وتصحيح الأخطاء والتوضيح.

الصياغة

isConstant(x)

الوسيطات

x — تعبير للتحقق منه. Any

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

تعيد 1 إذا كان x ثابتًا، و0 إذا كان x غير ثابت. UInt8

أمثلة

تعبير ثابت

SELECT isConstant(x + 1)
FROM (SELECT 43 AS x)

┌─isConstant(plus(x, 1))─┐
│                      1 │
└────────────────────────┘

ثابت مع استخدام دالة

WITH 3.14 AS pi
SELECT isConstant(cos(pi))

┌─isConstant(cos(pi))─┐
│                   1 │
└─────────────────────┘

تعبير غير ثابت

SELECT isConstant(number)
FROM numbers(1)

┌─isConstant(number)─┐
│                  0 │
└────────────────────┘

سلوك الدالة now()

SELECT isConstant(now())

┌─isConstant(now())─┐
│                 1 │
└───────────────────┘

isDecimalOverflow

استُحدثت في: v20.8.0

يتحقق مما إذا كان العدد العشري يحتوي على عدد كبير جدًا من الخانات بحيث لا يمكن تمثيله بشكل صحيح ضمن نوع البيانات Decimal عند دقة محددة.

البنية

isDecimalOverflow(value[, precision])

الوسائط

value — قيمة Decimal المطلوب التحقق منها. Decimal
precision — اختياري. دقة النوع Decimal. إذا لم يتم تحديده، تُستخدم الدقة الأصلية للوسيطة الأولى. UInt8

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

تعيد 1 إذا كانت قيمة Decimal تحتوي على عدد من الخانات أكبر مما تسمح به دقتها، و0 إذا كانت قيمة Decimal تستوفي الدقة المحددة. UInt8

أمثلة

مثال على الاستخدام

SELECT isDecimalOverflow(toDecimal32(1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(1000000000, 0)),
       isDecimalOverflow(toDecimal32(-1000000000, 0), 9),
       isDecimalOverflow(toDecimal32(-1000000000, 0));

┌─isDecimalOverflow(toDecimal32(1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(1000000000, 0))─┬─isDecimalOverflow(toDecimal32(-1000000000, 0), 9)─┬─isDecimalOverflow(toDecimal32(-1000000000, 0))─┐
│                                                1 │                                             1 │                                                 1 │                                              1 │
└──────────────────────────────────────────────────┴───────────────────────────────────────────────┴───────────────────────────────────────────────────┴────────────────────────────────────────────────┘

joinGet

أُضيف في: v18.16.0

يتيح لك استخراج البيانات من جدول بالطريقة نفسها كما لو كانت من قاموس. يجلب البيانات من جداول Join باستخدام مفتاح الربط المحدد.

الصياغة

joinGet(join_storage_table_name, value_column, join_keys)

الوسيطات

join_storage_table_name — معرّف يحدّد مكان إجراء البحث. يُبحث عن هذا المعرّف في قاعدة البيانات الافتراضية (راجع المَعلمة default_database في ملف الإعدادات). لتجاوز قاعدة البيانات الافتراضية، استخدم الاستعلام USE database_name أو حدّد قاعدة البيانات والجدول باستخدام نقطة، مثل database_name.table_name. String
value_column — اسم عمود الجدول الذي يحتوي على البيانات المطلوبة. const String
join_keys — قائمة بمفاتيح الربط. Any

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

يعيد قائمة من القيم المقابلة لقائمة المفاتيح. Any

أمثلة

مثال على الاستخدام

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGet(id_val, 'val', toUInt32(1));

┌─joinGet('id_val', 'val', toUInt32(1))─┐
│                                    11 │
└───────────────────────────────────────┘

الاستخدام مع جدول من قاعدة البيانات الحالية

SELECT joinGet(id_val, 'val', toUInt32(2));

┌─joinGet('id_val', 'val', toUInt32(2))─┐
│                                    12 │
└───────────────────────────────────────┘

استخدام المصفوفات كمفاتيح للربط

CREATE TABLE some_table (id1 UInt32, id2 UInt32, name String) ENGINE = Join(ANY, LEFT, id1, id2);
INSERT INTO some_table VALUES (1, 11, 'a') (2, 12, 'b') (3, 13, 'c');

SELECT joinGet(some_table, 'name', toUInt32(1), toUInt32(11));

┌─joinGet('some_table', 'name', toUInt32(1), toUInt32(11))─┐
│ a                                                        │
└──────────────────────────────────────────────────────────┘

joinGetOrNull

قُدِّمت في: v20.4.0

تتيح لك استخراج البيانات من جدول بالطريقة نفسها المتبعة مع القاموس. تجلب البيانات من جداول Join باستخدام مفتاح الربط المحدد. وعلى خلاف joinGet، فإنها تُرجع NULL عندما يكون المفتاح غير موجود.

الصياغة

joinGetOrNull(join_storage_table_name, value_column, join_keys)

الوسيطات

join_storage_table_name — معرّف يحدّد مكان إجراء البحث. يُجرى البحث عن هذا المعرّف في قاعدة البيانات الافتراضية (راجع المعامل default_database في ملف الإعدادات). لتجاوز قاعدة البيانات الافتراضية، استخدم الاستعلام USE database_name أو حدِّد قاعدة البيانات والجدول باستخدام نقطة، مثل database_name.table_name. String
value_column — اسم العمود في الجدول الذي يحتوي على البيانات المطلوبة. const String
join_keys — قائمة بمفاتيح الربط. Any

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

يعيد قائمة بالقيم المقابلة لقائمة المفاتيح، أو NULL إذا لم يُعثر على مفتاح. Any

أمثلة

مثال على الاستخدام

CREATE TABLE id_val(`id` UInt32, `val` UInt32) ENGINE = Join(ANY, LEFT, id);
INSERT INTO id_val VALUES (1,11)(2,12)(4,13);

SELECT joinGetOrNull(id_val, 'val', toUInt32(1)), joinGetOrNull(id_val, 'val', toUInt32(999));

┌─joinGetOrNull('id_val', 'val', toUInt32(1))─┬─joinGetOrNull('id_val', 'val', toUInt32(999))─┐
│                                          11 │                                          ᴺᵁᴸᴸ │
└─────────────────────────────────────────────┴───────────────────────────────────────────────┘

lowCardinalityIndices

تمت إضافته في: v18.12.0

تعيد هذه الدالة موضع قيمة في القاموس الخاص بعمود LowCardinality. تبدأ المواضع من 1. ونظرًا لأن LowCardinality يستخدم قواميس لكل جزء، فقد تُرجِع هذه الدالة مواضع مختلفة للقيمة نفسها في أجزاء مختلفة.

الصياغة

lowCardinalityIndices(col)

الوسيطات

col — عمود منخفض الكاردينالية. LowCardinality

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

موضع القيمة في القاموس الخاص بالجزء الحالي. UInt64

أمثلة

أمثلة الاستخدام

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

-- the order the blocks are read in is not defined, so sort the result to make it reproducible:

SELECT s, lowCardinalityIndices(s) AS index FROM test ORDER BY s, index;

┌─s──┬─index─┐
│ ab │     1 │
│ ab │     1 │
│ ab │     1 │
│ ab │     3 │
│ cd │     2 │
│ cd │     2 │
│ cd │     2 │
│ df │     3 │
│ ef │     1 │
│ ef │     1 │
└────┴───────┘

lowCardinalityKeys

أُضيف في: v18.12.0

تُرجع قيم القاموس لعمود LowCardinality. إذا كانت الكتلة أصغر من حجم القاموس أو أكبر منه، فستُقتطع النتيجة أو تُستكمل باستخدام القيم الافتراضية. ونظرًا لأن LowCardinality تستخدم قواميس منفصلة لكل جزء، فقد تُرجع هذه الدالة قيم قاموس مختلفة في الأجزاء المختلفة.

الصياغة

lowCardinalityKeys(col)

الوسيطات

col — عمود منخفض الكاردينالية. LowCardinality

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

يُرجع مفاتيح القاموس. UInt64

أمثلة

lowCardinalityKeys

DROP TABLE IF EXISTS test;
CREATE TABLE test (s LowCardinality(String)) ENGINE = Memory;

-- create two parts:

INSERT INTO test VALUES ('ab'), ('cd'), ('ab'), ('ab'), ('df');
INSERT INTO test VALUES ('ef'), ('cd'), ('ab'), ('cd'), ('ef');

SELECT s, lowCardinalityKeys(s) FROM test;

┌─s──┬─lowCardinalityKeys(s)─┐
│ ef │                       │
│ cd │ ef                    │
│ ab │ cd                    │
│ cd │ ab                    │
│ ef │                       │
└────┴───────────────────────┘
┌─s──┬─lowCardinalityKeys(s)─┐
│ ab │                       │
│ cd │ ab                    │
│ ab │ cd                    │
│ ab │ df                    │
│ df │                       │
└────┴───────────────────────┘

materialize

استُحدث في: v1.1.0

يحوِّل قيمة ثابتة إلى عمود كامل يحتوي على قيمة واحدة. تُمثَّل الأعمدة الكاملة والثوابت بصورة مختلفة في الذاكرة. عادةً ما تنفِّذ الدوال شيفرة مختلفة للوسائط العادية والثابتة، رغم أن النتيجة ينبغي في الغالب أن تكون واحدة. يمكن استخدام هذه الدالة لتصحيح هذا السلوك.

الصيغة

materialize(x)

الوسائط

x — ثابت. Any

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

يعيد عمودًا كاملاً يحتوي على القيمة الثابتة. Any

أمثلة

مثال على الاستخدام

-- In the example below the `countMatches` function expects a constant second argument.
-- This behaviour can be debugged by using the `materialize` function to turn a constant into a full column,
-- verifying that the function throws an error for a non-constant argument.

SELECT countMatches('foobarfoo', 'foo');

تحويل قيمة ثابتة إلى عمود كامل

SELECT countMatches('foobarfoo', materialize('foo'));

Received exception:
Code: 44. DB::Exception: A value of illegal type was provided as 2nd argument 'pattern' to function 'countMatches'. Expected: constant String, got: String. (ILLEGAL_COLUMN)

minSampleSizeContinuous

قُدِّمت في: v23.10.0

تحسب الحد الأدنى المطلوب لحجم العينة لاختبار A/B يقارن متوسطات مقياس مستمر بين عينتين.

تستخدم الصيغة الموضحة في هذه المقالة. وتفترض تساوي حجمي مجموعتي المعالجة والمجموعة الضابطة. وتُرجع حجم العينة المطلوب لمجموعة واحدة (أي إن حجم العينة المطلوب للتجربة بأكملها يساوي ضعف القيمة المُرجعة). كما تفترض أيضًا تساوي تباين مقياس الاختبار في مجموعتي المعالجة والمجموعة الضابطة.

الصيغة

minSampleSizeContinuous(baseline, sigma, mde, power, alpha)

الأسماء البديلة: minSampleSizeContinous

الوسيطات

baseline — القيمة المرجعية لمقياس. (U)Int* أو Float*
sigma — الانحراف المعياري المرجعي لمقياس. (U)Int* أو Float*
mde — الحد الأدنى للأثر القابل للاكتشاف (MDE) كنسبة مئوية من القيمة المرجعية (على سبيل المثال، إذا كانت القيمة المرجعية 112.25، فإن قيمة MDE البالغة 0.03 تعني تغيرًا متوقعًا إلى 112.25 ± 112.25*0.03). (U)Int* أو Float*
power — القدرة الإحصائية المطلوبة للاختبار (1 - احتمال الخطأ من النوع الثاني). (U)Int* أو Float*
alpha — مستوى الدلالة المطلوب للاختبار (احتمال الخطأ من النوع الأول). (U)Int* أو Float*

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

تعيد Tuple مُسمّاة تحتوي على 3 عناصر: minimum_sample_size و detect_range_lower و detect_range_upper. وتمثل هذه العناصر، على الترتيب: حجم العينة المطلوب، والحد الأدنى لنطاق القيم التي لا يمكن اكتشافها باستخدام حجم العينة المطلوب المُعاد، ويُحسب على النحو baseline * (1 - mde)، والحد الأعلى لنطاق القيم التي لا يمكن اكتشافها باستخدام حجم العينة المطلوب المُعاد، ويُحسب على النحو baseline * (1 + mde) ‏(Float64). Tuple(Float64, Float64, Float64)

أمثلة

minSampleSizeContinuous

SELECT minSampleSizeContinuous(112.25, 21.1, 0.03, 0.80, 0.05) AS sample_size

(616.2931945826209,108.8825,115.6175)

minSampleSizeConversion

أُضيف في: v22.6.0

يحسب الحد الأدنى المطلوب لحجم العينة لاختبار A/B يقارن معدلات التحويل (النِّسب) بين عينتين.

يستخدم الصيغة الموضحة في هذه المقالة. ويفترض تساوي حجمَي مجموعتي المعالجة والضبط. ويُرجع حجم العينة المطلوب لمجموعة واحدة (أي إن حجم العينة المطلوب للتجربة بأكملها يساوي ضعف القيمة المُعادة).

الصيغة

minSampleSizeConversion(baseline, mde, power, alpha)

الوسيطات

baseline — معدل التحويل الأساسي. Float*
mde — الحد الأدنى للأثر القابل للاكتشاف (MDE) بالنقاط المئوية (على سبيل المثال، إذا كان معدل التحويل الأساسي 0.25، فإن قيمة MDE البالغة 0.03 تعني تغيرًا متوقعًا إلى 0.25 ± 0.03). Float*
power — القدرة الإحصائية المطلوبة للاختبار (1 - احتمال خطأ من النوع الثاني). Float*
alpha — مستوى الدلالة المطلوب للاختبار (احتمال خطأ من النوع الأول). Float*

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

تعيد قيمة Tuple مُسمّاة تتكون من 3 عناصر: minimum_sample_size وdetect_range_lower وdetect_range_upper. وتمثل هذه العناصر، على الترتيب: حجم العينة المطلوب، والحد الأدنى لنطاق القيم غير القابلة للاكتشاف باستخدام حجم العينة المطلوب المُعاد، ويُحسب على أنه baseline - mde، والحد الأعلى لنطاق القيم غير القابلة للاكتشاف باستخدام حجم العينة المطلوب المُعاد، ويُحسب على أنه baseline + mde. Tuple(Float64, Float64, Float64)

أمثلة

minSampleSizeConversion

SELECT minSampleSizeConversion(0.25, 0.03, 0.80, 0.05) AS sample_size

(3396.077603219163,0.22,0.28)

neighbor

أُضيفت في: v20.1.0

تُرجع قيمة من عمود عند إزاحة محددة من الصف الحالي. هذه الدالة مُهملة ومعرّضة للأخطاء لأنها تعمل على الترتيب الفيزيائي لكتل البيانات، الذي قد لا يتوافق مع الترتيب المنطقي الذي يتوقعه المستخدمون. يُنصح باستخدام دوال النافذة المناسبة بدلًا من ذلك.

يمكن تمكين هذه الدالة عن طريق تعيين allow_deprecated_error_prone_window_functions = 1.

البنية

neighbor(column, offset[, default_value])

المعاملات

column — العمود المصدر. Any
offset — الإزاحة من الصف الحالي. تشير القيم الموجبة إلى الأمام، وتشير القيم السالبة إلى الخلف. Integer
default_value — اختياري. القيمة التي تُعاد إذا تجاوزت الإزاحة حدود البيانات. إذا لم يُحدَّد، تُستخدَم القيمة الافتراضية لنوع العمود. Any

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

تُعيد قيمة عند الإزاحة المحددة، أو القيمة الافتراضية إذا كانت خارج الحدود. Any

أمثلة

مثال على الاستخدام

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2)─┐
│      0 │                   2 │
│      1 │                   3 │
│      2 │                   4 │
│      3 │                   5 │
│      4 │                   6 │
│      5 │                   7 │
│      6 │                   8 │
│      7 │                   9 │
│      8 │                   0 │
│      9 │                   0 │
└────────┴─────────────────────┘

مع القيمة الافتراضية

SET allow_deprecated_error_prone_window_functions = 1;
SELECT number, neighbor(number, 2, 999) FROM system.numbers LIMIT 10;

┌─number─┬─neighbor(number, 2, 999)─┐
│      0 │                        2 │
│      1 │                        3 │
│      2 │                        4 │
│      3 │                        5 │
│      4 │                        6 │
│      5 │                        7 │
│      6 │                        8 │
│      7 │                        9 │
│      8 │                      999 │
│      9 │                      999 │
└────────┴──────────────────────────┘

normalizeQuery

أُضيفت في: v20.8.0

تستبدل القيم الحرفية، وتسلسلات القيم الحرفية، والأسماء المستعارة المعقدة (التي تحتوي على فراغات، أو أكثر من رقمين، أو يبلغ طولها 36 بايتًا على الأقل مثل UUIDs) بالرمز النائب ?.

البنية

normalizeQuery(x)

الوسيطات

x — تسلسل من المحارف. String

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

تُعيد تسلسل المحارف المُعطى مع عناصر نائبة. String

أمثلة

مثال على الاستخدام

SELECT normalizeQuery('[1, 2, 3, x]') AS query

┌─query────┐
│ [?.., x] │
└──────────┘

normalizeQueryKeepNames

قُدِّمت في: v21.2.0

تستبدل القيم الحرفية وسلاسل القيم الحرفية بالعنصر النائب ?، لكنها لا تستبدل الأسماء المستعارة المعقّدة (التي تحتوي على مسافات بيضاء، أو أكثر من رقمين، أو التي يبلغ طولها 36 بايتًا على الأقل، مثل UUIDs). يساعد ذلك على تحليل سجلات الاستعلام المعقّدة بشكل أفضل.

الصيغة

normalizeQueryKeepNames(x)

الوسيطات

x — سلسلة من الأحرف. String

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

تعيد سلسلة الأحرف المحددة مع العناصر النائبة. String

أمثلة

مثال على الاستخدام

SELECT normalizeQuery('SELECT 1 AS aComplexName123'), normalizeQueryKeepNames('SELECT 1 AS aComplexName123')

┌─normalizeQuery('SELECT 1 AS aComplexName123')─┬─normalizeQueryKeepNames('SELECT 1 AS aComplexName123')─┐
│ SELECT ? AS `?`                               │ SELECT ? AS aComplexName123                            │
└───────────────────────────────────────────────┴────────────────────────────────────────────────────────┘

normalizedQueryHash

قُدِّمت في: v20.8.0

تعيد قيم hash متطابقة بطول 64 بت، من دون قيم القيم الحرفية، للاستعلامات المتشابهة. يمكن أن يكون ذلك مفيدًا في تحليل سجلات الاستعلامات.

الصيغة

normalizedQueryHash(x)

الوسائط

x — تسلسل من الأحرف. String

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

يعيد قيمة تجزئة من 64 بت. UInt64

أمثلة

مثال على الاستخدام

SELECT normalizedQueryHash('SELECT 1 AS `xyz`') != normalizedQueryHash('SELECT 1 AS `abc`') AS res

┌─res─┐
│   1 │
└─────┘

normalizedQueryHashKeepNames

أُضيفت في: v21.2.0

على غرار normalizedQueryHash، تُرجِع هذه الدالة قيم hash متطابقة بطول 64 بت للاستعلامات المتشابهة من دون قيم القيم الحرفية، لكنها لا تستبدل الأسماء المستعارة المعقدة (التي تحتوي على مسافات، أو أكثر من رقمين، أو التي يبلغ طولها 36 بايتًا على الأقل مثل UUIDs) بعنصر نائب قبل إجراء hash. وقد يكون ذلك مفيدًا في تحليل سجلات الاستعلامات.

البنية

normalizedQueryHashKeepNames(x)

الوسيطات

x — سلسلة من الأحرف. String

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

يعيد قيمة تجزئة بطول 64 بت. UInt64

أمثلة

مثال على الاستخدام

SELECT normalizedQueryHash('SELECT 1 AS `xyz123`') != normalizedQueryHash('SELECT 1 AS `abc123`') AS normalizedQueryHash;
SELECT normalizedQueryHashKeepNames('SELECT 1 AS `xyz123`') != normalizedQueryHashKeepNames('SELECT 1 AS `abc123`') AS normalizedQueryHashKeepNames;

┌─normalizedQueryHash─┐
│                   0 │
└─────────────────────┘
┌─normalizedQueryHashKeepNames─┐
│                            1 │
└──────────────────────────────┘

obfuscateQuery

أُضيف في: v26.4.0

يُموّه استعلام SQL عبر استبدال المعرّفات بكلمات عشوائية والقيم الحرفية بقيم عشوائية، مع الحفاظ على بنية الاستعلام.

تكون هذه الدالة مفيدة لإخفاء هوية الاستعلامات قبل تسجيلها أو مشاركتها لأغراض تصحيح الأخطاء. وستنتج الصفوف المختلفة نتائج تمويه مختلفة حتى مع استعلام الإدخال نفسه، مما يساعد في الحفاظ على الخصوصية عند العمل مع عدة استعلامات.

تمنع المعلَمة الاختيارية tag إزالة التعبيرات الفرعية المشتركة عندما يُستخدم استدعاء الدالة نفسه عدة مرات في استعلام. ويضمن ذلك أن ينتج كل استدعاء نتيجة تمويه مختلفة.

الميزات:

يستبدل أسماء الجداول وأسماء الأعمدة والأسماء المستعارة بكلمات عشوائية
يستبدل القيم الحرفية الرقمية والنصية بقيم عشوائية
يحافظ على البنية العامة للاستعلام وصياغة SQL
ينتج نتائج مختلفة لصفوف مختلفة

الصيغة

obfuscateQuery(query[, tag])

الوسيطات

query — استعلام SQL المطلوب تمويهه. String
tag — اختياري. قيمة لمنع إزالة التعبيرات الفرعية المشتركة عند استخدام استدعاء الدالة نفسه عدة مرات.

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

الاستعلام المُموَّه بعد استبدال المعرّفات والقيم الحرفية مع الحفاظ على البنية الأصلية للاستعلام. String

أمثلة

الاستخدام الأساسي

SELECT obfuscateQuery('SELECT name, age FROM users WHERE age > 30')

SELECT fruit, number FROM table WHERE number > 12

باستخدام وسم لمنع إزالة التعبيرات الفرعية المشتركة

SELECT obfuscateQuery('SELECT * FROM t', 1), obfuscateQuery('SELECT * FROM t', 2)

SELECT a FROM b, SELECT c FROM d

تعطي الصفوف المختلفة نتائج مختلفة

SELECT obfuscateQuery('SELECT 1') AS a, obfuscateQuery('SELECT 1') AS b

SELECT 1	SELECT 1

obfuscateQueryWithSeed

أُضيف في: v26.4.0

يُموّه استعلام SQL باستخدام قيمة seed محددة للحصول على نتائج حتمية.

بخلاف obfuscateQuery(), تُنتج هذه الدالة نتائج حتمية عند تزويدها بالقيمة نفسها من seed. ويكون ذلك مفيدًا عندما تحتاج إلى تمويه متسق عبر عمليات تشغيل متعددة، أو عندما تريد إعادة إنتاج الاستعلام المُموَّه نفسه لأغراض الاختبار أو تصحيح الأخطاء.

الميزات:

تمويه حتمي استنادًا إلى قيمة seed المقدمة
تؤدي قيمة seed نفسها دائمًا إلى النتيجة المُموَّهة نفسها
تؤدي قيم seed المختلفة إلى نتائج مختلفة
يحافظ على بنية الاستعلام مثل obfuscateQuery()

حالات الاستخدام:

حالات اختبار قابلة لإعادة الإنتاج
إخفاء هوية متسق عبر عمليات تشغيل متعددة
تصحيح الأخطاء باستخدام استعلامات مُموَّهة متسقة

الصيغة

obfuscateQueryWithSeed(query, seed)

الوسائط

query — استعلام SQL المراد تمويهه. String
seed — قيمة البذرة للتمويه. تؤدي البذرة نفسها إلى نتائج حتمية. Integer أو String

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

الاستعلام المُموَّه، ويُولَّد بصورة حتمية استنادًا إلى البذرة المُقدَّمة. String

أمثلة

تمويه حتمي باستخدام بذرة من نوع عدد صحيح

SELECT obfuscateQueryWithSeed('SELECT name FROM users', 42)

SELECT name FROM users

إخفاء الهوية الحتمي باستخدام seed نصي

SELECT obfuscateQueryWithSeed('SELECT id, value FROM data', 'myseed')

SELECT id, value FROM data

تؤدي قيمة seed نفسها إلى النتيجة نفسها

SELECT obfuscateQueryWithSeed('SELECT 1', 100) = obfuscateQueryWithSeed('SELECT 1', 100)

parseQueryToJSON

متاح منذ: v26.8.0

يحلّل سلسلة استعلام SQL إلى AST (شجرة البنية المجرّدة) ويُرجع تمثيلًا بصيغة JSON لهذه الشجرة. يمكن تمرير JSON الناتج إلى formatQueryFromJSON لإعادة تكوين استعلام SQL، أو إرساله مباشرةً إلى الخادم باستخدام القيمة clickhouse_json لإعداد dialect (المشروط بـ enable_json_ast_dialect).

يفيد ذلك الأدوات التي تحتاج إلى فحص الاستعلامات أو تحويلها برمجيًا دون الرجوع إلى قواعد SQL النحوية.

لا يمتلك كل استعلام SQL تمثيلًا مطابقًا تمامًا بصيغة JSON. تُرفض الاستعلامات التي تتضمن بيانات لا يمكن لصيغة JSON إعادة إنتاجها (مثل بيانات INSERT ... VALUES / INSERT ... FORMAT المضمّنة) وأنواع عُقد AST التي لم تدعم بعد تسلسل JSON، ويُرجع الخطأ BAD_ARGUMENTS بدلًا من إنتاج JSON لا يمكن لـ formatQueryFromJSON قراءته مجددًا.

تُؤخذ حدود التحليل (max_query_size وmax_parser_depth وmax_parser_backtracks) من إعدادات الجلسة الحالية.

صيغة

parseQueryToJSON(sql)

وسيطات الدالة

sql — سلسلة استعلام SQL لتحليلها. String

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

سلسلة JSON تمثّل شجرة AST. String

أمثلة

عبارة SELECT بسيطة

SELECT formatQueryFromJSON(parseQueryToJSON('SELECT 1'));

┌─formatQueryFromJSON(parseQueryToJSON('SELECT 1'))─┐
│ SELECT 1                                          │
└───────────────────────────────────────────────────┘

parseReadableSize

أُضيفت في: v24.6.0

إذا أُعطيت هذه الدالة سلسلة نصية تحتوي على حجم بالبايت مع وحدة مثل B أو KiB أو KB أو MiB أو MB وما إلى ذلك (أي ISO/IEC 80000-13 أو وحدة بايت عشرية)، فستُرجع عدد البايتات المقابل. إذا تعذّر على الدالة تحليل قيمة الإدخال، فإنها تُطلق استثناءً.

العمليات العكسية لهذه الدالة هي formatReadableSize وformatReadableDecimalSize.

البنية

parseReadableSize(x)

الوسائط

x — حجم بصيغة مقروءة مع وحدة ISO/IEC 80000-13 أو وحدة بايت عشرية. String

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

يعيد عدد البايتات، مُقرَّبًا للأعلى إلى أقرب عدد صحيح. UInt64

أمثلة

مثال على الاستخدام

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB']) AS readable_sizes, parseReadableSize(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
└────────────────┴─────────┘

parseReadableSizeOrNull

أُضيف في: v24.6.0

إذا أُعطيت هذه الدالة سلسلة نصية تتضمن حجم بايت ووحدة مثل B أو KiB أو KB أو MiB أو MB وما إلى ذلك (أي ISO/IEC 80000-13 أو وحدة بايت عشرية)، فإنها تُرجع عدد البايتات المقابل. إذا تعذّر على الدالة تحليل قيمة الإدخال، فإنها تُرجع NULL.

العمليات العكسية لهذه الدالة هي formatReadableSize وformatReadableDecimalSize.

الصياغة

parseReadableSizeOrNull(x)

الوسائط

x — حجم بصيغة مقروءة باستخدام ISO/IEC 80000-13 أو وحدة بايت عشرية. String

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

يُرجع عدد البايتات، مُقرَّبًا للأعلى إلى أقرب عدد صحيح، أو NULL إذا تعذّر تحليل الإدخال Nullable(UInt64)

أمثلة

مثال على الاستخدام

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrNull(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │    ᴺᵁᴸᴸ │
└────────────────┴─────────┘

parseReadableSizeOrZero

أُضيفت في: v24.6.0

إذا كانت لديك سلسلة نصية تحتوي على حجم بالبايت ووحدة مثل B أو KiB أو KB أو MiB أو MB وما إلى ذلك (أي ISO/IEC 80000-13 أو وحدة البايت العشرية)، فستُرجع هذه الدالة عدد البايتات المقابل. إذا تعذّر على الدالة تحليل قيمة الإدخال، فستُرجع 0.

العمليتان العكسيتان لهذه الدالة هما formatReadableSize وformatReadableDecimalSize.

الصياغة

parseReadableSizeOrZero(x)

الوسيطات

x — حجم بصيغة مقروءة وفق ISO/IEC 80000-13 أو بوحدة بايت عشرية. String

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

يعيد عدد البايتات، مُقرَّبًا إلى الأعلى لأقرب عدد صحيح، أو 0 إذا تعذّر تحليل المُدخل. UInt64

أمثلة

مثال على الاستخدام

SELECT arrayJoin(['1 B', '1 KiB', '3 MB', '5.314 KiB', 'invalid']) AS readable_sizes, parseReadableSizeOrZero(readable_sizes) AS sizes;

┌─readable_sizes─┬───sizes─┐
│ 1 B            │       1 │
│ 1 KiB          │    1024 │
│ 3 MB           │ 3000000 │
│ 5.314 KiB      │    5442 │
│ invalid        │       0 │
└────────────────┴─────────┘

parseTimeDelta

أُضيف في: v22.7.0

يحلّل تسلسلًا من الأرقام يتبعه ما يشبه وحدة زمنية.

تستخدم سلسلة الفاصل الزمني هذه مواصفات وحدات الزمن التالية:

years, year, yr, y
months, month, mo
weeks, week, w
days, day, d
hours, hour, hr, h
minutes, minute, min, m
seconds, second, sec, s
milliseconds, millisecond, millisec, ms
microseconds, microsecond, microsec, μs, µs, us
nanoseconds, nanosecond, nanosec, ns

يمكن الجمع بين عدة وحدات زمنية باستخدام الفواصل (مسافة، ;، -، +، ,، :).

أطوال السنوات والأشهر تقريبية: السنة 365 يومًا، والشهر 30.5 يومًا.

الصيغة

parseTimeDelta(timestr)

الوسائط

timestr — سلسلة من الأرقام يتبعها ما يشبه وحدة زمنية. String

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

عدد الثواني. Float64

أمثلة

مثال على الاستخدام

SELECT parseTimeDelta('11s+22min')

┌─parseTimeDelta('11s+22min')─┐
│                        1331 │
└─────────────────────────────┘

وحدات زمنية مركّبة

SELECT parseTimeDelta('1yr2mo')

┌─parseTimeDelta('1yr2mo')─┐
│                 36806400 │
└──────────────────────────┘

partitionId

قُدِّمت في: v21.4.0

تحسب معرّف التقسيم.

الصيغة

partitionId(column1[, column2, ...])

الأسماء المستعارة: partitionID

الوسيطات

column1, column2, ... — العمود الذي سيُعاد معرّف القسم الخاص به.

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

يُعيد معرّف القسم الذي ينتمي إليه الصف. String

أمثلة

مثال على الاستخدام

DROP TABLE IF EXISTS tab;

CREATE TABLE tab
(
  i int,
  j int
)
ENGINE = MergeTree
PARTITION BY i
ORDER BY tuple();

INSERT INTO tab VALUES (1, 1), (1, 2), (1, 3), (2, 4), (2, 5), (2, 6);

SELECT i, j, partitionId(i), _partition_id FROM tab ORDER BY i, j;

┌─i─┬─j─┬─partitionId(i)─┬─_partition_id─┐
│ 1 │ 1 │ 1              │ 1             │
│ 1 │ 2 │ 1              │ 1             │
│ 1 │ 3 │ 1              │ 1             │
│ 2 │ 4 │ 2              │ 2             │
│ 2 │ 5 │ 2              │ 2             │
│ 2 │ 6 │ 2              │ 2             │
└───┴───┴────────────────┴───────────────┘

pgGetUserById

أُضيف في: v26.8.0

دالة توافقية لبروتوكول الاتصال PostgreSQL، وهي مماثلة لـ pg_catalog.pg_get_userbyid. يستخدمها عملاء PostgreSQL (مثل الأمر \d في psql) لعرض مالك الجدول. لا يتتبع ClickHouse ملكية الجداول، لذا تتجاهل الدالة الوسيطة وتُرجع اسم المستخدم الحالي.

البنية

pgGetUserById(oid)

الأسماء المستعارة: pg_get_userbyid

الوسيطات

oid — معرّف كائن الدور. تُتجاهل القيمة. UInt32

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

يعيد اسم المستخدم الحالي. String

أمثلة

مثال على الاستخدام

SELECT pg_get_userbyid(10)

┌─pg_get_userbyid(10)─┐
│ default             │
└─────────────────────┘

pgTableIsVisible

أُضيف في: v26.8.0

دالة توافق مع بروتوكول الاتصال PostgreSQL، وهي نظير للدالة pg_catalog.pg_table_is_visible. تستخدمها عميل PostgreSQL (مثل الأمر \d في psql) لتصفية الجداول الظاهرة في مسار البحث. ونظرًا لأن العرض pg_class الذي يحاكيه ClickHouse لا يكشف إلا عن جداول قاعدة البيانات الحالية، وجميعها ظاهرة، فإن الدالة تُرجع دائمًا 1.

الصياغة

pgTableIsVisible(oid)

الأسماء البديلة: pg_table_is_visible

الوسيطات

oid — معرّف كائن الجدول، كما هو معروض في طريقة العرض المحاكية pg_class. تُتجاهل القيمة. UInt32

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

تُرجع دائمًا 1. UInt8

أمثلة

مثال على الاستخدام

SELECT pg_table_is_visible(0)

┌─pg_table_is_visible(0)─┐
│                      1 │
└────────────────────────┘

queryID

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

يُرجع معرّف الاستعلام الحالي. يمكن استخراج المعلمات الأخرى للاستعلام من الحقل query_id في الجدول system.query_log.

بخلاف الدالة initialQueryID، قد تُرجع queryID نتائج مختلفة على المقاطع المختلفة.

البنية

queryID()

الأسماء المستعارة: query_id

المعاملات

لا شيء.

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

يُرجع معرّف الاستعلام الحالي. String

أمثلة

مثال على الاستخدام

CREATE TABLE tmp (str String) ENGINE = Log;
INSERT INTO tmp (*) VALUES ('a');
SELECT count(DISTINCT t) FROM (SELECT queryID() AS t FROM remote('127.0.0.{1..3}', currentDatabase(), 'tmp') GROUP BY queryID());

┌─countDistinct(t)─┐
│                3 │
└──────────────────┘

revision

قُدِّم في: v22.7.0

يُرجع رقم مراجعة خادم ClickHouse الحالي.

البنية

revision()

الوسائط

لا شيء.

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

يعيد رقم المراجعة الحالي لخادم ClickHouse. UInt32

أمثلة

مثال على الاستخدام

SELECT revision()

┌─revision()─┐
│      54485 │
└────────────┘

rowNumberInAllBlocks

أُضيف في: v1.1.0

يعيد رقم صف فريدًا لكل صف مُعالَج.

الصيغة

rowNumberInAllBlocks()

المعاملات

لا شيء.

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

تُرجع الرقم الترتيبي للصف في كتلة البيانات ابتداءً من 0. UInt64

أمثلة

مثال على الاستخدام

-- The data is processed in blocks of two rows: rowNumberInBlock restarts from 0 in every block,
-- while rowNumberInAllBlocks keeps counting across them.
SELECT
    number,
    rowNumberInBlock(),
    rowNumberInAllBlocks()
FROM system.numbers
LIMIT 6
SETTINGS max_block_size = 2

┌─number─┬─rowNumberInBlock()─┬─rowNumberInAllBlocks()─┐
│      0 │                  0 │                      0 │
│      1 │                  1 │                      1 │
│      2 │                  0 │                      2 │
│      3 │                  1 │                      3 │
│      4 │                  0 │                      4 │
│      5 │                  1 │                      5 │
└────────┴────────────────────┴────────────────────────┘

rowNumberInBlock

أُضيف في: v1.1.0

بالنسبة إلى كل كتلة يعالجها rowNumberInBlock، تُرجِع الدالة رقم الصف الحالي.

يبدأ الرقم المُعاد من 0 في كل كتلة.

الصيغة

rowNumberInBlock()

المعاملات

لا شيء.

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

تُرجِع الرقم الترتيبي للصف في كتلة البيانات ابتداءً من 0. UInt64

أمثلة

مثال على الاستخدام

SELECT rowNumberInBlock()
FROM
(
    SELECT *
    FROM system.numbers_mt
    LIMIT 10
) SETTINGS max_block_size = 2

┌─rowNumberInBlock()─┐
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
│                  0 │
│                  1 │
└────────────────────┘

runningAccumulate

أُضيفت في: v1.1.0

تُراكم حالات دالة تجميع لكل صف ضمن كتلة بيانات.

الصيغة

runningAccumulate(agg_state[, grouping])

المعاملات

agg_state — حالة الدالة التجميعية. AggregateFunction
grouping — اختياري. مفتاح التجميع. تُعاد تهيئة حالة الدالة إذا تغيّرت قيمة grouping. ويمكن أن يكون من أيٍّ من أنواع البيانات المدعومة التي يكون فيها عامل المساواة معرّفًا. Any

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

تعيد النتيجة المتراكمة لكل صف. Any

أمثلة

مثال على الاستخدام مع initializeAggregation

SET allow_deprecated_error_prone_window_functions = 1;
WITH initializeAggregation('sumState', number) AS one_row_sum_state
SELECT
    number,
    finalizeAggregation(one_row_sum_state) AS one_row_sum,
    runningAccumulate(one_row_sum_state) AS cumulative_sum
FROM numbers(5);

┌─number─┬─one_row_sum─┬─cumulative_sum─┐
│      0 │           0 │              0 │
│      1 │           1 │              1 │
│      2 │           2 │              3 │
│      3 │           3 │              6 │
│      4 │           4 │             10 │
└────────┴─────────────┴────────────────┘

runningConcurrency

استُحدث في: v21.3.0

يحسب عدد الأحداث المتزامنة. لكل حدث وقت بداية ووقت نهاية. يُحتسب وقت البداية ضمن الحدث، بينما لا يُحتسب وقت النهاية. يجب أن تكون الأعمدة التي تتضمن وقت بداية ووقت نهاية من نوع البيانات نفسه. تحسب الدالة العدد الإجمالي للأحداث النشطة (المتزامنة) لكل وقت بداية حدث.

الصيغة

runningConcurrency(start, end)

المعاملات

start — عمود يحتوي على وقت بدء الأحداث. Date أو DateTime أو DateTime64
end — عمود يحتوي على وقت انتهاء الأحداث. Date أو DateTime أو DateTime64

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

يعيد عدد الأحداث المتزامنة عند وقت بدء كل حدث. UInt32

أمثلة

مثال على الاستخدام

CREATE TABLE example_table (start Date, end Date) ENGINE = Memory;
INSERT INTO example_table VALUES ('2025-03-03', '2025-03-11'), ('2025-03-06', '2025-03-08'), ('2025-03-07', '2025-03-09'), ('2025-03-11', '2025-03-12');

SELECT start, runningConcurrency(start, end) FROM example_table;

┌──────start─┬─runningConcurrency(start, end)─┐
│ 2025-03-03 │                              1 │
│ 2025-03-06 │                              2 │
│ 2025-03-07 │                              3 │
│ 2025-03-11 │                              1 │
└────────────┴────────────────────────────────┘

runningDifference

قُدِّمت في: v1.1.0

تحسب الفرق بين قيمتَي صفّين متتاليين داخل كتلة البيانات. وتُرجِع 0 للصف الأول، أما الصفوف اللاحقة فتُرجِع الفرق مقارنةً بالصف السابق.

تعتمد نتيجة الدالة على كتل البيانات المعنية وترتيب البيانات داخل الكتلة. وقد يختلف ترتيب الصفوف أثناء حساب runningDifference() عن ترتيب الصفوف المُعادة إلى المستخدم. ولتجنّب ذلك، يمكنك إنشاء استعلام فرعي باستخدام ORDER BY ثم استدعاء الدالة من خارج هذا الاستعلام الفرعي. يرجى ملاحظة أن حجم الكتلة يؤثر في النتيجة. تُعاد تهيئة الحالة الداخلية للدالة runningDifference مع كل كتلة جديدة.

الصيغة

runningDifference(x)

المعاملات

x — العمود الذي يُحسب له الفرق التراكمي. Any

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

يعيد الفرق بين كل قيمتين متتاليتين، وتكون القيمة 0 في الصف الأول.

أمثلة

مثال على الاستخدام

SET allow_deprecated_error_prone_window_functions = 1;

CREATE TABLE events
(
    EventID UInt32,
    EventDate Date,
    EventTime DateTime
)
ENGINE = Memory;

INSERT INTO events VALUES
    (1106, '2025-11-24', '2025-11-24 00:00:04'),
    (1107, '2025-11-24', '2025-11-24 00:00:05'),
    (1108, '2025-11-24', '2025-11-24 00:00:05'),
    (1109, '2025-11-24', '2025-11-24 00:00:09'),
    (1110, '2025-11-24', '2025-11-24 00:00:10');

SELECT
    EventID,
    EventTime,
    runningDifference(EventTime) AS delta
FROM
(
    SELECT
        EventID,
        EventTime
    FROM events
    WHERE EventDate = '2025-11-24'
    ORDER BY EventTime ASC, EventID ASC
    LIMIT 5
);

┌─EventID─┬───────────EventTime─┬─delta─┐
│    1106 │ 2025-11-24 00:00:04 │     0 │
│    1107 │ 2025-11-24 00:00:05 │     1 │
│    1108 │ 2025-11-24 00:00:05 │     0 │
│    1109 │ 2025-11-24 00:00:09 │     4 │
│    1110 │ 2025-11-24 00:00:10 │     1 │
└─────────┴─────────────────────┴───────┘

مثال على تأثير حجم الكتلة

SET allow_deprecated_error_prone_window_functions = 1;
SELECT
    number,
    runningDifference(number + 1) AS diff
FROM numbers(100000)
WHERE diff != 1;

┌─number─┬─diff─┐
│      0 │    0 │
│  65409 │    0 │
└────────┴──────┘

runningDifferenceStartingWithFirstValue

أُضيفت في: v1.1.0

تحسب الفرق بين قيم الصفوف المتتالية في كتلة بيانات، ولكن بخلاف runningDifference، فإنها تُرجع القيمة الفعلية للصف الأول بدلًا من 0.

الصيغة

runningDifferenceStartingWithFirstValue(x)

المعاملات

x — العمود المراد حساب الفرق التراكمي له. Any

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

يعيد الفرق بين القيم المتتالية، وتكون قيمة الصف الأول هي قيمة الصف الأول نفسها. Any

أمثلة

مثال على الاستخدام

SET allow_deprecated_error_prone_window_functions = 1;
SELECT
    number,
    runningDifferenceStartingWithFirstValue(number) AS diff
FROM numbers(5);

┌─number─┬─diff─┐
│      0 │    0 │
│      1 │    1 │
│      2 │    1 │
│      3 │    1 │
│      4 │    1 │
└────────┴──────┘

serverUUID

أُضيف في: v20.1.0

يعيد معرّف UUID (v4) عشوائيًا وفريدًا يُولَّد عند بدء تشغيل الخادم لأول مرة. ويُحفَظ هذا المعرّف، أي إن تشغيل الخادم للمرة الثانية أو الثالثة أو ما بعدها يعيد معرّف UUID نفسه.

الصيغة

serverUUID()

المعاملات

لا توجد.

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

يُرجع معرّف UUID عشوائيًا للخادم. UUID

أمثلة

مثال على الاستخدام

SELECT serverUUID();

┌─serverUUID()─────────────────────────────┐
│ 7ccc9260-000d-4d5c-a843-5459abaabb5f     │
└──────────────────────────────────────────┘

shardCount

استُحدث في: v21.9.0

يعيد العدد الإجمالي للشظايا في الاستعلام الموزع. إذا لم يكن الاستعلام موزعًا، فستُعاد القيمة الثابتة 0.

الصيغة

shardCount()

المعاملات

لا شيء.

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

يُرجع العدد الإجمالي للشظايا أو 0. UInt32

أمثلة

مثال على الاستخدام

-- See shardNum() example above which also demonstrates shardCount()
CREATE TABLE shard_count_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT shardCount() FROM shard_count_example;

┌─shardCount()─┐
│            2 │
│            2 │
└──────────────┘

shardNum

تم تقديمه في: v21.9.0

يعيد فهرس الشظية التي تعالج جزءًا من البيانات في استعلام موزّع. تبدأ الفهارس من 1. إذا لم يكن الاستعلام موزّعًا، فستُعاد قيمة ثابتة هي 0.

الصيغة

shardNum()

المعاملات

لا يوجد.

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

تعيد فهرس الشظية أو القيمة الثابتة 0. UInt32

أمثلة

مثال على الاستخدام

CREATE TABLE shard_num_example (dummy UInt8)
ENGINE=Distributed(test_cluster_two_shards_localhost, system, one, dummy);
SELECT dummy, shardNum(), shardCount() FROM shard_num_example;

┌─dummy─┬─shardNum()─┬─shardCount()─┐
│     0 │          1 │            2 │
│     0 │          2 │            2 │
└───────┴────────────┴──────────────┘

showCertificate

أُضيف في: v22.6.0

يعرض معلومات عن شهادة SSL الخاصة بالخادم الحالي إذا كانت مُهيّأة. تُعاد خريطة فارغة إذا لم تكن لدى الخادم شهادة، على سبيل المثال، عندما تُوفَّر الشهادة باستخدام ACME ولم تُصدر بعد. راجع إعداد TLS لمزيد من المعلومات حول كيفية إعداد ClickHouse لاستخدام شهادات OpenSSL للتحقق من الاتصالات.

الصيغة

showCertificate()

وسيطات الدالة

لا شيء.

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

تعيد خريطةً من أزواج المفتاح والقيمة المرتبطة بشهادة SSL المُعدّة. Map(String, String)

أمثلة

مثال على الاستخدام

SELECT showCertificate() FORMAT LineAsString;

{'version':'1','serial_number':'2D9071D64530052D48308473922C7ADAFA85D6C5','signature_algo':'sha256WithRSAEncryption','issuer':'/CN=marsnet.local CA','not_before':'May  7 17:01:21 2024 GMT','not_after':'May  7 17:01:21 2025 GMT','subject':'/CN=chnode1','pkey_algo':'rsaEncryption'}

sleep

قُدِّمت في: v1.1.0

توقف تنفيذ الاستعلام مؤقتًا لمدة عدد الثواني المحدد. تُستخدم هذه الدالة أساسًا لأغراض الاختبار واستكشاف الأخطاء وإصلاحها.

بوجه عام، لا ينبغي استخدام الدالة sleep() في بيئات production، لأنها قد تؤثر سلبًا في أداء الاستعلام واستجابة النظام. ومع ذلك، قد تكون مفيدة في السيناريوهات التالية:

الاختبار: عند اختبار ClickHouse أو إجراء benchmarking له، قد ترغب في محاكاة حالات تأخير أو إدخال توقفات مؤقتة لملاحظة كيفية تصرف النظام في ظروف معينة.
استكشاف الأخطاء وإصلاحها: إذا كنت بحاجة إلى فحص حالة النظام أو تنفيذ استعلام عند نقطة زمنية محددة، فيمكنك استخدام sleep() لإدخال توقف مؤقت، مما يتيح لك فحص المعلومات ذات الصلة أو جمعها.
المحاكاة: في بعض الحالات، قد ترغب في محاكاة سيناريوهات واقعية تحدث فيها حالات تأخير أو توقفات مؤقتة، مثل كمون الشبكة أو اعتماديات الأنظمة الخارجية.

لأسباب أمنية، لا يمكن تنفيذ هذه الدالة إلا ضمن ملف تعريف المستخدم default (مع تفعيل allow_sleep).

الصيغة

sleep(seconds)

المعاملات

seconds — عدد الثواني المطلوب إيقاف تنفيذ الاستعلام مؤقتًا خلالها، بحد أقصى 3 ثوانٍ. ويمكن أن تكون قيمة ذات فاصلة عائمة لتحديد أجزاء من الثانية. const UInt* أو const Float*

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

يعيد 0. UInt8

أمثلة

مثال على الاستخدام

-- This query will pause for 2 seconds before completing.
-- During this time, no results will be returned, and the query will appear to be hanging or unresponsive.
SELECT sleep(2);

┌─sleep(2)─┐
│        0 │
└──────────┘

sleepEachRow

أُضيفت في: v1.1.0

توقف تنفيذ الاستعلام لعدد محدد من الثواني لكل صف في مجموعة النتائج.

تُستخدم الدالة sleepEachRow() بشكل أساسي لأغراض الاختبار وتصحيح الأخطاء، على غرار الدالة sleep(). وتتيح لك محاكاة حالات التأخير أو إدخال توقفات مؤقتة أثناء معالجة كل صف، مما قد يكون مفيدًا في سيناريوهات مثل:

الاختبار: عند اختبار أداء ClickHouse أو إجراء اختبارات قياس الأداء له في ظل ظروف محددة، يمكنك استخدام sleepEachRow() لمحاكاة حالات التأخير أو إدخال توقفات مؤقتة لكل صف تتم معالجته.
تصحيح الأخطاء: إذا كنت بحاجة إلى فحص حالة النظام أو تنفيذ الاستعلام لكل صف تتم معالجته، فيمكنك استخدام sleepEachRow() لإدخال توقفات مؤقتة، مما يتيح لك فحص المعلومات ذات الصلة أو جمعها.
المحاكاة: في بعض الحالات، قد ترغب في محاكاة سيناريوهات واقعية تحدث فيها حالات تأخير أو توقفات مؤقتة لكل صف تتم معالجته، مثل عند التعامل مع أنظمة خارجية أو زمن الاستجابة على الشبكة.

الصيغة

sleepEachRow(seconds)

المعاملات

seconds — عدد الثواني التي يُوقَف فيها تنفيذ الاستعلام مؤقتًا لكل صف في مجموعة النتائج، بحد أقصى 3 ثوانٍ. ويمكن أن تكون قيمة فاصلة عائمة لتحديد أجزاء من الثانية. const UInt* أو const Float*

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

يعيد 0 لكل صف. UInt8

أمثلة

مثال على الاستخدام

-- The output will be delayed, with a 0.5-second pause between each row.
SELECT number, sleepEachRow(0.5) FROM system.numbers LIMIT 5;

┌─number─┬─sleepEachRow(0.5)─┐
│      0 │                 0 │
│      1 │                 0 │
│      2 │                 0 │
│      3 │                 0 │
│      4 │                 0 │
└────────┴───────────────────┘

structureToCapnProtoSchema

أُضيفت في: v23.8.0

دالة تُحوِّل بنية جدول ClickHouse إلى مخطط schema بتنسيق CapnProto

الصيغة

structureToCapnProtoSchema(table_structure, message)

الوسائط

لا شيء.

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

أمثلة

random

SELECT structureToCapnProtoSchema('s String, x UInt32', 'MessageName') format TSVRaw

struct MessageName
{
    s @0 : Data;
    x @1 : UInt32;
}

structureToProtobufSchema

أُضيفت في: v23.8.0

تحوّل بنية جدول ClickHouse إلى مخطط بتنسيق Protobuf.

تأخذ هذه الدالة تعريف بنية جدول ClickHouse وتحوله إلى تعريف مخطط Protocol Buffers ‏(Protobuf) بصياغة proto3. وهذا مفيد لإنشاء مخططات Protobuf تتوافق مع بُنى جداول ClickHouse لتبادل البيانات.

الصيغة

structureToProtobufSchema(structure, message_name)

المعاملات

structure — تعريف بنية جدول ClickHouse كسلسلة نصية (على سبيل المثال: 'column1 Type1, column2 Type2'). String
message_name — اسم نوع رسالة Protobuf في المخطط المُنشأ. String

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

يُرجع تعريفًا لمخطط Protobuf بصيغة proto3 يتوافق مع بنية ClickHouse المُدخلة. String

أمثلة

تحويل بنية ClickHouse إلى مخطط Protobuf

SELECT structureToProtobufSchema('s String, x UInt32', 'MessageName') FORMAT TSVRaw;

syntax = "proto3";

message MessageName
{
    bytes s = 1;
    uint32 x = 2;
}

tcpPort

أُضيفت في: v20.12.0

تعيد رقم منفذ TCP الخاص بـ الواجهة الأصلية الذي يستمع عليه الخادم. إذا نُفِّذت في سياق جدول موزّع، فستُنشئ هذه الدالة عمودًا عاديًا بقيم مرتبطة بكل شظية. وإلا، فإنها تُنتج قيمة ثابتة.

الصيغة

tcpPort()

المعاملات

لا توجد.

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

يُرجع رقم منفذ TCP. UInt16

أمثلة

مثال على الاستخدام

SELECT tcpPort()

┌─tcpPort()─┐
│      9000 │
└───────────┘

throwIf

قُدِّمت في: v1.1.0

يطرح استثناءً إذا كانت الوسيطة x تساوي true. لاستخدام الوسيطة error_code، يجب تمكين معلمة الإعداد allow_custom_error_code_in_throw.

الصيغة

throwIf(x[, message[, error_code]])

الوسيطات

x — الشرط المطلوب التحقق منه. Any
message — اختياري. رسالة خطأ مخصّصة. const String
error_code — اختياري. رمز خطأ مخصّص. const Int8/16/32

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

يعيد 0 إذا كان الشرط false، ويُطلق استثناءً إذا كان الشرط true. UInt8

أمثلة

مثال على الاستخدام

SELECT throwIf(number = 3, 'Too many') FROM numbers(10);

Received exception:
Code: 395. DB::Exception: Too many. (FUNCTION_THROW_IF_VALUE_IS_NON_ZERO)

toColumnTypeName

أُضيف في: v1.1.0

يعيد الاسم الداخلي لنوع بيانات القيمة المحددة. وعلى خلاف الدالة toTypeName، قد يشمل نوع البيانات المُعاد أعمدة مُغلِّفة داخلية مثل Const وLowCardinality.

الصيغة

toColumnTypeName(value)

المعاملات

value — القيمة التي يُراد إرجاع نوع البيانات الداخلي الخاص بها. Any

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

يُرجع نوع البيانات الداخلي المستخدم لتمثيل القيمة. String

أمثلة

مثال على الاستخدام

SELECT toColumnTypeName(CAST('2025-01-01 01:02:03' AS DateTime));

┌─toColumnTypeName(CAST('2025-01-01 01:02:03', 'DateTime'))─┐
│ Const(UInt32)                                             │
└───────────────────────────────────────────────────────────┘

toTypeName

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

يعيد اسم النوع للوسيطة المُمرَّرة. إذا تم تمرير NULL، فستُعيد الدالة النوع Nullable(Nothing)، وهو ما يقابل التمثيل الداخلي للقيمة NULL في ClickHouse.

البنية

toTypeName(x)

الوسائط

x — قيمة من أي نوع. Any

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

يُرجع اسم نوع بيانات قيمة الإدخال. String

أمثلة

مثال على الاستخدام

SELECT toTypeName(123)

┌─toTypeName(123)─┐
│ UInt8           │
└─────────────────┘

tokenizeQuery

استُحدث في: v26.5.0

يُجزِّئ سلسلة استعلام ClickHouse SQL إلى رموز ويُعيد مصفوفة من الرموز. كل رمز عبارة عن named tuple يتضمن موضع البداية (بالبايت)، وموضع النهاية، ونوع الرمز.

البنية

tokenizeQuery(query)

الوسائط

query — سلسلة استعلام في ClickHouse SQL. String.

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

مصفوفة من قيم Tuple مُسمّاة (begin UInt64, end UInt64, type Enum8(...)) تمثل توكنات الاستعلام. Array(Tuple(begin UInt64, end UInt64, type Enum8(...)))

أمثلة

بسيط

SELECT tokenizeQuery('SELECT 1')

[(0,6,'BareWord'),(6,7,'Whitespace'),(7,8,'Number')]

transactionID

أُضيف في: v22.6.0

ميزة تجريبية

غير مدعوم في ClickHouse Cloud

تُرجِع معرّف المعاملة.

Note

هذه الدالة جزء من مجموعة ميزات تجريبية. فعِّل دعم المعاملات التجريبي بإضافة هذا الإعداد إلى التهيئة:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

لمزيد من المعلومات، راجع صفحة دعم المعاملات (ACID).

الصيغة

transactionID()

الوسائط

لا شيء.

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

تُرجِع قيمة من النوع Tuple تتكوّن من start_csn وlocal_tid وhost_id.

start_csn: رقم تسلسلي عام، وهو أحدث طابع زمني لعملية commit تمت ملاحظته عند بدء هذه المعاملة.
local_tid: رقم تسلسلي محلي فريد لكل معاملة يبدأها هذا المضيف ضمن start_csn محدد.
host_id: معرّف UUID للمضيف الذي بدأ هذه المعاملة. Tuple(UInt64, UInt64, UUID)

أمثلة

مثال على الاستخدام

BEGIN TRANSACTION;
SELECT transactionID();
ROLLBACK;

┌─transactionID()────────────────────────────────┐
│ (32,34,'0ee8b069-f2bb-4748-9eae-069c85b5252b') │
└────────────────────────────────────────────────┘

transactionLatestSnapshot

أُضيف في: v22.6.0

ميزة تجريبية

غير مدعوم في ClickHouse Cloud

تعيد أحدث لقطة (Commit Sequence Number) لـ معاملة المتاحة للقراءة.

Note

هذه الدالة جزء من مجموعة ميزات تجريبية. فعِّل دعم المعاملات التجريبي بإضافة هذا الإعداد إلى التهيئة:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

لمزيد من المعلومات، راجع صفحة دعم المعاملات (ACID).

الصيغة

transactionLatestSnapshot()

الوسائط

لا شيء.

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

يُرجع أحدث لقطة (CSN) لمعاملة. UInt64

أمثلة

مثال على الاستخدام

BEGIN TRANSACTION;
SELECT transactionLatestSnapshot();
ROLLBACK;

┌─transactionLatestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transactionOldestSnapshot

تم تقديمه في: v22.6.0

ميزة تجريبية

غير مدعوم في ClickHouse Cloud

تُرجع أقدم لقطة (Commit Sequence Number) تكون مرئية لإحدى المعاملات الجارية.

Note

هذه الدالة جزء من مجموعة ميزات تجريبية. فعِّل دعم المعاملات التجريبي بإضافة هذا الإعداد إلى التهيئة الخاصة بك:

<clickhouse>
    <allow_experimental_transactions>1</allow_experimental_transactions>
</clickhouse>

لمزيد من المعلومات، راجع صفحة دعم المعاملات (ACID).

البنية

transactionOldestSnapshot()

الوسائط

لا شيء.

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

تُعيد أقدم لقطة (CSN) لمعاملة. UInt64

أمثلة

مثال على الاستخدام

BEGIN TRANSACTION;
SELECT transactionOldestSnapshot();
ROLLBACK;

┌─transactionOldestSnapshot()─┐
│                          32 │
└─────────────────────────────┘

transform

قُدِّمت في: v1.1.0

تحوِّل قيمةً وفق تعيين مُعرَّف صراحةً لبعض العناصر إلى عناصر أخرى.

لهذه الدالة صيغتان:

transform(x, array_from, array_to, default) - تحوِّل x باستخدام مصفوفتَي تعيين مع قيمة default للعناصر غير المتطابقة
transform(x, array_from, array_to) - التحويل نفسه، لكنها تعيد x الأصلي إذا لم يُعثر على أي تطابق

تبحث الدالة عن x في array_from وتعيد العنصر المقابل من array_to عند الفهرس نفسه. إذا لم يُعثر على x في array_from، فإنها تعيد إما قيمة default (في نسخة المعاملات الأربعة) أو x الأصلي (في نسخة المعاملات الثلاثة). إذا وُجدت عدة عناصر متطابقة في array_from، فإنها تعيد العنصر المقابل لأول تطابق.

المتطلبات:

يجب أن يحتوي array_from وarray_to على العدد نفسه من العناصر
لنسخة المعاملات الأربعة: transform(T, Array(T), Array(U), U) -> U حيث يمكن أن يكون T وU نوعين مختلفين لكن متوافقين
لنسخة المعاملات الثلاثة: transform(T, Array(T), Array(T)) -> T حيث يجب أن تكون جميع الأنواع متماثلة

الصيغة

transform(x, array_from, array_to[, default])

الوسيطات

x — القيمة المطلوب تحويلها. (U)Int* أو Decimal أو Float* أو String أو Date أو DateTime
array_from — مصفوفة ثابتة من القيم للبحث عن القيم المطابقة فيها. Array((U)Int*) أو Array(Decimal) أو Array(Float*) أو Array(String) أو Array(Date) أو Array(DateTime)
array_to — مصفوفة ثابتة من القيم لإرجاع القيم المناظرة للعناصر المطابقة في array_from. Array((U)Int*) أو Array(Decimal) أو Array(Float*) أو Array(String) أو Array(Date) أو Array(DateTime)
default — اختياري. القيمة التي تُعاد إذا لم يتم العثور على x في array_from. إذا لم يتم تحديده، فستُعاد x كما هي. (U)Int* أو Decimal أو Float* أو String أو Date أو DateTime

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

تُعيد القيمة المناظرة من array_to إذا كانت x تطابق عنصرًا في array_from، وإلا فتُعيد default (إذا تم تحديده) أو x (إذا لم يتم تحديد default). Any

أمثلة

transform(T, Array(T), Array(U), U) -> U

CREATE TABLE hits (SearchEngineID UInt8, Referer String) ENGINE = Memory;

INSERT INTO hits VALUES
    (2, 'http://yandex.ru/search'),
    (2, 'http://yandex.ru/news'),
    (2, 'http://mail.yandex.ru/'),
    (3, 'http://google.ru/search'),
    (4, 'http://duckduckgo.com/'),
    (0, 'http://vkontakte.ru/feed'),
    (0, '');

SELECT
transform(SearchEngineID, [2, 3], ['Yandex', 'Google'], 'Other') AS title,
count() AS c
FROM hits
WHERE SearchEngineID != 0
GROUP BY title
ORDER BY c DESC, title

┌─title──┬─c─┐
│ Yandex │ 3 │
│ Google │ 1 │
│ Other  │ 1 │
└────────┴───┘

transform(T, Array(T), Array(T)) -> T

-- Without a default, a domain that is not listed is returned unchanged.
SELECT
transform(domain(Referer), ['yandex.ru', 'google.ru', 'vkontakte.ru'], ['www.yandex', 'example.com', 'vk.com']) AS s, count() AS c
FROM hits
GROUP BY domain(Referer)
ORDER BY count() DESC, s
LIMIT 10

┌─s──────────────┬─c─┐
│ www.yandex     │ 2 │
│                │ 1 │
│ duckduckgo.com │ 1 │
│ example.com    │ 1 │
│ mail.yandex.ru │ 1 │
│ vk.com         │ 1 │
└────────────────┴───┘

uniqThetaIntersect

طُرح في: v22.9.0

يُستخدم كائنان من نوع uniqThetaSketch لإجراء عملية التقاطع (عملية المجموعات ∩)، وتكون النتيجة كائن uniqThetaSketch جديدًا.

الصيغة

uniqThetaIntersect(uniqThetaSketch,uniqThetaSketch)

الوسيطات

uniqThetaSketch — كائن uniqThetaSketch. Tuple أو Array أو Date أو DateTime أو String أو (U)Int* أو Float* أو Decimal

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

كائن uniqThetaSketch جديد يحتوي على ناتج التقاطع. UInt64

أمثلة

مثال على الاستخدام

SELECT finalizeAggregation(uniqThetaIntersect(a, b)) AS a_intersect_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_intersect_b─┬─a_cardinality─┬─b_cardinality─┐
│             1 │             2 │             3 │
└───────────────┴───────────────┴───────────────┘

uniqThetaNot

قُدِّم في: v22.9.0

كائنان من نوع uniqThetaSketch لإجراء العملية الحسابية a_not_b (عملية على المجموعات ×)، وتكون النتيجة كائن uniqThetaSketch جديدًا.

الصيغة

uniqThetaNot(uniqThetaSketch,uniqThetaSketch)

الوسيطات

uniqThetaSketch — كائن uniqThetaSketch. Tuple أو Array أو Date أو DateTime أو String أو (U)Int* أو Float* أو Decimal

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

يعيد كائن uniqThetaSketch جديدًا يحتوي على نتيجة a_not_b. UInt64

أمثلة

مثال للاستخدام

SELECT finalizeAggregation(uniqThetaNot(a, b)) AS a_not_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [2, 3, 4]) AS a, arrayReduce('uniqThetaState', [1, 2]) AS b);

┌─a_not_b─┬─a_cardinality─┬─b_cardinality─┐
│       2 │             3 │             2 │
└─────────┴───────────────┴───────────────┘

uniqThetaUnion

أُضيف في: v22.9.0

كائنان من نوع uniqThetaSketch لإجراء عملية الاتحاد (عملية مجموعات ∪)، وتكون النتيجة uniqThetaSketch جديدًا.

الصيغة

uniqThetaUnion(uniqThetaSketch,uniqThetaSketch)

الوسيطات

uniqThetaSketch — كائن uniqThetaSketch. Tuple أو Array أو Date أو DateTime أو String أو (U)Int* أو Float* أو Decimal

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

يُرجع كائن uniqThetaSketch جديدًا يحتوي على نتيجة الاتحاد. UInt64

أمثلة

مثال على الاستخدام

SELECT finalizeAggregation(uniqThetaUnion(a, b)) AS a_union_b, finalizeAggregation(a) AS a_cardinality, finalizeAggregation(b) AS b_cardinality
FROM
(SELECT arrayReduce('uniqThetaState', [1, 2]) AS a, arrayReduce('uniqThetaState', [2, 3, 4]) AS b);

┌─a_union_b─┬─a_cardinality─┬─b_cardinality─┐
│         4 │             2 │             3 │
└───────────┴───────────────┴───────────────┘

مدة التشغيل

أُضيف في: v1.1.0

يعيد مدة تشغيل الخادم بالثواني. إذا نُفِّذت هذه الدالة في سياق جدول موزّع، فإنها تُنشئ عمودًا عاديًا بقيم مرتبطة بكل جزء. أما خلاف ذلك، فتنتج قيمة ثابتة.

الصيغة

uptime()

الوسائط

لا يوجد.

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

يُرجع مدة تشغيل الخادم بالثواني. UInt32

أمثلة

مثال على الاستخدام

SELECT uptime() AS Uptime

┌─Uptime─┐
│  55867 │
└────────┘

variantElement

أُضيفت في: v25.2.0

تستخرج عمودًا من النوع المحدد من عمود Variant.

البنية

variantElement(variant, type_name[, default_value])

المعاملات

variant — عمود Variant. Variant
type_name — اسم نوع Variant المراد استخراجه. String
default_value — القيمة الافتراضية التي ستُستخدم إذا لم يتضمّن variant نوع Variant المحدد. يمكن أن تكون من أي نوع. اختياري. Any

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

يعيد عمودًا يحتوي على نوع Variant المحدد بعد استخراجه من عمود Variant. Any

أمثلة

مثال على الاستخدام

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT v, variantElement(v, 'String'), variantElement(v, 'UInt64'), variantElement(v, 'Array(UInt64)') FROM test;

┌─v─────────────┬─variantElement(v, 'String')─┬─variantElement(v, 'UInt64')─┬─variantElement(v, 'Array(UInt64)')─┐
│ ᴺᵁᴸᴸ          │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ []                                 │
│ 42            │ ᴺᵁᴸᴸ                        │                          42 │ []                                 │
│ Hello, World! │ Hello, World!               │                        ᴺᵁᴸᴸ │ []                                 │
│ [1,2,3]       │ ᴺᵁᴸᴸ                        │                        ᴺᵁᴸᴸ │ [1,2,3]                            │
└───────────────┴─────────────────────────────┴─────────────────────────────┴────────────────────────────────────┘

variantType

قُدِّم في: v24.2.0

يعيد اسم النوع المتغيّر لكل صف في عمود Variant. وإذا احتوى الصف على NULL، فستُعاد له القيمة 'None'.

الصيغة

variantType(variant)

الوسائط

variant — عمود Variant. Variant

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

يُرجع عمودًا من نوع Enum يحتوي على اسم نوع Variant لكل صف. Enum

أمثلة

مثال على الاستخدام

CREATE TABLE test (v Variant(UInt64, String, Array(UInt64))) ENGINE = Memory;
INSERT INTO test VALUES (NULL), (42), ('Hello, World!'), ([1, 2, 3]);
SELECT variantType(v) FROM test;

┌─variantType(v)─┐
│ None           │
│ UInt64         │
│ String         │
│ Array(UInt64)  │
└────────────────┘

version

أُضيف في الإصدار: v1.1.0

تعيد الإصدار الحالي من ClickHouse كسلسلة نصية بالصيغة: major_version.minor_version.patch_version.number_of_commits_since_the_previous_stable_release. إذا نُفِّذت في سياق جدول موزّع، فستُنشئ هذه الدالة عمودًا عاديًا بقيم خاصة بكل جزء. وبخلاف ذلك، فإنها تُنتج قيمة ثابتة.

الصيغة

version()

الوسائط

لا شيء.

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

يُرجع الإصدار الحالي من ClickHouse. String

أمثلة

مثال للاستخدام

SELECT version()

┌─version()─┐
│ 24.2.1.1  │
└───────────┘

visibleWidth

ظهر لأول مرة في: v1.1.0

يحسب العرض التقريبي عند إخراج القيم إلى الطرفية بتنسيق نصي (مفصول بعلامات الجدولة). تُستخدم هذه الدالة من قِبل النظام لتنفيذ تنسيقات Pretty. تُمثَّل NULL كسلسلة نصية تقابل NULL في تنسيقات Pretty.

الصيغة

visibleWidth(x)

الوسائط

x — قيمة من أي نوع بيانات. Any

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

يعيد العرض التقريبي للقيمة عند عرضها بتنسيق نصي. UInt64

أمثلة

حساب العرض المرئي لـ NULL

SELECT visibleWidth(NULL)

┌─visibleWidth(NULL)─┐
│                  4 │
└────────────────────┘

zookeeperSessionUptime

أُضيف في: v21.11.0

تعيد مدة تشغيل جلسة ZooKeeper الحالية بالثواني.

الصيغة

zookeeperSessionUptime()

الوسائط

لا شيء.

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

تُرجع مدة تشغيل جلسة ZooKeeper الحالية بالثواني. UInt32

أمثلة

مثال على الاستخدام

SELECT zookeeperSessionUptime();

┌─zookeeperSessionUptime()─┐
│                        3 │
└──────────────────────────┘