البدء السريع مع ClickHouse Cloud

أسرع وأسهل طريقة لبدء استخدام ClickHouse هي إنشاء خدمة جديدة في ClickHouse Cloud. في دليل البدء السريع هذا، سنساعدك على الإعداد في ثلاث خطوات سهلة.

إنشاء خدمة ClickHouse

لإنشاء خدمة ClickHouse مجانية في ClickHouse Cloud، ما عليك سوى التسجيل باتباع الخطوات التالية:

أنشئ حسابًا من صفحة التسجيل
يمكنك التسجيل باستخدام بريدك الإلكتروني أو عبر Google SSO أو Microsoft SSO أو AWS Marketplace أو Google Cloud أو Microsoft Azure
إذا سجلت باستخدام بريد إلكتروني وكلمة مرور، فتذكّر تأكيد عنوان بريدك الإلكتروني خلال 24 ساعة عبر الرابط الذي ستتلقاه في بريدك الإلكتروني
سجّل الدخول باستخدام اسم المستخدم وكلمة المرور اللذين أنشأتهما للتو

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

افتراضيًا، تُدرج Organizations الجديدة ضمن Scale tier، وتُنشأ 3 replicas، لكل منها 4 vCPUs وذاكرة RAM بسعة 16 GiB. تكون ميزة Vertical autoscaling مفعّلة افتراضيًا في Scale tier. يمكنك تغيير organization tier لاحقًا من صفحة «الخطط».

خصّص موارد الخدمة عند الحاجة عبر تحديد حجم أدنى وأقصى يمكن أن تتدرج replicas بينهما. عند الجاهزية، اختر Create service.

تهانينا! أصبحت خدمة ClickHouse Cloud الخاصة بك قيد التشغيل، واكتملت عملية الإعداد. تابع القراءة لمعرفة كيفية البدء في استيعاب بياناتك والاستعلام عنها.

الاتصال بـ ClickHouse

هناك طريقتان للاتصال بـ ClickHouse:

الاتصال باستخدام SQL Console عبر الويب
الاتصال من تطبيقك

الاتصال باستخدام SQL Console

للبدء بسرعة، يوفّر ClickHouse SQL Console عبر الويب، وستتم إعادتك إليها بعد إكمال Onboarding.

أنشئ علامة تبويب لاستعلام وأدخل استعلامًا بسيطًا للتحقق من عمل الاتصال:

SHOW databases

سترى 4 قواعد بيانات في القائمة، بالإضافة إلى أي قواعد بيانات أضفتها.

هذا كل شيء — أصبحت جاهزًا لبدء استخدام خدمة ClickHouse الجديدة!

الاتصال بتطبيقك

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

إذا لم تجد مكتبة العميل للغة البرمجة التي تستخدمها، فاطّلع على قائمة عمليات التكامل.

إضافة بيانات

يزداد ClickHouse قوةً بوجود البيانات! هناك طرق متعددة لإضافة البيانات، ومعظمها متاح في صفحة مصادر البيانات التي يمكن الوصول إليها من قائمة التنقل.

يمكنك رفع البيانات باستخدام الطرق التالية:

أعدّ ClickPipe لبدء استيعاب البيانات من مصادر مثل S3 وPostgres وKafka وGCS
استخدم وحدة تحكم SQL
استخدم عميل ClickHouse
حمّل ملفًا - تشمل التنسيقات المقبولة JSON وCSV وTSV
حمّل البيانات من URL للملف

ClickPipes

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

إضافة البيانات باستخدام SQL Console

شأنه شأن معظم أنظمة إدارة قواعد البيانات، يُجمّع ClickHouse الجداول منطقيًا ضمن قواعد بيانات. استخدم الأمر CREATE DATABASE لإنشاء قاعدة بيانات جديدة في ClickHouse:

CREATE DATABASE IF NOT EXISTS helloworld

نفّذ الأمر التالي لإنشاء جدول باسم my_first_table في قاعدة البيانات helloworld:

CREATE TABLE helloworld.my_first_table
(
    user_id UInt32,
    message String,
    timestamp DateTime,
    metric Float32
)
ENGINE = MergeTree()
PRIMARY KEY (user_id, timestamp)

في المثال أعلاه، my_first_table هو جدول من نوع MergeTree يتكوّن من أربعة أعمدة:

user_id: عدد صحيح غير موقّع بطول 32 بت (UInt32)
message: نوع البيانات String، الذي يحل محل أنواع مثل VARCHAR وBLOB وCLOB وغيرها في أنظمة قواعد البيانات الأخرى
timestamp: قيمة DateTime تمثل نقطة زمنية
metric: عدد ذو فاصلة عائمة بطول 32 بت (Float32)

مقدمة موجزة عن المفاتيح الأساسية

قبل المضي قدمًا، من المهم فهم كيفية عمل المفاتيح الأساسية في ClickHouse (فقد يبدو تطبيق المفاتيح الأساسية غير متوقع!):

المفاتيح الأساسية في ClickHouse ليست فريدة لكل صف في جدول

يحدد المفتاح الأساسي (primary key) لجدول ClickHouse كيفية ترتيب البيانات عند كتابتها على القرص. فكل 8,192 صفًا أو 10 ميغابايت من البيانات (وهو ما يُعرف بـ دقة الفهرس (index granularity)) يُنشئ مدخلًا في ملف فهرس المفتاح الأساسي. ويؤدي مفهوم الدقة هذا إلى إنشاء فهرس متناثر (sparse index) يسهل استيعابه في الذاكرة، فيما تمثّل الحُبيبات (granules) شريحة تضم أصغر كمية من بيانات الأعمدة التي تُعالَج أثناء استعلامات SELECT.

يمكن تعريف المفتاح الأساسي باستخدام المعامل PRIMARY KEY. وإذا عرّفت جدولاً دون تحديد PRIMARY KEY، فسيصبح المفتاح هو الـ tuple المحدد في عبارة ORDER BY. أما إذا حددت PRIMARY KEY وORDER BY معاً، فيجب أن يكون المفتاح الأساسي مجموعة جزئية من ترتيب الفرز.

المفتاح الأساسي هو نفسه مفتاح الفرز، وهو Tuple مكوّن من (user_id, timestamp). وبالتالي، ستكون البيانات المخزّنة في كل ملف عمود مرتّبة حسب user_id ثم timestamp.

للتعمق في المفاهيم الأساسية لـ ClickHouse، راجع "المفاهيم الأساسية".

إدراج البيانات في جدولك

يمكنك استخدام الأمر المألوف INSERT INTO TABLE مع ClickHouse، لكن من المهم أن تدرك أن كل عملية insert في جدول MergeTree ينتج عنها إنشاء part في التخزين.

حتى في مثال بسيط، لنقم بإدراج أكثر من صف واحد في المرة الواحدة:

INSERT INTO helloworld.my_first_table (user_id, message, timestamp, metric) VALUES
    (101, 'Hello, ClickHouse!',                                 now(),       -1.0    ),
    (102, 'Insert a lot of rows per batch',                     yesterday(), 1.41421 ),
    (102, 'Sort your data based on your commonly-used queries', today(),     2.718   ),
    (101, 'Granules are the smallest chunks of data read',      now() + 5,   3.14159 )

لنتحقق من نجاح العملية:

SELECT * FROM helloworld.my_first_table

إضافة البيانات باستخدام ClickHouse Client

يمكنك أيضًا الاتصال بخدمة ClickHouse Cloud الخاصة بك باستخدام أداة سطر الأوامر clickhouse client. انقر على Connect في القائمة اليسرى للاطلاع على هذه التفاصيل، ثم اختر Native من القائمة المنسدلة في مربع الحوار:

ثبّت ClickHouse.
نفّذ الأمر التالي، مع استبدال اسم المضيف واسم المستخدم وكلمة المرور بالقيم الخاصة بك:

./clickhouse client --host HOSTNAME.REGION.CSP.clickhouse.cloud \
--secure --port 9440 \
--user default \
--password <password>

إذا ظهر لك موجّه الأوامر على شكل وجه مبتسم، فأنت جاهز لتنفيذ الاستعلامات!

:)

جرّب ذلك عبر تشغيل الاستعلام التالي:

SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp

لاحظ أن الاستجابة تعود بتنسيق جدول أنيق:

┌─user_id─┬─message────────────────────────────────────────────┬───────────timestamp─┬──metric─┐
│     102 │ Insert a lot of rows per batch                     │ 2022-03-21 00:00:00 │ 1.41421 │
│     102 │ Sort your data based on your commonly-used queries │ 2022-03-22 00:00:00 │   2.718 │
│     101 │ Hello, ClickHouse!                                 │ 2022-03-22 14:04:09 │      -1 │
│     101 │ Granules are the smallest chunks of data read      │ 2022-03-22 14:04:14 │ 3.14159 │
└─────────┴────────────────────────────────────────────────────┴─────────────────────┴─────────┘

4 rows in set. Elapsed: 0.008 sec.

أضف عبارة FORMAT لتحديد أحد تنسيقات الإخراج العديدة المدعومة في ClickHouse:

SELECT *
FROM helloworld.my_first_table
ORDER BY timestamp
FORMAT TabSeparated

في الاستعلام أعلاه، يُعاد الناتج مفصولاً بعلامات الجدولة:

Query id: 3604df1c-acfd-4117-9c56-f86c69721121

102 Insert a lot of rows per batch      2022-03-21 00:00:00     1.41421
102 Sort your data based on your commonly-used queries  2022-03-22 00:00:00     2.718
101 Hello, ClickHouse!  2022-03-22 14:04:09     -1
101 Granules are the smallest chunks of data read       2022-03-22 14:04:14     3.14159

4 rows in set. Elapsed: 0.005 sec.

للخروج من clickhouse client، أدخِل الأمر exit:

exit

رفع ملف

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

لنفترض أن لدينا النص التالي في ملف CSV يحمل اسم الملف data.csv:

data.csvbash

102,This is data in a file,2022-02-22 10:43:28,123.45
101,It is comma-separated,2022-02-23 00:00:00,456.78
103,Use FORMAT to specify the format,2022-02-21 10:43:30,678.90

يُدرِج الأمر التالي البيانات في جدول my_first_table:

./clickhouse client --host HOSTNAME.REGION.CSP.clickhouse.cloud \
--secure --port 9440 \
--user default \
--password <password> \
--query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv

لاحظ ظهور الصفوف الجديدة الآن في الجدول عند إجراء استعلام من SQL Console:

ما الخطوة التالية؟

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

يمكنك اتباع هذا المسار بنفسك، أو أتمتته ببرنامج نصي، أو إسناده إلى AI Agent. انتقل إلى عرض Cloud UI للإصدار الخاص بـ Console.

تغطي هذه الصفحة توفير خدمة ClickHouse Cloud والاتصال بها وتحميل البيانات، وكل ذلك من سطر الأوامر باستخدام واجهة سطر أوامر ClickHouse (clickhousectl). الأوامر غير تفاعلية، ويُخرج clickhousectl بيانات JSON باستخدام --json.

المتطلبات الأساسية

ثبّت واجهة سطر أوامر ClickHouse:

curl https://clickhouse.com/cli | sh

ستحتاج أيضًا إلى jq.

تحتاج إلى حساب ClickHouse Cloud. إذا لم يكن لديك حساب بعد، فسيؤدي الأمر clickhousectl cloud auth signup إلى فتح صفحة التسجيل في متصفحك.

تتطلب عمليات الكتابة (الإنشاء والحذف) مصادقة بمفتاح API، بينما يقتصر تسجيل الدخول عبر OAuth على القراءة فقط:

clickhousectl cloud auth login --api-key <YOUR_KEY> --api-secret <YOUR_SECRET>

بدلًا من ذلك، عيّن متغيرَي البيئة CLICKHOUSE_CLOUD_API_KEY وCLICKHOUSE_CLOUD_API_SECRET. تحقّق باستخدام clickhousectl cloud auth status؛ ويُفترض أن يظهر إدخال بنطاق read/write.

أنشئ خدمة ClickHouse

أنشئ الخدمة واحفظ الاستجابة؛ إذ لا تُعرض كلمة مرور المستخدم default إلا مرة واحدة:

clickhousectl cloud service create \
  --name quickstart-ch \
  --region us-east-1 \
  --json > ch.json

تتضمن الاستجابة معرّف الخدمة ونقاط النهاية وكلمة المرور المُنشأة (اقتُصرت هنا؛ إذ تتضمن الاستجابة الكاملة أيضًا إعدادات التوسعة وقائمة الوصول عبر IP والوسوم):

{
  "password": "dK7mPq2x_-TzrL9vNw0s",
  "service": {
    "id": "4f7b92f3-4163-403a-b538-b9bc6e2e8f66",
    "name": "quickstart-ch",
    "provider": "aws",
    "region": "us-east-1",
    "state": "provisioning",
    "endpoints": [
      {
        "host": "quickstart-abc123.us-east-1.aws.clickhouse.cloud",
        "port": 9440,
        "protocol": "nativesecure"
      },
      {
        "host": "quickstart-abc123.us-east-1.aws.clickhouse.cloud",
        "port": 8443,
        "protocol": "https"
      }
    ],
    "numReplicas": 3,
    "minReplicaMemoryGb": 16.0,
    "maxReplicaMemoryGb": 120.0
  }
}

استخرج المتطلبات اللازمة لبقية هذا الدليل:

CH_ID=$(jq -r .service.id ch.json)
CH_PASSWORD=$(jq -r .password ch.json)
CH_HOST=$(jq -r '.service.endpoints[] | select(.protocol=="nativesecure") | .host' ch.json)

إذا فقدت كلمة المرور، أنشئ كلمة مرور جديدة باستخدام clickhousectl cloud service reset-password "$CH_ID".

تُنشأ الخدمات باستخدام clickhousectl افتراضيًا مع قائمة وصول لعناوين IP تسمح بالوصول من جميع العناوين (0.0.0.0/0). لتقييد الوصول، مرّر --ip-allow عند إنشاء الخدمة؛ راجع "إعداد عوامل تصفية IP".

انتظر حتى تكتمل تهيئة الخدمة

تستغرق التهيئة نحو دقيقة. تحقّق دوريًا حتى تصبح الحالة running:

while [ "$(clickhousectl cloud service get "$CH_ID" --json | jq -r .state)" != "running" ]; do
  sleep 15
done

شغّل SQL باستخدام واجهة برمجة تطبيقات الاستعلام

يشغّل clickhousectl cloud service query استعلامات SQL عبر HTTP، دون الحاجة إلى ملف تنفيذي لـ clickhouse محلي أو كلمة مرور الخدمة. ينشئ الاستدعاء الأول تلقائيًا نقطة نهاية لواجهة برمجة تطبيقات الاستعلام ومفتاح API مقيّدًا بالخدمة:

clickhousectl cloud service query --id "$CH_ID" --query "SHOW databases"

Provisioning Query API endpoint + key for service 'quickstart-ch'...
{"name":"INFORMATION_SCHEMA"}
{"name":"default"}
{"name":"information_schema"}
{"name":"system"}

يكون إخراج الأنبوب افتراضيًا بتنسيق JSONEachRow؛ مرّر --format PrettyCompact للحصول على إخراج على هيئة جدول بدلًا من ذلك.

إنشاء قاعدة بيانات وجدول

clickhousectl cloud service query --id "$CH_ID" \
  --query "CREATE DATABASE IF NOT EXISTS helloworld"

clickhousectl cloud service query --id "$CH_ID" \
  --query "CREATE TABLE helloworld.my_first_table (
    user_id UInt32,
    message String,
    timestamp DateTime,
    metric Float32
  ) ENGINE = MergeTree()
  PRIMARY KEY (user_id, timestamp)"

يطبع كلا الأمرين OK. أدرج بضعة صفوف:

clickhousectl cloud service query --id "$CH_ID" \
  --query "INSERT INTO helloworld.my_first_table (user_id, message, timestamp, metric) VALUES
    (101, 'Hello, ClickHouse!', now(), -1.0),
    (102, 'Insert a lot of rows per batch', yesterday(), 1.41421),
    (102, 'Sort your data based on your commonly-used queries', today(), 2.718),
    (101, 'Granules are the smallest chunks of data read', now() + 5, 3.14159)"

تحقّق من نجاح العملية:

clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT * FROM helloworld.my_first_table ORDER BY timestamp"

{"user_id":102,"message":"Insert a lot of rows per batch","timestamp":"2026-08-26 00:00:00","metric":1.41421}
{"user_id":102,"message":"Sort your data based on your commonly-used queries","timestamp":"2026-08-27 00:00:00","metric":2.718}
{"user_id":101,"message":"Hello, ClickHouse!","timestamp":"2026-08-27 10:41:28","metric":-1}
{"user_id":101,"message":"Granules are the smallest chunks of data read","timestamp":"2026-08-27 10:41:33","metric":3.14159}

تعتمد الطوابع الزمنية على وقت تنفيذ عملية insert، لذا ستختلف القيم لديك.

تحميل ملف CSV

افترض أن النص التالي موجود في ملف CSV باسم data.csv:

data.csvtext

102,This is data in a file,2022-02-22 10:43:28,123.45
101,It is comma-separated,2022-02-23 00:00:00,456.78
103,Use FORMAT to specify the format,2022-02-21 10:43:30,678.90

تقرأ INSERT ... FORMAT البيانات من stdin، لذا مرّر الاستعلام والملف معًا عبر pipe:

printf 'INSERT INTO helloworld.my_first_table FORMAT CSV\n' | cat - data.csv \
  | clickhousectl cloud service query --id "$CH_ID"

تحقّق من إدراج الصفوف الجديدة:

clickhousectl cloud service query --id "$CH_ID" \
  --query "SELECT count() FROM helloworld.my_first_table"

{"count()":7}

الاتصال باستخدام clickhouse client

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

clickhousectl local use latest

يثبّت هذا أحدث ملف تنفيذي لـ clickhouse وينشئ رابطًا رمزيًا له في ~/.local/bin/clickhouse، بحيث يصبح أمر clickhouse متاحًا عموميًا ضمن PATH.

بعد ذلك، اتصل باستخدام اسم المضيف وكلمة المرور الواردين في استجابة الإنشاء. عند استخدام --query، تُطبع النتيجة ثم ينهي العميل عمله؛ أما بدونه، فستظهر لك موجّه الأوامر التفاعلي (:)) الذي يمكنك الخروج منه باستخدام exit:

clickhouse client --host "$CH_HOST" --secure --port 9440 \
  --user default --password "$CH_PASSWORD" \
  --query "SELECT * FROM helloworld.my_first_table ORDER BY timestamp FORMAT TabSeparated"

102	Insert a lot of rows per batch	2026-08-26 00:00:00	1.41421
102	Sort your data based on your commonly-used queries	2026-08-27 00:00:00	2.718
101	Hello, ClickHouse!	2026-08-27 10:41:28	-1
101	Granules are the smallest chunks of data read	2026-08-27 10:41:33	3.14159
103	Use FORMAT to specify the format	2022-02-21 10:43:30	678.9
102	This is data in a file	2022-02-22 10:43:28	123.45
101	It is comma-separated	2022-02-23 00:00:00	456.78

يتيح نموذج الأمر نفسه تحميل الملفات:

clickhouse client --host "$CH_HOST" --secure --port 9440 \
  --user default --password "$CH_PASSWORD" \
  --query='INSERT INTO helloworld.my_first_table FORMAT CSV' < data.csv

التنظيف

يؤدي حذف الخدمة إلى إزالة جميع بياناتها نهائيًا. يوقف الخيار --force الخدمة قيد التشغيل أولًا:

clickhousectl cloud service delete "$CH_ID" --force

للاحتفاظ بالبيانات مع إيقاف تكاليف الحوسبة، أوقف الخدمة باستخدام clickhousectl cloud service stop "$CH_ID" بدلًا من ذلك.