Paramètres globaux
common de niveau supérieur :
Ces paramètres communs
autogenerate_session_id, product_name et readonly doivent toujours être modifiés avant de créer un client avec la méthode clickhouse_connect.get_client. Modifier ces paramètres après la création du client n’affecte pas le comportement des clients existants.| Setting Name | Default | Options | Description |
|---|---|---|---|
| autogenerate_session_id | True | True, False | Génère automatiquement un nouvel ID de session UUID(1) (s’il n’est pas fourni) pour chaque session client. Si aucun ID de session n’est fourni (au niveau du client ou de la requête), ClickHouse générera un ID interne aléatoire pour chaque requête. |
| dict_parameter_format | ’json' | 'json’, ‘map’ | Contrôle si les requêtes paramétrées convertissent un dictionnaire Python en syntaxe JSON ou en syntaxe ClickHouse Map. json doit être utilisé pour les inserts dans des colonnes JSON, map pour les colonnes ClickHouse Map. |
| invalid_setting_action | ’error' | 'drop’, ‘send’, ‘error’ | Action à effectuer lorsqu’un paramètre invalide ou readonly est fourni (pour la session client ou la requête). Si drop, le paramètre sera ignoré, si send, le paramètre sera envoyé à ClickHouse, si error, une ProgrammingError côté client sera levée. |
| max_connection_age | 600 | Nombre maximal de secondes pendant lesquelles une connexion HTTP Keep-Alive sera maintenue ouverte/réutilisée. Cela évite de concentrer les connexions sur un seul nœud ClickHouse derrière un load balancer/proxy. La valeur par défaut est de 10 minutes. | |
| product_name | Chaîne transmise avec la requête à ClickHouse pour identifier l’application utilisant ClickHouse Connect. Elle doit être de la forme <nom du produit>&gl/<version du produit>. | ||
| readonly | 0 | 0, 1 | paramètres de ClickHouse implicites “read_only” pour les versions antérieures à 19.17. Peut être défini pour correspondre à la valeur ClickHouse “read_only” des paramètres afin de permettre le fonctionnement avec de très anciennes versions de ClickHouse. |
| send_os_user | True | True, False | Inclure l’utilisateur du système d’exploitation détecté dans les informations client envoyées à ClickHouse (chaîne HTTP User-Agent). |
| send_integration_tags | True | True, False | Inclure les bibliothèques/versions d’intégration utilisées (par ex. Pandas/SQLAlchemy/etc.) dans les informations client envoyées à ClickHouse (chaîne HTTP User-Agent). |
| use_protocol_version | True | True, False | Utiliser la version du protocole client. Cela est nécessaire pour les colonnes DateTime avec fuseau horaire, mais ne fonctionne pas avec la version actuelle de chproxy. |
| max_error_size | 1024 | Nombre maximal de caractères renvoyés dans les messages d’erreur du client. Utilisez 0 pour ce paramètre afin d’obtenir le message d’erreur ClickHouse complet. La valeur par défaut est de 1024 caractères. | |
| http_buffer_size | 10MB | Taille (en octets) du buffer “en mémoire” utilisé pour les requêtes HTTP en streaming. | |
| preserve_pandas_datetime_resolution | False | True, False | Lorsque la valeur est True et que pandas 2.x est utilisé, préserve la résolution Dtype de datetime64/timedelta64 (par ex. ’s’, ‘ms’, ‘us’, ‘ns’). Si False (ou avec pandas <2.x), convertit vers une résolution à la nanoseconde (‘ns’) pour assurer la compatibilité. |
Compression
enable_http_compression du serveur ClickHouse doit être défini sur 1, ou l’utilisateur doit être autorisé à modifier ce paramètre « par requête ».
La compression est contrôlée par le paramètre compress lors de l’appel de la méthode de fabrique clickhouse_connect.get_client. Par défaut, compress est défini sur True, ce qui active les paramètres de compression par défaut. Pour les requêtes exécutées avec les méthodes client query, query_np et query_df, ClickHouse Connect ajoute l’en-tête Accept-Encoding avec
les encodages lz4, zstd, br (brotli, si la bibliothèque brotli est installée), gzip et deflate aux requêtes exécutées avec la méthode client query (et indirectement, query_np et query_df). (Pour la majorité des requêtes, le serveur ClickHouse
renvoie une payload compressée avec zstd.) Pour les inserts, par défaut, ClickHouse Connect compresse les blocs d’insertion avec la compression lz4 et envoie l’en-tête HTTP Content-Encoding: lz4.
Le paramètre compress de get_client peut également être défini sur une méthode de compression spécifique, parmi lz4, zstd, br ou gzip. Cette méthode sera alors utilisée à la fois pour les inserts et pour les résultats de requête (si elle est prise en charge par le serveur ClickHouse). Les bibliothèques de compression requises zstd et lz4 sont désormais installées par défaut avec ClickHouse Connect. Si br/brotli est spécifié, la bibliothèque brotli doit être installée séparément.
Notez que les méthodes client raw* n’utilisent pas la compression spécifiée par la configuration du client.
Nous déconseillons également d’utiliser la compression gzip, car elle est nettement plus lente que les autres options, aussi bien pour la compression que pour la décompression des données.
Prise en charge des proxys HTTP
urllib3. Il reconnaît les variables d’environnement standard HTTP_PROXY et HTTPS_PROXY. Notez que l’utilisation de ces variables d’environnement s’appliquera à tout client créé avec la méthode clickhouse_connect.get_client. Vous pouvez aussi effectuer une configuration par client en utilisant les arguments http_proxy ou https_proxy de la méthode get_client. Pour plus de détails sur l’implémentation de la prise en charge des proxys HTTP, consultez la documentation urllib3.
Pour utiliser un proxy SOCKS, vous pouvez transmettre un SOCKSProxyManager de urllib3 comme argument pool_mgr à get_client. Notez que cela nécessite l’installation de la bibliothèque PySocks, soit directement, soit en utilisant l’option [socks] pour la dépendance urllib3.
Type de données JSON « ancien »
Object (ou Object('json')) est déprécié et doit être évité dans un environnement de production. ClickHouse Connect continue d’offrir une prise en charge limitée de ce type de données pour assurer la rétrocompatibilité. Notez que cette prise en charge n’inclut pas les requêtes censées renvoyer des valeurs JSON « de premier niveau » ou « parentes » sous forme de dictionnaires ou équivalent, et de telles requêtes entraîneront une exception.
« Nouveaux » types de données Variant/Dynamic/JSON (fonctionnalité expérimentale)
clickhouse-connect prend en charge à titre expérimental les nouveaux types ClickHouse — eux aussi expérimentaux — Variant, Dynamic et JSON.
Remarques sur l’utilisation
- Les données JSON peuvent être insérées soit sous la forme d’un dictionnaire Python, soit sous la forme d’une chaîne JSON contenant un objet JSON
{}. Les autres formes de données JSON ne sont pas prises en charge. - Les requêtes utilisant des sous-colonnes/chemins pour ces types renverront le type de la sous-colonne.
- Consultez la documentation principale de ClickHouse pour d’autres remarques sur l’utilisation.
Limites connues
- Chacun de ces types doit être activé dans les paramètres de ClickHouse avant de pouvoir être utilisé.
- Le « nouveau » type JSON est disponible à partir de la version 24.8 de ClickHouse.
- En raison de modifications du format interne,
clickhouse-connectn’est compatible avec les types Variant qu’à partir de la version 24.7 de ClickHouse. - Les objets JSON renvoyés ne contiendront qu’un nombre d’éléments égal à
max_dynamic_paths(1024 par défaut). Ce problème sera corrigé dans une prochaine version. - Les insertions dans des colonnes
Dynamicutiliseront toujours la représentation sous forme de chaîne de caractères de la valeur Python. Ce problème sera corrigé dans une prochaine version, une fois https://github.com/ClickHouse/ClickHouse/issues/70395 corrigé. - L’implémentation des nouveaux types n’a pas été optimisée en code C, de sorte que les performances peuvent être légèrement inférieures à celles de types de données plus simples et éprouvés.