> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-mintlify-8c05c8a2.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Options supplémentaires pour ClickHouse Connect # Options supplémentaires ClickHouse Connect offre plusieurs options supplémentaires pour des cas d’usage avancés.
## Paramètres globaux
Un petit nombre de paramètres régissent globalement le comportement de ClickHouse Connect. Ils sont accessibles depuis le paquet `common` de niveau supérieur : ```python theme={null} from clickhouse_connect import common common.set_setting('autogenerate_session_id', False) common.get_setting('invalid_setting_action') 'drop' ``` 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. Les paramètres globaux suivants sont actuellement définis : | 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 \\&gl/\. | | 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
ClickHouse Connect prend en charge la compression lz4, zstd, brotli et gzip, à la fois pour les résultats de requête et pour les inserts. Gardez toujours à l'esprit que l'utilisation de la compression implique généralement un compromis entre la bande passante réseau/la vitesse de transfert et l'utilisation du CPU (côté client comme côté serveur). Pour recevoir des données compressées, le paramètre `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
ClickHouse Connect ajoute une prise en charge basique des proxys HTTP à l’aide de la bibliothèque `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](https://urllib3.readthedocs.io/en/stable/advanced-usage.html#http-and-https-proxies). 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 »
Le type de données expérimental `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)
À partir de la version 0.8.0, `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](/fr/) 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-connect` n'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 `Dynamic` utiliseront 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](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.