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

المتطلبات الأساسية وإرشادات الإعداد لتطوير ClickHouse

يمكن بناء ClickHouse على Linux وFreeBSD وmacOS. إذا كنت تستخدم Windows، فلا يزال بإمكانك بناء ClickHouse داخل جهاز افتراضي يعمل بنظام Linux، مثل VirtualBox مع Ubuntu.

​

أنشئ مستودعًا على GitHub

لبدء التطوير على ClickHouse، ستحتاج إلى حساب على GitHub. يُرجى أيضًا إنشاء مفتاح SSH محليًا (إذا لم يكن لديك واحد بالفعل) ورفع المفتاح العام إلى GitHub، لأن ذلك يُعد متطلبًا أساسيًا للمساهمة بالتعديلات.

بعد ذلك، أنشئ نسخة متفرعة من مستودع ClickHouse ضمن حسابك الشخصي بالنقر على زر “fork” في الزاوية العلوية اليمنى.

للمساهمة بتغييرات، مثل إصلاح مشكلة أو إضافة ميزة، نفّذ أولًا commit لتغييراتك على فرع في نسختك المتفرعة، ثم أنشئ “طلب سحب” بهذه التغييرات إلى المستودع الرئيسي.

للعمل مع مستودعات Git، يُرجى تثبيت Git. على سبيل المثال، في Ubuntu، شغّل:

sudo apt update
sudo apt install git

يمكنك العثور على ملخص مرجعي لـ Git هنا. كما يتوفر دليل Git مفصل هنا.

​

استنسخ المستودع على جهاز التطوير لديك

أولاً، نزّل الملفات المصدرية إلى جهازك، أي انسخ المستودع محليًا:

git clone [e-mail]:your_github_username/ClickHouse.git  # replace the placeholder with your GitHub user name
cd ClickHouse

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

يستخدم مستودع Git الخاص بـ ClickHouse الوحدات الفرعية لجلب مكتبات الطرف الثالث. ولا تُسحَب الوحدات الفرعية افتراضيًا. يمكنك إما

• تشغيل git clone مع الخيار --recurse-submodules،

• إذا شغّلت git clone بدون --recurse-submodules، فشغّل git submodule update --init --jobs <N> لسحب جميع الوحدات الفرعية صراحةً. (يمكن ضبط <N> مثلًا على 12 لتنفيذ التنزيل بالتوازي.)

• إذا شغّلت git clone بدون --recurse-submodules وكنت ترغب في استخدام checkout سطحي shallow للوحدات الفرعية لتجاهل السجل فيها وتوفير بعض المساحة، فشغّل ./contrib/update-submodules.sh. يُستخدم هذا البديل في CI، لكنه غير موصى به للتطوير المحلي لأنه يجعل العمل مع الوحدات الفرعية أقل سهولة وأبطأ.

للتحقق من حالة الوحدات الفرعية في Git، شغّل git submodule status.

إذا ظهرت لك رسالة الخطأ التالية

Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

مفاتيح SSH اللازمة للاتصال بـ GitHub غير موجودة. توجد هذه المفاتيح عادةً في ~/.ssh. ولكي يقبل GitHub مفاتيح SSH، يجب رفعها في إعداداته.

يمكنك أيضًا استنساخ المستودع عبر HTTPS:

git clone https://github.com/ClickHouse/ClickHouse.git

لكن هذا لن يتيح لك إرسال تغييراتك إلى الخادم. ومع ذلك، لا يزال بإمكانك استخدامه مؤقتًا ثم إضافة مفاتيح SSH لاحقًا، مع استبدال العنوان البعيد للمستودع باستخدام الأمر git remote.

يمكنك أيضًا إضافة عنوان مستودع ClickHouse الأصلي إلى مستودعك المحلي لسحب التحديثات منه:

git remote add upstream [e-mail]:ClickHouse/ClickHouse.git

بعد تنفيذ هذا الأمر بنجاح، ستتمكن من سحب التحديثات من مستودع ClickHouse الرئيسي بتنفيذ git pull upstream master.

يُرجى عدم استخدام الأمر git push كما هو، فقد تدفع إلى مستودع بعيد خاطئ و/أو فرع خاطئ. من الأفضل تحديد اسم المستودع البعيد واسم الفرع صراحةً، مثل git push origin my_branch_name.

​

كتابة الشيفرة

فيما يلي بعض الروابط السريعة التي قد تفيدك عند كتابة الشيفرة لـ ClickHouse:

• معمارية ClickHouse.
• دليل أسلوب كتابة الشيفرة.
• مكتبات الطرف الثالث
• كتابة الاختبارات
• المشكلات المفتوحة

​

بيئة التطوير المتكاملة

يُعدّ كلٌّ من Visual Studio Code وNeovim خيارين أثبتا فاعليتهما سابقًا في تطوير ClickHouse. إذا كنت تستخدم VS Code، فنوصي باستخدام إضافة clangd بدلًا من IntelliSense لأنها أعلى أداءً بكثير.

يُعدّ CLion بديلًا ممتازًا آخر. ومع ذلك، قد يكون أبطأ في المشاريع الكبيرة مثل ClickHouse. إليك بعض الأمور التي ينبغي مراعاتها عند استخدام CLion:

• ينشئ CLion تلقائيًا مسار build ويحدّد debug تلقائيًا كنوع البناء
• يستخدم إصدارًا من CMake محددًا داخل CLion، وليس الإصدار الذي ثبّتَّه أنت
• سيستخدم CLion الأمر make لتشغيل مهام البناء بدلًا من ninja (وهذا سلوك طبيعي)

ومن بيئات التطوير المتكاملة الأخرى التي يمكنك استخدامها: Sublime Text، وQt Creator، أو Kate.

​

أنشئ طلب سحب

انتقل إلى المستودع المتفرع الخاص بك في واجهة GitHub. إذا كنت تعمل على فرع، فعليك تحديد ذلك الفرع. سيظهر على الشاشة زر “Pull request”. وبعبارة أخرى، فهذا يعني: “أنشئ طلبًا لقبول تعديلاتي في المستودع الرئيسي”.

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

سيبدأ الاختبار بمجرد أن يضيف موظفو ClickHouse إلى طلب السحب الخاص بك الوسم “can be tested”. ستظهر نتائج بعض عمليات التحقق الأولى (مثل أسلوب كتابة الشيفرة) خلال عدة دقائق. ستصل نتائج التحقق من البناء خلال نصف ساعة. وستظهر نتائج المجموعة الرئيسية من الاختبارات خلال ساعة.

سيُعدّ النظام إصدارات ClickHouse الثنائية الخاصة بطلب السحب لديك بشكل منفصل. ولاسترجاع هذه الإصدارات، انقر على الرابط “Details” بجوار العنصر “Builds” في قائمة عمليات التحقق. وهناك ستجد روابط مباشرة إلى حزم .deb المبنية الخاصة بـ ClickHouse، والتي يمكنك نشرها حتى على خوادم الإنتاج لديك (إن كنت لا تمانع المخاطرة).

​

كتابة الوثائق

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

# newFunctionName

A short description of the function goes here. It should describe briefly what it does and a typical usage case.

**Syntax**

\```sql
newFunctionName(arg1, arg2[, arg3])
\```

**Arguments**

- `arg1` — Description of the argument. [DataType](../data-types/float.md)
- `arg2` — Description of the argument. [DataType](../data-types/float.md)
- `arg3` — Description of optional argument (optional). [DataType](../data-types/float.md)

**Implementation Details**

A description of implementation details if relevant.

**Returned value**

- Returns {insert what the function returns here}. [DataType](../data-types/float.md)

**Example**

\```sql title="Query"
SELECT 'write your example query here';
\```

\```response title="Response"
┌───────────────────────────────────┐
│ the result of the query           │
└───────────────────────────────────┘
\```

​

استخدام بيانات الاختبار

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

    sudo apt install wget xz-utils

    wget https://datasets.clickhouse.com/hits/tsv/hits_v1.tsv.xz
    wget https://datasets.clickhouse.com/visits/tsv/visits_v1.tsv.xz

    xz -v -d hits_v1.tsv.xz
    xz -v -d visits_v1.tsv.xz

    clickhouse-client

في clickhouse-client:

CREATE DATABASE IF NOT EXISTS test;

CREATE TABLE test.hits ( WatchID UInt64,  JavaEnable UInt8,  Title String,  GoodEvent Int16,  EventTime DateTime,  EventDate Date,  CounterID UInt32,  ClientIP UInt32,  ClientIP6 FixedString(16),  RegionID UInt32,  UserID UInt64,  CounterClass Int8,  OS UInt8,  UserAgent UInt8,  URL String,  Referer String,  URLDomain String,  RefererDomain String,  Refresh UInt8,  IsRobot UInt8,  RefererCategories Array(UInt16),  URLCategories Array(UInt16),  URLRegions Array(UInt32),  RefererRegions Array(UInt32),  ResolutionWidth UInt16,  ResolutionHeight UInt16,  ResolutionDepth UInt8,  FlashMajor UInt8,  FlashMinor UInt8,  FlashMinor2 String,  NetMajor UInt8,  NetMinor UInt8,  UserAgentMajor UInt16,  UserAgentMinor FixedString(2),  CookieEnable UInt8,  JavascriptEnable UInt8,  IsMobile UInt8,  MobilePhone UInt8,  MobilePhoneModel String,  Params String,  IPNetworkID UInt32,  TraficSourceID Int8,  SearchEngineID UInt16,  SearchPhrase String,  AdvEngineID UInt8,  IsArtifical UInt8,  WindowClientWidth UInt16,  WindowClientHeight UInt16,  ClientTimeZone Int16,  ClientEventTime DateTime,  SilverlightVersion1 UInt8,  SilverlightVersion2 UInt8,  SilverlightVersion3 UInt32,  SilverlightVersion4 UInt16,  PageCharset String,  CodeVersion UInt32,  IsLink UInt8,  IsDownload UInt8,  IsNotBounce UInt8,  FUniqID UInt64,  HID UInt32,  IsOldCounter UInt8,  IsEvent UInt8,  IsParameter UInt8,  DontCountHits UInt8,  WithHash UInt8,  HitColor FixedString(1),  UTCEventTime DateTime,  Age UInt8,  Sex UInt8,  Income UInt8,  Interests UInt16,  Robotness UInt8,  GeneralInterests Array(UInt16),  RemoteIP UInt32,  RemoteIP6 FixedString(16),  WindowName Int32,  OpenerName Int32,  HistoryLength Int16,  BrowserLanguage FixedString(2),  BrowserCountry FixedString(2),  SocialNetwork String,  SocialAction String,  HTTPError UInt16,  SendTiming Int32,  DNSTiming Int32,  ConnectTiming Int32,  ResponseStartTiming Int32,  ResponseEndTiming Int32,  FetchTiming Int32,  RedirectTiming Int32,  DOMInteractiveTiming Int32,  DOMContentLoadedTiming Int32,  DOMCompleteTiming Int32,  LoadEventStartTiming Int32,  LoadEventEndTiming Int32,  NSToDOMContentLoadedTiming Int32,  FirstPaintTiming Int32,  RedirectCount Int8,  SocialSourceNetworkID UInt8,  SocialSourcePage String,  ParamPrice Int64,  ParamOrderID String,  ParamCurrency FixedString(3),  ParamCurrencyID UInt16,  GoalsReached Array(UInt32),  OpenstatServiceName String,  OpenstatCampaignID String,  OpenstatAdID String,  OpenstatSourceID String,  UTMSource String,  UTMMedium String,  UTMCampaign String,  UTMContent String,  UTMTerm String,  FromTag String,  HasGCLID UInt8,  RefererHash UInt64,  URLHash UInt64,  CLID UInt32,  YCLID UInt64,  ShareService String,  ShareURL String,  ShareTitle String,  `ParsedParams.Key1` Array(String),  `ParsedParams.Key2` Array(String),  `ParsedParams.Key3` Array(String),  `ParsedParams.Key4` Array(String),  `ParsedParams.Key5` Array(String),  `ParsedParams.ValueDouble` Array(Float64),  IslandID FixedString(16),  RequestNum UInt32,  RequestTry UInt8) ENGINE = MergeTree PARTITION BY toYYYYMM(EventDate) SAMPLE BY intHash32(UserID) ORDER BY (CounterID, EventDate, intHash32(UserID), EventTime);

CREATE TABLE test.visits ( CounterID UInt32,  StartDate Date,  Sign Int8,  IsNew UInt8,  VisitID UInt64,  UserID UInt64,  StartTime DateTime,  Duration UInt32,  UTCStartTime DateTime,  PageViews Int32,  Hits Int32,  IsBounce UInt8,  Referer String,  StartURL String,  RefererDomain String,  StartURLDomain String,  EndURL String,  LinkURL String,  IsDownload UInt8,  TraficSourceID Int8,  SearchEngineID UInt16,  SearchPhrase String,  AdvEngineID UInt8,  PlaceID Int32,  RefererCategories Array(UInt16),  URLCategories Array(UInt16),  URLRegions Array(UInt32),  RefererRegions Array(UInt32),  IsYandex UInt8,  GoalReachesDepth Int32,  GoalReachesURL Int32,  GoalReachesAny Int32,  SocialSourceNetworkID UInt8,  SocialSourcePage String,  MobilePhoneModel String,  ClientEventTime DateTime,  RegionID UInt32,  ClientIP UInt32,  ClientIP6 FixedString(16),  RemoteIP UInt32,  RemoteIP6 FixedString(16),  IPNetworkID UInt32,  SilverlightVersion3 UInt32,  CodeVersion UInt32,  ResolutionWidth UInt16,  ResolutionHeight UInt16,  UserAgentMajor UInt16,  UserAgentMinor UInt16,  WindowClientWidth UInt16,  WindowClientHeight UInt16,  SilverlightVersion2 UInt8,  SilverlightVersion4 UInt16,  FlashVersion3 UInt16,  FlashVersion4 UInt16,  ClientTimeZone Int16,  OS UInt8,  UserAgent UInt8,  ResolutionDepth UInt8,  FlashMajor UInt8,  FlashMinor UInt8,  NetMajor UInt8,  NetMinor UInt8,  MobilePhone UInt8,  SilverlightVersion1 UInt8,  Age UInt8,  Sex UInt8,  Income UInt8,  JavaEnable UInt8,  CookieEnable UInt8,  JavascriptEnable UInt8,  IsMobile UInt8,  BrowserLanguage UInt16,  BrowserCountry UInt16,  Interests UInt16,  Robotness UInt8,  GeneralInterests Array(UInt16),  Params Array(String),  `Goals.ID` Array(UInt32),  `Goals.Serial` Array(UInt32),  `Goals.EventTime` Array(DateTime),  `Goals.Price` Array(Int64),  `Goals.OrderID` Array(String),  `Goals.CurrencyID` Array(UInt32),  WatchIDs Array(UInt64),  ParamSumPrice Int64,  ParamCurrency FixedString(3),  ParamCurrencyID UInt16,  ClickLogID UInt64,  ClickEventID Int32,  ClickGoodEvent Int32,  ClickEventTime DateTime,  ClickPriorityID Int32,  ClickPhraseID Int32,  ClickPageID Int32,  ClickPlaceID Int32,  ClickTypeID Int32,  ClickResourceID Int32,  ClickCost UInt32,  ClickClientIP UInt32,  ClickDomainID UInt32,  ClickURL String,  ClickAttempt UInt8,  ClickOrderID UInt32,  ClickBannerID UInt32,  ClickMarketCategoryID UInt32,  ClickMarketPP UInt32,  ClickMarketCategoryName String,  ClickMarketPPName String,  ClickAWAPSCampaignName String,  ClickPageName String,  ClickTargetType UInt16,  ClickTargetPhraseID UInt64,  ClickContextType UInt8,  ClickSelectType Int8,  ClickOptions String,  ClickGroupBannerID Int32,  OpenstatServiceName String,  OpenstatCampaignID String,  OpenstatAdID String,  OpenstatSourceID String,  UTMSource String,  UTMMedium String,  UTMCampaign String,  UTMContent String,  UTMTerm String,  FromTag String,  HasGCLID UInt8,  FirstVisit DateTime,  PredLastVisit Date,  LastVisit Date,  TotalVisits UInt32,  `TraficSource.ID` Array(Int8),  `TraficSource.SearchEngineID` Array(UInt16),  `TraficSource.AdvEngineID` Array(UInt8),  `TraficSource.PlaceID` Array(UInt16),  `TraficSource.SocialSourceNetworkID` Array(UInt8),  `TraficSource.Domain` Array(String),  `TraficSource.SearchPhrase` Array(String),  `TraficSource.SocialSourcePage` Array(String),  Attendance FixedString(16),  CLID UInt32,  YCLID UInt64,  NormalizedRefererHash UInt64,  SearchPhraseHash UInt64,  RefererDomainHash UInt64,  NormalizedStartURLHash UInt64,  StartURLDomainHash UInt64,  NormalizedEndURLHash UInt64,  TopLevelDomain UInt64,  URLScheme UInt64,  OpenstatServiceNameHash UInt64,  OpenstatCampaignIDHash UInt64,  OpenstatAdIDHash UInt64,  OpenstatSourceIDHash UInt64,  UTMSourceHash UInt64,  UTMMediumHash UInt64,  UTMCampaignHash UInt64,  UTMContentHash UInt64,  UTMTermHash UInt64,  FromHash UInt64,  WebVisorEnabled UInt8,  WebVisorActivity UInt32,  `ParsedParams.Key1` Array(String),  `ParsedParams.Key2` Array(String),  `ParsedParams.Key3` Array(String),  `ParsedParams.Key4` Array(String),  `ParsedParams.Key5` Array(String),  `ParsedParams.ValueDouble` Array(Float64),  `Market.Type` Array(UInt8),  `Market.GoalID` Array(UInt32),  `Market.OrderID` Array(String),  `Market.OrderPrice` Array(Int64),  `Market.PP` Array(UInt32),  `Market.DirectPlaceID` Array(UInt32),  `Market.DirectOrderID` Array(UInt32),  `Market.DirectBannerID` Array(UInt32),  `Market.GoodID` Array(String),  `Market.GoodName` Array(String),  `Market.GoodQuantity` Array(Int32),  `Market.GoodPrice` Array(Int64),  IslandID FixedString(16)) ENGINE = CollapsingMergeTree(Sign) PARTITION BY toYYYYMM(StartDate) SAMPLE BY intHash32(UserID) ORDER BY (CounterID, StartDate, intHash32(UserID), VisitID);

قم باستيراد البيانات:

clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.hits FORMAT TSV" < hits_v1.tsv
clickhouse-client --max_insert_block_size 100000 --query "INSERT INTO test.visits FORMAT TSV" < visits_v1.tsv