{"id":18853721,"url":"https://github.com/bytehouse-cloud/driver-py","last_synced_at":"2025-08-23T10:11:01.538Z","repository":{"id":65736285,"uuid":"598495959","full_name":"bytehouse-cloud/driver-py","owner":"bytehouse-cloud","description":"Python Driver for ByteHouse","archived":false,"fork":false,"pushed_at":"2024-03-28T06:55:10.000Z","size":260,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-04-11T07:09:38.096Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bytehouse-cloud.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-02-07T08:24:47.000Z","updated_at":"2025-03-04T14:33:47.000Z","dependencies_parsed_at":"2023-02-19T16:01:41.853Z","dependency_job_id":null,"html_url":"https://github.com/bytehouse-cloud/driver-py","commit_stats":{"total_commits":2,"total_committers":2,"mean_commits":1.0,"dds":0.5,"last_synced_commit":"578a7f688f4abdebb70bdc1e082199c62e57cd59"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytehouse-cloud%2Fdriver-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytehouse-cloud%2Fdriver-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytehouse-cloud%2Fdriver-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bytehouse-cloud%2Fdriver-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bytehouse-cloud","download_url":"https://codeload.github.com/bytehouse-cloud/driver-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248860686,"owners_count":21173484,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T03:45:24.436Z","updated_at":"2025-04-14T10:23:58.467Z","avatar_url":"https://github.com/bytehouse-cloud.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ByteHouse Python Driver\n## Introduction \nByteHouse provides a Python driver that supports Python Database API Specification v2.0. The driver can be used with \nmost client tools/applications/BI tools which accept python driver following python DB API 2.0. The driver uses \nTCP/Native protocol to connect to ByteHouse.\n\n## Requirements\nPython v3.6 or higher\n\n## Installation from PyPI\nLatest release version can be installed from here:\n```commandline\npip install bytehouse-driver\n```\n## Installation from github\nCurrent development version can be installed from here:\n```commandline\npip install git+https://github.com/bytehouse-cloud/driver-py@master#egg=bytehouse-driver\n```\n## Creating ByteHouse Account\nYou need to create ByteHouse account in order to use Python Driver. You can simply create a free account with the \nprocess mentioned in our official website documentation: https://docs.bytehouse.cloud/en/docs/quick-start\u003cbr/\u003e\n\nYou can also create ByteHouse account through Volcano Engine by ByteDance: \nhttps://www.volcengine.com/product/bytehouse-cloud\n\n## ByteHouse Regions\nCurrently, the driver supports the following region names across different cloud providers. Alternatively, if you know\nthe host address of ByteHouse server, you can directly use host address \u0026 omit region name. \n\u003ctable\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eRegion Name\u003c/td\u003e\n        \u003ctd\u003eTarget Server\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eAP-SOUTHEAST-1\u003c/td\u003e\n        \u003ctd\u003egateway.aws-ap-southeast-1.bytehouse.cloud:19000\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n        \u003ctd\u003eVOLCANO-CN-NORTH-1\u003c/td\u003e\n        \u003ctd\u003ebytehouse-cn-beijing.volces.com:19000\u003c/td\u003e\n    \u003c/tr\u003e\n\u003c/table\u003e\n\n## URI format for Connection \u0026 Authentication\n### Region \u0026 Password Format\n*Required parameters:* `region` `account` `user` `password`\n```python\n'bytehouse:///?region={}\u0026account={}\u0026user={}\u0026password={}'.format(REGION, ACCOUNT, USER, PASSWORD)\n```\n### Host Address \u0026 Password Format\n*Required parameters:* `host` `port` `account` `user` `password`\n```python\n'bytehouse://{}:{}/?account={}\u0026user={}\u0026password={}'.format(HOST, PORT, ACCOUNT, USER, PASSWORD)\n```\n\u003e For API Key authentication, user is always 'bytehouse'\n### Region \u0026 API Key Format\n*Required parameters:* `region` `password`\n```python\n'bytehouse:///?region={}\u0026user=bytehouse\u0026password={}'.format(REGION, API_KEY)\n```\n### Host Address \u0026 API Key Format\n*Required parameters:* `host` `port` `password`\n```python\n'bytehouse://{}:{}/?user=bytehouse\u0026password={}'.format(HOST, PORT, API_KEY)\n```\n## Virtual warehouse \u0026 Role Management\nConnection initialiaztion with ByteHouse always assumes default virtual warehouse \u0026 active role, therefore these values\ncannot be empty. So before using the driver, users need to set/ensure these values through \nhttps://console.bytehouse.cloud/account/details\n![Default Settings](./default_settings.png)\n## Constructing Client Object\n### Passing parameters\n```python\nfrom bytehouse_driver import Client\n\nclient = Client(\n    region=REGION,\n    account=ACCOUNT,\n    user=USER,\n    password=PASSWORD\n)\n```\n### From URI\n```python\nfrom bytehouse_driver import Client\n\nclient = Client.from_url('bytehouse:///?region={}\u0026account={}\u0026user={}\u0026password{}'.format(\n     REGION, ACCOUNT, USER, PASSWORD)\n)\n```\n## Performing SQL queries\n```python\nfrom bytehouse_driver import Client\n\nclient = Client(\n    region=REGION,\n    account=ACCOUNT,\n    user=USER,\n    password=PASSWORD\n)\n# DDL Query\nclient.execute(\"CREATE DATABASE demo_db\")\nclient.execute(\"CREATE TABLE demo_db.demo_tb (id INT) ENGINE=CnchMergeTree() ORDER BY tuple()\")\n\n# DML Query\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", [[1], [2], [3]])\n\n# DQL Query\nresult_set = client.execute(\"SELECT * FROM demo_db.demo_tb\")\nfor result in result_set:\n    print(result)\n\nclient.execute(\"DROP DATABASE demo_db\")\n```\n## Supported Datatypes\n| **ByteHouse type**                                                       | **Python type for INSERT**               | **Python type for SELECT**  |\n|----------------------------------------------------------------------|--------------------------------------|-------------------------|\n| Integar family (UInt8/UInt16/UInt32/UInt64 / Int8/Int16/Int32/Int64) | `int` `long`                             | `int`                     |\n| Float family (Float32/Float64)                                       | `float` `int` `long`                       | `float`                   |\n| String                                                               | `str` `bytes`                            | `str` `bytes`               |\n| FixedString                                                          | `str` `bytes`                            | `str` `bytes`               |\n| Nullable\u003cT\u003e                                                          | `None` `T`                               | `None` `T`                  |\n| Date                                                                 | `date` `datetime`                        | `date`                    |\n| DateTime                                                             | `datetime` `int` `long`                    | `datetime`                |\n| Array                                                                | `list` `tuple`                           | `list`                    |\n| Enum family                                                          | `Enum` `int` `long` `str`                    | `str`                     |\n| Decimal                                                              | `Decimal` `float` `int` `long`               | `Decimal`                 |\n| IP family                                                            | `IPv4Address` `IPv6Address` `int` `long` `str` | `IPv4Address` `IPv6Address` |\n| Map                                                                  | `dict`                                 | `dict`                    |\n| LowCardinality\u003cT\u003e                                                    | `T`                                    | `T`                       |\n| UUID                                                                 | `UUID` `str`                             | `UUID`                    |\n### Settings types_check=True\nDefault value for 'types_check' is false for performance. If set to true, then explicit type checking and transformation\nwould happen before passing the data onto the server. Recommended to set it to true, for float/decimal or any other \ntypes, where raw data needs to be transformed into appropriate type. \n### Integer family\n`Int8` `Int16` `Int32` `Int64` `UInt8` `UInt16` `UInt32` `UInt64`\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Int8, b Int16, c Int32, d Int64, e UInt8, f UInt16, g UInt32, h UInt64) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [\n    (-10, -300, -123581321, -123581321345589144, 10, 300, 123581321, 123581321345589144)\n]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Float family\n`Float32` `Float64`\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Float32, b Float64) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [\n    (3.4028235e38, 3.4028235e38),\n    (3.4028235e39, 3.4028235e39),\n    (-3.4028235e39, 3.4028235e39),\n    (1, 2)\n]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data, types_check=True)\n```\n### String\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a String) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [('axdfgrt', )]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### FixedString\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a FixedString(4)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [('a', ), ('bb', ), ('ccc', ), ('dddd', ), ('я', )]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Nullable\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Nullable(Int32)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(3, ), (None, ), (2, )]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Date\n```python\nfrom datetime import date, datetime\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Date) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(date(1970, 1, 1), ), (datetime(2015, 6, 6, 12, 30, 54), )]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### DateTime\n```python\nfrom datetime import datetime\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a DateTime) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(datetime(2015, 6, 6, 12, 30, 54), ), (1530211034,)]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Array\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Array(Int32)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [([], ), ([100, 500], )]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Enum family\n`Enum8` `Enum16`\n```python\nfrom enum import IntEnum\n\nclass A(IntEnum):\n    hello = -1\n    world = 2\n\nclass B(IntEnum):\n    foo = -300\n    bar = 300\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Enum8('hello' = -1, 'world' = 2), b Enum16('foo' = -300, 'bar' = 300)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(A.hello, B.bar), (A.world, B.foo), (-1, 300), (2, -300)]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### Decimal\n```python\nfrom decimal import Decimal\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Decimal(9, 5)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(Decimal('300.42'),), (300.42,), (-300,)]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data, types_check=True)\n```\n### IP family\n`IPv4` `IPv6`\n```python\nfrom ipaddress import IPv6Address, IPv4Address\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a IPv4, b IPv6) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [\n    (IPv4Address(\"10.0.0.1\"), IPv6Address('79f4:e698:45de:a59b:2765:28e3:8d3a:35ae'),),\n]\nclient.execute(\"INSERT INTO demo_db.demo_tb (a, b) VALUES\", data)\n```\n### Map\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a Map(String, UInt64)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [\n    ({},),\n    ({'key1': 1},),\n    ({'key1': 2, 'key2': 20},),\n    ({'key1': 3, 'key2': 30, 'key3': 50},)\n]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### LowCardinality\n```python\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a LowCardinality(UInt8)) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [(x,) for x in range(255)]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n### UUID\n```python\nfrom uuid import UUID\n\nclient.execute(\"CREATE TABLE demo_db.demo_tb (a UUID) ENGINE=CnchMergeTree() ORDER BY tuple()\")\ndata = [\n    (UUID('c0fcbba9-0752-44ed-a5d6-4dfb4342b89d'),),\n    ('2efcead4-ff55-4db5-bdb4-6b36a308d8e0',)\n]\nclient.execute(\"INSERT INTO demo_db.demo_tb VALUES\", data)\n```\n## Cursor Support: DB API 2.0\nCursors are supported following DB API 2.0 specifications. Cursors are created by the connection.cursor() method. They \nare bound to the connection for the entire lifetime and all the commands are executed in the context of the database \nsession wrapped by the connection.\n```python\nfrom bytehouse_driver import connect\n\nkwargs = {}\nkwargs.setdefault('region', REGION)\nkwargs.setdefault('account', ACCOUNT)\nkwargs.setdefault('user', USER)\nkwargs.setdefault('password', PASSWORD)\n\nconnection = connect(**kwargs)\ncursor = connection.cursor()\n\ncursor.execute(\"DROP TABLE IF EXISTS cursor_tb\")\ncursor.execute(\"CREATE TABLE cursor_tb (id INT) ENGINE=CnchMergeTree() ORDER BY tuple()\")\n\ncursor.executemany(\"INSERT INTO cursor_tb (id) VALUES\", [{'id': 100}])\n\nresult_set = cursor.execute(\"SELECT * FROM cursor_tb\")\nfor result in result_set:\n    print(result)\n\nconnection.close()\n```\n## User defined query-id\nUser can manually supply query-id for each query execution. Users are encouraged to maintain uniqueness or relevancy \nof the query-id string. If not set, then server will assign a randomly generated UUID as the query-id. \n```python\nclient = Client(\n    region=self.region,\n    account=self.account,\n    user=self.user,\n    password=self.password\n)\nclient.execute(\"SELECT 1\", query_id=\"ba2e2cea-2a11-4926-a0b8-e694ded0cf65\")\n```\n## Local Development\nChange `setup.cfg` file to include your connection credentials. For running tests locally, follow these steps:\n```python\npython testsrequire.py \u0026\u0026 python setup.py develop\npy.test -v\n```\n## Issue Reporting\nIf you have found a bug or if you have a feature request, please report them at this repository issues section. \nAlternatively, you can directly create an issue with our support platform here: https://bytehouse.cloud/support\n## Original Author\nByteHouse wants to thank original author @Konstantin Lebedev \u0026 ClickHouse for original contribution to this driver. \n## License\nThis project is distributed under the terms of the MIT license: http://www.opensource.org/licenses/mit-license.php\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytehouse-cloud%2Fdriver-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbytehouse-cloud%2Fdriver-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbytehouse-cloud%2Fdriver-py/lists"}