clickhouse-local - ClickHouse Documentation

متى تستخدم clickhouse-local مقابل ClickHouse

يُعد clickhouse-local إصدارًا سهل الاستخدام من ClickHouse، وهو مثالي للمطورين الذين يحتاجون إلى معالجة سريعة للملفات المحلية والبعيدة باستخدام SQL من دون الحاجة إلى تثبيت خادم قاعدة بيانات كامل. باستخدام clickhouse-local، يمكن للمطورين استخدام أوامر SQL (باستخدام لهجة ClickHouse SQL) مباشرةً من سطر الأوامر، مما يوفّر طريقة بسيطة وفعّالة للوصول إلى ميزات ClickHouse من دون الحاجة إلى تثبيت ClickHouse كامل. ومن أبرز مزايا clickhouse-local أنه يأتي مضمنًا بالفعل عند تثبيت clickhouse-client. وهذا يعني أن المطورين يمكنهم البدء باستخدام clickhouse-local بسرعة، من دون الحاجة إلى عملية تثبيت معقدة. ومع أن clickhouse-local أداة ممتازة لأغراض التطوير والاختبار ومعالجة الملفات، فإنه غير مناسب لخدمة المستخدمين النهائيين أو التطبيقات. في هذه الحالات، يُوصى باستخدام ClickHouse مفتوح المصدر. ClickHouse هو قاعدة بيانات OLAP قوية صُممت للتعامل مع أحمال العمل التحليلية واسعة النطاق. وهو يوفّر معالجة سريعة وفعّالة للاستعلامات المعقدة على مجموعات بيانات كبيرة، مما يجعله مثاليًا للاستخدام في بيئات الإنتاج التي يكون فيها الأداء العالي بالغ الأهمية. بالإضافة إلى ذلك، يوفّر ClickHouse مجموعة واسعة من الميزات مثل النسخ المتماثل والتجزئة والتوافر العالي، وهي أمور أساسية للتوسع والتعامل مع مجموعات بيانات كبيرة وخدمة التطبيقات. إذا كنت بحاجة إلى التعامل مع مجموعات بيانات أكبر أو خدمة المستخدمين النهائيين أو التطبيقات، فنوصي باستخدام ClickHouse مفتوح المصدر بدلًا من clickhouse-local. يُرجى قراءة الوثائق أدناه التي تعرض أمثلة على حالات استخدام clickhouse-local، مثل الاستعلام عن ملف محلي أو قراءة ملف Parquet في S3.

تنزيل clickhouse-local

يُشغَّل clickhouse-local باستخدام الملف التنفيذي clickhouse نفسه الذي يُشغِّل خادم ClickHouse وclickhouse-client. وأسهل طريقة لتنزيل أحدث إصدار هي استخدام الأمر التالي:

curl https://clickhouse.com/ | sh

يمكن للملف التنفيذي الذي نزّلته للتو تشغيل مختلف أدوات ClickHouse وبرامجه المساعدة. إذا كنت تريد تشغيل ClickHouse كخادم قاعدة بيانات، فراجِع Quick Start.

الاستعلام عن البيانات في ملف باستخدام SQL

من الاستخدامات الشائعة لـ clickhouse-local تشغيل استعلامات مخصّصة على الملفات، بحيث لا تحتاج إلى إدراج البيانات في جدول. ويمكن لـ clickhouse-local دفق البيانات من ملف إلى جدول مؤقت وتنفيذ أوامر SQL. إذا كان الملف موجودًا على الجهاز نفسه الذي يعمل عليه clickhouse-local، فيمكنك ببساطة تحديد الملف المراد تحميله. يحتوي ملف reviews.tsv التالي على عينة من مراجعات منتجات Amazon:

./clickhouse local -q "SELECT * FROM 'reviews.tsv'"

هذا الأمر اختصار لـ:

./clickhouse local -q "SELECT * FROM file('reviews.tsv')"

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

./clickhouse local -q "SELECT * FROM file('reviews.tsv', 'TabSeparated')"

تنشئ دالة الجدول file جدولًا، ويمكنك استخدام DESCRIBE للاطّلاع على المخطط المُستنتَج:

./clickhouse local -q "DESCRIBE file('reviews.tsv')"

يُسمح لك باستخدام globs في اسم الملف (راجع استبدالات glob).أمثلة:

./clickhouse local -q "SELECT * FROM 'reviews*.jsonl'"
./clickhouse local -q "SELECT * FROM 'review_?.csv'"
./clickhouse local -q "SELECT * FROM 'review_{1..3}.csv'"

marketplace    Nullable(String)
customer_id    Nullable(Int64)
review_id    Nullable(String)
product_id    Nullable(String)
product_parent    Nullable(Int64)
product_title    Nullable(String)
product_category    Nullable(String)
star_rating    Nullable(Int64)
helpful_votes    Nullable(Int64)
total_votes    Nullable(Int64)
vine    Nullable(String)
verified_purchase    Nullable(String)
review_headline    Nullable(String)
review_body    Nullable(String)
review_date    Nullable(Date)

لنحدّد المنتج الأعلى تقييمًا:

./clickhouse local -q "SELECT
    argMax(product_title,star_rating),
    max(star_rating)
FROM file('reviews.tsv')"

Monopoly Junior Board Game    5

الاستعلام عن البيانات في ملف Parquet على AWS S3

إذا كان لديك ملف في S3، فاستخدم clickhouse-local ودالة الجدول s3 للاستعلام عن الملف مباشرةً (من دون إدراج البيانات في جدول ClickHouse). لدينا ملف باسم house_0.parquet في حاوية عامة يحتوي على أسعار المنازل للعقارات المبيعة في المملكة المتحدة. لنرَ كم عدد الصفوف التي يحتوي عليها:

./clickhouse local -q "
SELECT count()
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

يحتوي الملف على 2.7 مليون صف:

من المفيد دائمًا الاطلاع على المخطط المستنتَج الذي يستنتجه ClickHouse من الملف:

./clickhouse local -q "DESCRIBE s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')"

price    Nullable(Int64)
date    Nullable(UInt16)
postcode1    Nullable(String)
postcode2    Nullable(String)
type    Nullable(String)
is_new    Nullable(UInt8)
duration    Nullable(String)
addr1    Nullable(String)
addr2    Nullable(String)
street    Nullable(String)
locality    Nullable(String)
town    Nullable(String)
district    Nullable(String)
county    Nullable(String)

لنرَ ما هي أكثر الأحياء تكلفةً:

./clickhouse local -q "
SELECT
    town,
    district,
    count() AS c,
    round(avg(price)) AS price,
    bar(price, 0, 5000000, 100)
FROM s3('https://datasets-documentation.s3.eu-west-3.amazonaws.com/house_parquet/house_0.parquet')
GROUP BY
    town,
    district
HAVING c >= 100
ORDER BY price DESC
LIMIT 10"

LONDON    CITY OF LONDON    886    2271305    █████████████████████████████████████████████▍
LEATHERHEAD    ELMBRIDGE    206    1176680    ███████████████████████▌
LONDON    CITY OF WESTMINSTER    12577    1108221    ██████████████████████▏
LONDON    KENSINGTON AND CHELSEA    8728    1094496    █████████████████████▉
HYTHE    FOLKESTONE AND HYTHE    130    1023980    ████████████████████▍
CHALFONT ST GILES    CHILTERN    113    835754    ████████████████▋
AMERSHAM    BUCKINGHAMSHIRE    113    799596    ███████████████▉
VIRGINIA WATER    RUNNYMEDE    356    789301    ███████████████▊
BARNET    ENFIELD    282    740514    ██████████████▊
NORTHWOOD    THREE RIVERS    184    731609    ██████████████▋

عندما تصبح جاهزًا لإدراج ملفاتك في ClickHouse، شغّل خادم ClickHouse وأدرِج نتائج دوال الجدول file وs3 في جدول من نوع MergeTree. راجع Quick Start لمزيد من التفاصيل.

تحويلات الصيغ

يمكنك استخدام clickhouse-local لتحويل البيانات بين صيغ مختلفة. مثال:

$ clickhouse-local --input-format JSONLines --output-format CSV --query "SELECT * FROM table" < data.json > data.csv

يُتعرَّف على التنسيقات تلقائيًا من امتدادات الملفات:

$ clickhouse-local --query "SELECT * FROM table" < data.json > data.csv

كاختصار، يمكنك كتابته باستخدام الوسيط --copy:

$ clickhouse-local --copy < data.json > data.csv

الاستخدام

افتراضيًا، يمكن لـ clickhouse-local الوصول إلى بيانات خادم ClickHouse على نفس المضيف، ولا يعتمد على إعدادات الخادم. كما يدعم تحميل إعدادات الخادم باستخدام الوسيط --config-file. وبالنسبة إلى البيانات المؤقتة، يُنشأ افتراضيًا دليل مؤقت فريد للبيانات. الاستخدام الأساسي (Linux):

$ clickhouse-local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

الاستخدام البسيط (Mac):

$ ./clickhouse local --structure "table_structure" --input-format "format_of_incoming_data" --query "query"

يدعم clickhouse-local أيضًا العمل على Windows عبر WSL2.

الوسيطات:

-S, --structure — بنية الجدول لبيانات الإدخال.
--input-format — تنسيق الإدخال، والافتراضي هو TSV.
-F, --file — المسار إلى البيانات، والافتراضي هو stdin.
-q, --query — الاستعلامات المطلوب تنفيذها، مع استخدام ; كفاصل. يمكن تحديد --query عدة مرات، مثل: --query "SELECT 1" --query "SELECT 2". لا يمكن استخدامه بالتزامن مع --queries-file.
--queries-file - مسار ملف يحتوي على الاستعلامات المطلوب تنفيذها. يمكن تحديد --queries-file عدة مرات، مثل: --query queries1.sql --query queries2.sql. لا يمكن استخدامه بالتزامن مع --query.
--multiquery, -n – إذا تم تحديده، يمكن إدراج عدة استعلامات مفصولة بفواصل منقوطة بعد الخيار --query. وللتسهيل، يمكن أيضًا حذف --query وتمرير الاستعلامات مباشرةً بعد --multiquery.
-N, --table — اسم الجدول الذي ستوضع فيه بيانات الإخراج، والافتراضي هو table.
-f, --format, --output-format — تنسيق الإخراج، والافتراضي هو TSV.
-d, --database — قاعدة البيانات الافتراضية، والافتراضي هو _local.
--stacktrace — ما إذا كان سيتم تفريغ مخرجات التصحيح عند حدوث استثناء.
--echo [ <bool> ] — اطبع كل استعلام قبل التنفيذ. يقبل قيمة منطقية اختيارية. يكون مفعّلًا افتراضيًا في الوضع التفاعلي ومعطّلًا في وضع الدُفعات. ملاحظة: لأن --echo يقبل الآن قيمة اختيارية، فإن أي استعلام موضعي يأتي مباشرةً بعد --echo بدون قيمة صريحة سيُعامَل على أنه قيمته؛ استخدم بدلًا من ذلك --echo --query "..." أو --echo -q "..." أو --echo=false أو stdin عبر pipe.
--echo-formatted [ <bool> ] — نسّق الاستعلامات المطبوعة عبر echo. يقبل قيمة منطقية اختيارية. يكون مفعّلًا افتراضيًا في الوضع التفاعلي ومعطّلًا في وضع الدُفعات.
--echo-query-id [ <bool> ] — اطبع query_id قبل التنفيذ. يقبل قيمة منطقية اختيارية. يكون مفعّلًا افتراضيًا في الوضع التفاعلي ومعطّلًا في وضع الدُفعات.
--echo-query-separator <string> — اطبع هذا الفاصل قبل الاستعلام المنسّق المطبوع عبر echo (يتطلب --echo-formatted)، مما يجعل من الأسهل تمييز الاستعلام المكتوب عن نسخته المعاد تنسيقها عبر echo. يكون فارغًا افتراضيًا (معطّلًا).
--highlight, --hilite <bool> — بدّل تمييز بناء الجملة في موجّه الأوامر والاستعلامات المطبوعة عبر echo. يكون مفعّلًا افتراضيًا. لا يُطبَّق التمييز إلا عند الكتابة إلى طرفية.
--hints <bool> — اعرض تلميحات الإكمال التلقائي أثناء الكتابة (نص “شبح” مضمن) لأفضل اقتراح مطابق عندما يكون المؤشر عند نهاية الإدخال. تنقّل بين التلميحات باستخدام Up/Down (أو Ctrl-Up/Ctrl-Down)؛ واقبل التلميح المضمن باستخدام Tab أو Right؛ لا يقبل Enter أي تلميح إلا بعد تحديده صراحةً، وإلا فإنه يشغّل الاستعلام؛ كما يفتح Tab أيضًا قائمة الإكمال الكلاسيكية. يتطلب --highlight (لأن التلميحات تحتاج إلى الألوان) وآلية الاقتراحات (لذا فإن --disable_suggestion يعطّلها أيضًا). يكون مفعّلًا افتراضيًا.
--verbose — مزيد من التفاصيل حول تنفيذ الاستعلام.
--logger.console — سجّل إلى وحدة التحكم.
--logger.log — اسم ملف السجل.
--logger.level — مستوى السجل.
--ignore-error — لا توقف المعالجة إذا فشل استعلام.
-c, --config-file — مسار إلى ملف التهيئة بالتنسيق نفسه المستخدم في خادم ClickHouse، ويكون ملف التهيئة فارغًا افتراضيًا.
--no-system-tables — لا تُرفق جداول النظام.
--help — مرجع الوسيطات لـ clickhouse-local.
-V, --version — اطبع معلومات الإصدار ثم اخرج.

بالإضافة إلى ذلك، توجد وسيطات لكل متغير من متغيرات تهيئة ClickHouse، ويشيع استخدامها بدلًا من --config-file.

الأوامر

أمر LS

يعرض جميع الملفات في دليل العمل الحالي التي يمكن لـ clickhouse-local الوصول إليها. يمكنك تشغيله في الوضع التفاعلي كما يلي:

Query

ClickHouse local version 26.3.1.1.

:) ls

SELECT _file AS file
FROM file('*', 'One')
ORDER BY file ASC

Response

┌─file────────┐
│ file1.csv   │
│ file2.json  │
│ file3.xml   │
└─────────────┘

يمكنك أيضًا تنفيذه كاستعلام باستخدام الوسيط -q:

./clickhouse-local -q ls

Response

file1.csv
file2.json
file3.xml

الأمر CLEAR

يمسح شاشة الطرفية (على غرار الأمر clear في Linux أو Ctrl+L في كثير من الطرفيات). هذا إجراء من جهة العميل: ولا يُرسَل إلى محرك SQL. في clickhouse-local، يُتعرَّف على هذا الأمر الوصفي في الوضع التفاعلي، وكذلك عند الإدخال عبر -q و**--queries-file** (المسار نفسه في العميل كما في -q، والفكرة نفسها كما في ls)، لذا فإن كتابة clear وحدها لا تؤدي إلى ظهور الخطأ UNKNOWN_IDENTIFIER. أما clickhouse-client --queries-file البعيد فيبقى دون تغيير: إذ يُنفَّذ محتوى الملف على أنه SQL فقط (من دون أوامر وصفية على مستوى النص). في clickhouse-client، لا يُتعرَّف عليه إلا في الوضع التفاعلي. ومع -q أو ملفات الاستعلامات، يظل clear يُفسَّر على أنه SQL، بحيث يحتفظ التشغيل الآلي بسلوك الخطأ السابق بدلًا من تحويل الأخطاء المطبعية إلى إجراء صامت بلا تأثير. الصيغ المدعومة: clear وCLEAR و/clear (تُتجاهل الفاصلة المنقوطة اللاحقة ; إن وُجدت). إذا لم يكن الإخراج القياسي طرفيةً (على سبيل المثال، عند تمرير الإخراج عبر أنبوب)، فسيُقبَل الأمر الوصفي عند التعرّف عليه، لكنه لن يُصدر تسلسلات تحكم. مع clickhouse-local و-q:

./clickhouse-local -q clear

أمثلة

Query

$ echo -e "1,2\n3,4" | clickhouse-local --structure "a Int64, b Int64" \
    --input-format "CSV" --query "SELECT * FROM table"
Read 2 rows, 32.00 B in 0.000 sec., 5182 rows/sec., 80.97 KiB/sec.
1   2
3   4

المثال السابق مماثل لما يلي:

Query

$ echo -e "1,2\n3,4" | clickhouse-local -n --query "
    CREATE TABLE table (a Int64, b Int64) ENGINE = File(CSV, stdin);
    SELECT a, b FROM table;
    DROP TABLE table;"
Read 2 rows, 32.00 B in 0.000 sec., 4987 rows/sec., 77.93 KiB/sec.
1   2
3   4

لا تحتاج إلى استخدام stdin أو الوسيطة --file، ويمكنك فتح أي عدد من الملفات باستخدام دالة الجدول file:

Query

$ echo 1 | tee 1.tsv
1

$ echo 2 | tee 2.tsv
2

$ clickhouse-local --query "
    select * from file('1.tsv', TSV, 'a int') t1
    cross join file('2.tsv', TSV, 'b int') t2"
1    2

والآن لنعرض مستخدم الذاكرة لكل مستخدم في Unix:

Query

$ ps aux | tail -n +2 | awk '{ printf("%s\t%s\n", $1, $4) }' \
    | clickhouse-local --structure "user String, mem Float64" \
        --query "SELECT user, round(sum(mem), 2) as memTotal
            FROM table GROUP BY user ORDER BY memTotal DESC FORMAT Pretty"

Response

Read 186 rows, 4.15 KiB in 0.035 sec., 5302 rows/sec., 118.34 KiB/sec.
┏━━━━━━━━━━┳━━━━━━━━━━┓
┃ user     ┃ memTotal ┃
┡━━━━━━━━━━╇━━━━━━━━━━┩
│ bayonet  │    113.5 │
├──────────┼──────────┤
│ root     │      8.8 │
├──────────┼──────────┤
...

تشغيل مستمعات TCP وHTTP

يمكن تحويل clickhouse-local إلى خادم خفيف الوزن يقبل اتصالات TCP (البروتوكول الأصلي) واتصالات HTTP. يكون هذا مفيدًا عندما تريد إتاحة الوصول إلى قواعد البيانات والجداول في مثيل clickhouse-local قيد التشغيل لأدوات أو تطبيقات ClickHouse الأخرى. لاحظ أن كل اتصال وارد يحصل على جلسة خاصة به، لذلك لا تكون الجداول المؤقتة وإعدادات مستوى الجلسة الخاصة بجلسة clickhouse-local التفاعلية مرئية للاتصالات الخارجية. استخدم SYSTEM START LISTEN لفتح مستمع، وSYSTEM STOP LISTEN لإغلاقه:

clickhouse-local \
    --listen_host 127.0.0.1 \
    --tcp_port 9000 \
    --http_port 8123 \
    --query "
        SYSTEM START LISTEN TCP;
        SYSTEM START LISTEN HTTP;
        SELECT * FROM url('http://127.0.0.1:8123/?query=SELECT+42', LineAsString);
        SYSTEM STOP LISTEN TCP;
        SYSTEM STOP LISTEN HTTP;
    "

تضبط الخيارات --listen_host و--tcp_port و--http_port عنوان الربط والمنافذ. المنافذ الافتراضية هي 9000 لـ TCP و8123 لـ HTTP.

الأمانبشكل افتراضي، يعمل clickhouse-local بإعداد المستخدمين المؤقتين، لذا فإن أي مستمع يفتحه يكون من دون مصادقة. اربطه بعنوان استرجاعي (127.0.0.1 أو ::1) ما لم تكن قد هيّأت المستخدمين والتحكم في الوصول صراحةً عبر توجيه الإعداد users_config إلى ملف users.xml مخصص (على سبيل المثال باستخدام --config-file). يؤدي الاستماع على عنوان غير استرجاعي من دون مصادقة إلى كشف بيانات المثيل المحلي لأي شخص يمكنه الوصول إلى المنفذ المحدد.

​متى تستخدم clickhouse-local مقابل ClickHouse

​تنزيل clickhouse-local

​الاستعلام عن البيانات في ملف باستخدام SQL

​الاستعلام عن البيانات في ملف Parquet على AWS S3

​تحويلات الصيغ

​الاستخدام

​الأوامر

​أمر LS

​الأمر CLEAR

​أمثلة

​تشغيل مستمعات TCP وHTTP

​محتوى مرتبط

متى تستخدم clickhouse-local مقابل ClickHouse

تنزيل clickhouse-local

الاستعلام عن البيانات في ملف باستخدام SQL

الاستعلام عن البيانات في ملف Parquet على AWS S3

تحويلات الصيغ

الاستخدام

الأوامر

أمر LS

الأمر CLEAR

أمثلة

تشغيل مستمعات TCP وHTTP

محتوى مرتبط