Prérequis pour les développeurs

ClickHouse peut être compilé sur Linux, FreeBSD et macOS. Si vous utilisez Windows, vous pouvez tout de même compiler ClickHouse dans une machine virtuelle sous Linux, par exemple VirtualBox avec Ubuntu.

Créer un dépôt sur GitHub

Pour commencer à développer pour ClickHouse, vous aurez besoin d’un compte GitHub. Veuillez également générer une clé SSH en local (si vous n’en avez pas déjà une) et ajouter la clé publique à GitHub, car il s’agit d’un prérequis pour soumettre des correctifs. Ensuite, créez un fork du dépôt ClickHouse dans votre compte personnel en cliquant sur le bouton “fork” en haut à droite. Pour proposer des modifications, par exemple un correctif pour une issue ou une fonctionnalité, validez d’abord vos changements dans une branche de votre fork, puis créez une “Pull Request” vers le dépôt principal. Pour travailler avec des dépôts Git, veuillez installer Git. Par exemple, sur Ubuntu, exécutez :

sudo apt update
sudo apt install git

Vous trouverez un aide-mémoire Git ici. Un manuel Git détaillé est disponible ici.

Clonez le dépôt sur votre machine de développement

Commencez par récupérer les fichiers sources sur votre machine de travail en clonant le dépôt :

git clone git@github.com:your_github_username/ClickHouse.git  # replace the placeholder with your GitHub user name
cd ClickHouse

Cette commande crée un répertoire ClickHouse/ contenant le code source, les tests et d’autres fichiers. Vous pouvez spécifier un répertoire de destination personnalisé après l’URL, mais il est important que ce chemin ne contienne pas d’espaces, car cela pourrait casser le build par la suite. Le dépôt Git de ClickHouse utilise des sous-modules pour récupérer des bibliothèques tierces. Les sous-modules ne sont pas extraits par défaut. Vous pouvez soit

exécuter git clone avec l’option --recurse-submodules,
si git clone est exécuté sans --recurse-submodules, exécuter git submodule update --init --jobs <N> pour extraire explicitement tous les sous-modules. (<N> peut par exemple être défini sur 12 pour paralléliser le téléchargement.)
si git clone est exécuté sans --recurse-submodules et que vous souhaitez utiliser une extraction superficielle (shallow) des sous-modules afin d’en omettre l’historique pour gagner de l’espace, exécutez ./contrib/update-submodules.sh. Cette alternative est utilisée par la CI, mais elle n’est pas recommandée pour le développement local, car elle rend l’utilisation des sous-modules moins pratique et plus lente.

Pour vérifier l’état des sous-modules Git, exécutez git submodule status. Si vous obtenez le message d’erreur suivant

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

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

les clés SSH de connexion à GitHub sont absentes. Ces clés se trouvent normalement dans ~/.ssh. Pour que les clés SSH soient reconnues, vous devez les ajouter dans les paramètres de GitHub. Vous pouvez également cloner le dépôt via HTTPS :

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

Cela ne vous permettra toutefois pas d’envoyer vos modifications au serveur. Vous pouvez néanmoins l’utiliser temporairement et ajouter les clés SSH plus tard en remplaçant l’adresse distante du dépôt à l’aide de la commande git remote. Vous pouvez également ajouter l’adresse du dépôt ClickHouse d’origine à votre dépôt local pour récupérer les mises à jour depuis celui-ci :

git remote add upstream git@github.com:ClickHouse/ClickHouse.git

Après avoir exécuté cette commande avec succès, vous pourrez récupérer les mises à jour du dépôt principal de ClickHouse en exécutant git pull upstream master.

N’utilisez pas git push tel quel : vous risquez de pousser vers le mauvais dépôt distant et/ou la mauvaise branche. Il est préférable de préciser explicitement les noms du dépôt distant et de la branche, par exemple git push origin my_branch_name.

Écrire du code

Vous trouverez ci-dessous quelques liens utiles pour écrire du code pour ClickHouse :

IDE

Visual Studio Code et Neovim sont deux options qui ont bien fonctionné jusqu’ici pour développer ClickHouse. Si vous utilisez VS Code, nous vous recommandons d’utiliser l’extension clangd à la place d’IntelliSense, car elle est nettement plus performante. CLion est une autre excellente option. Cependant, il peut être plus lent sur de gros projets comme ClickHouse. Voici quelques points à garder à l’esprit lorsque vous utilisez CLion :

CLion crée lui-même un répertoire build et sélectionne automatiquement debug comme type de build
Il utilise une version de CMake définie dans CLion, et non celle que vous avez installée
CLion utilise make pour exécuter les tâches de compilation au lieu de ninja (c’est le comportement normal)

Vous pouvez également utiliser d’autres IDE, comme Sublime Text, Qt Creator ou Kate.

Créer une pull request

Accédez au dépôt de votre fork dans l’interface de GitHub. Si vous avez travaillé dans une branche, vous devez sélectionner cette branche. Un bouton “Pull request” sera affiché à l’écran. Concrètement, cela signifie « créer une demande pour faire accepter mes modifications dans le dépôt principal ». Une pull request peut être créée même si le travail n’est pas encore terminé. Dans ce cas, veuillez mettre le mot “WIP” (work in progress) au début du titre ; vous pourrez le modifier plus tard. C’est utile pour la relecture collaborative et la discussion autour des modifications, ainsi que pour exécuter tous les tests disponibles. Il est important de fournir une brève description de vos modifications ; elle sera ensuite utilisée pour générer le changelog de la release. Les tests démarreront dès que des employés de ClickHouse auront ajouté à votre PR le tag “can be tested”. Les résultats de quelques premières vérifications (par ex. le style de code) arriveront en quelques minutes. Les résultats des vérifications de build arriveront dans la demi-heure. L’ensemble principal des tests remontera ses résultats en moins d’une heure. Le système préparera séparément des builds binaires de ClickHouse pour votre pull request. Pour récupérer ces builds, cliquez sur le lien “Details” à côté de l’entrée “Builds” dans la liste des vérifications. Vous y trouverez des liens directs vers les paquets .deb de ClickHouse générés, que vous pouvez déployer même sur vos serveurs de production (si vous n’avez peur de rien).

Rédiger la documentation

Toute pull request qui ajoute une nouvelle fonctionnalité doit être accompagnée d’une documentation adéquate. Si vous souhaitez prévisualiser vos modifications de la documentation, suivez les instructions du README de la documentation (mint dev depuis docs/). Lorsque vous ajoutez une nouvelle fonction à ClickHouse, vous pouvez utiliser le modèle ci-dessous comme référence :

# 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](/reference/data-types/float)
- `arg2` — Description of the argument. [DataType](/reference/data-types/float)
- `arg3` — Description of optional argument (optional). [DataType](/reference/data-types/float)

**Implementation Details**

A description of implementation details if relevant.

**Returned value**

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

**Example**

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

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

Utilisation de données de test

Le développement de ClickHouse nécessite souvent le chargement de jeux de données réalistes. C’est particulièrement important pour les tests de performances. Nous mettons à disposition un jeu de données anonymisées d’analyse d’audience web, spécialement préparé à cet effet. Cela nécessite en outre environ 3 Go d’espace disque libre.

    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

Dans 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);

Importez les données :

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

Introduction

Compilation

Protocole natif

Contribuer

Développement d’intégrations

Feuille de route

Créer un dépôt sur GitHub

Clonez le dépôt sur votre machine de développement

Écrire du code

IDE

Créer une pull request

Rédiger la documentation

Utilisation de données de test

​Créer un dépôt sur GitHub

​Clonez le dépôt sur votre machine de développement

​Écrire du code

​IDE

​Créer une pull request

​Rédiger la documentation

​Utilisation de données de test

Créer un dépôt sur GitHub

Clonez le dépôt sur votre machine de développement

Écrire du code

IDE

Créer une pull request

Rédiger la documentation

Utilisation de données de test