{"id":10187,"library":"questdb","title":"QuestDB Python Client","description":"The `questdb` library is the official Python client for QuestDB, a high-performance open-source SQL database for time-series and analytics. It provides efficient ingestion of data via InfluxDB Line Protocol (ILP) over TCP or HTTP, supporting various Python data types, Pandas DataFrames, and NumPy arrays. The current version is 4.1.0, and releases are typically feature-driven, often aligning with new QuestDB server capabilities.","status":"active","version":"4.1.0","language":"python","source_language":"en","source_url":"https://github.com/questdb/py-questdb-client/","tags":["database client","time series","QuestDB","dataframe","ingestion","ILP"],"install":[{"cmd":"pip install questdb","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for ingesting n-dimensional NumPy arrays into QuestDB.","package":"numpy","optional":true},{"reason":"Required for high-performance ingestion of Pandas DataFrames.","package":"pandas","optional":true},{"reason":"Provides improved performance when ingesting Pandas DataFrames containing Decimal types.","package":"pyarrow","optional":true}],"imports":[{"wrong":"from questdb import Sender","symbol":"Sender","correct":"import questdb"}],"quickstart":{"code":"import os\nimport time\nfrom questdb.client import Sender\nfrom datetime import datetime, timezone\n\n# Configure QuestDB connection (ILP over HTTP)\n# Use os.environ.get for security and flexibility in deployment\nQDB_HOST = os.environ.get(\"QDB_HOST\", \"localhost\")\nQDB_PORT = os.environ.get(\"QDB_PORT\", \"9000\")\nQDB_AUTH = os.environ.get(\"QDB_AUTH\", \"\") # Format: \"username:token\"\n\nconf = f'http::addr={QDB_HOST}:{QDB_PORT};'\nif QDB_AUTH:\n    conf += f'auth={QDB_AUTH};' # Assumes auth syntax for QuestDB 7.0+\nelse:\n    print(\"Warning: QDB_AUTH environment variable not set. Connecting without authentication.\")\n\ntry:\n    with Sender.from_conf(conf) as sender:\n        # Ingest a single row of data\n        sender.row(\n            \"sensor_data\",\n            columns={\n                \"location\": \"london\",\n                \"temperature\": 15.5,\n                \"humidity\": 70,\n                \"event_time\": datetime.now(timezone.utc)\n            },\n            at=datetime.now(timezone.utc) # QuestDB timestamp column\n        )\n\n        # Ingest another row, demonstrating nanosecond precision (client v4.0.0+)\n        # Note: Requires QuestDB server 9.1.0+ for nanosecond TIMESTAMP_NS type\n        nanos_timestamp = int(time.time_ns()) # Current time in nanoseconds\n        sender.row(\n            \"sensor_data\",\n            columns={\n                \"location\": \"paris\",\n                \"temperature\": 18.2,\n                \"humidity\": 65,\n                \"event_time\": datetime.now(timezone.utc)\n            },\n            at=nanos_timestamp # This sends nanosecond precision\n        )\n\n        sender.flush() # Ensure all buffered data is sent\n        print(\"Data sent successfully to QuestDB!\")\n\nexcept Exception as e:\n    print(f\"Failed to send data: {e}\")\n    print(f\"Please ensure QuestDB server is running and accessible at http://{QDB_HOST}:{QDB_PORT}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `Sender` using a configuration string for ILP over HTTP and ingest two rows of data. It also highlights the support for nanosecond precision timestamps introduced in version 4.0.0. The connection details can be configured via environment variables for easy deployment."},"warnings":[{"fix":"Ensure QuestDB server is 9.1.0+ to fully utilize nanosecond precision with `TIMESTAMP_NS` columns. For older servers, be mindful of timestamp precision or convert to microseconds before sending.","message":"Version 4.0.0 introduced support for nanosecond precision timestamps via the `.row()` API. While it enhances precision, users relying on older QuestDB servers (pre-9.1.0) might encounter issues or loss of precision if sending nanoseconds to `TIMESTAMP` columns, which only support microsecond precision. For full nanosecond support, QuestDB 9.1.0+ is required with `TIMESTAMP_NS` columns.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Upgrade QuestDB server to 9.0.0+ to enable n-dimensional array ingestion. Ensure NumPy arrays are of `float64` dtype.","message":"Version 3.0.0 introduced support for n-dimensional NumPy arrays and a new protocol version (2) for this feature. This requires QuestDB server 9.0.0 or higher. Attempting to send array data to older QuestDB servers will not work.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Review `Sender.from_conf()` arguments for HTTP configuration and update error handling to catch `IngressError` for server-side errors.","message":"Version 2.0.0 was a major release introducing ILP over HTTP, which became the preferred method for sending data due to better error feedback. If migrating from v1.x (TCP-only), connection configurations (`Sender.from_conf()`) and error handling (e.g., `IngressError`) will need to be updated.","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade QuestDB server to 9.2.0+ to use the `DECIMAL` data type. If using an older server, convert `decimal.Decimal` objects to `float` or `string` before sending, mindful of potential precision loss.","message":"Version 4.1.0 added support for `decimal.Decimal` objects. This feature requires QuestDB server 9.2.0 or newer to correctly handle the native `DECIMAL(precision, scale)` column type. Sending decimals to older server versions will likely result in type errors or incorrect ingestion.","severity":"gotcha","affected_versions":">=4.1.0"},{"fix":"Upgrade to `questdb>=2.0.2` or explicitly set a higher `auto_flush_rows` value (e.g., 75000) when initializing the `Sender` for HTTPS connections.","message":"In versions 2.0.0 and 2.0.1, the `auto_flush_rows` default for HTTPS connections was incorrectly set to a low value (600 rows), leading to suboptimal performance due to frequent flushes. This was fixed in v2.0.2.","severity":"gotcha","affected_versions":"2.0.0, 2.0.1"}],"env_vars":null,"search_vec":"'4.1.0':58 'align':67 'analyt':28 'array':53 'capabl':72 'client':3,11,74 'current':55 'data':34,47 'databas':22,73 'datafram':50,78 'driven':65 'effici':31 'featur':64 'feature-driven':63 'high':16 'high-perform':15 'http':43 'ilp':39,80 'influxdb':36 'ingest':32,79 'librari':6 'line':37 'new':69 'numpi':52 'offici':9 'often':66 'open':19 'open-sourc':18 'panda':49 'perform':17 'protocol':38 'provid':30 'python':2,10,46 'questdb':1,5,13,70,77 'releas':60 'seri':26,76 'server':71 'sourc':20 'sql':21 'support':44 'tcp':41 'time':25,75 'time-seri':24 'type':48 'typic':62 'various':45 'version':56 'via':35","created_at":"2026-04-17T01:22:49.997768+00:00","updated_at":"2026-04-17T01:22:49.997768+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"4.1.0","cli_name":"","cli_version":null,"type":"library","homepage":"https://questdb.com/","github":"https://github.com/questdb/py-questdb-client","docs":"https://py-questdb-client.readthedocs.io/en/latest/index.html","changelog":"https://py-questdb-client.readthedocs.io/en/latest/changelog.html","pypi":"https://pypi.org/project/questdb/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["database","data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-07-03","last_verified":"2026-07-03","next_check":"2026-08-02","install_tag":null}}