QuestDB Client Library for Python

https://py-questdb-client.readthedocs.io/en/latest
Admin
The official Python client library for QuestDB that implements InfluxDB Line Protocol over HTTP and...
Tokens:111,336
Snippets:738
Trust Score:8.3
Update:1 day ago
Show doc for...
Tokens:
Raw
### Buffer.dataframe() example: pandas DataFrame to ILP

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Shows how to create a Buffer, build a pandas DataFrame, and call dataframe() with table_name, at, and symbols parameters. The example includes a placeholder for buffer setup and a flush call, and notes that the index column is never serialized.

```python
import pandas as pd
import questdb as qi

buf = qi.ingress.Buffer(protocol_version=2)
# ...

df = pd.DataFrame({
    'location': ['London', 'Managua', 'London'],
    'temperature': [24.5, 35.0, 25.5],
    'humidity': [0.5, 0.6, 0.45],
    'ts': pd.date_range('2021-07-01', periods=3)})
buf.dataframe(
    df, table_name='weather', at='ts', symbols=['location'])

# ...
sender.flush(buf)
```

--------------------------------

### Verify installation with version and connect check

Source: https://py-questdb-client.readthedocs.io/en/latest/installation.html

Interactive Python shell commands to verify the wheel installation: import questdb, check __version__, and confirm connect is available.

```python
>>> import questdb
>>> questdb.__version__
'5.0.0'
>>> questdb.connect
<function connect at 0x104b68240>
```

--------------------------------

### Install minimal QuestDB client

Source: https://py-questdb-client.readthedocs.io/en/latest/index.html

Install the library without the 'dataframe' extra, sufficient for sending individual rows.

```bash
python3 -m pip install -U questdb
```

--------------------------------

### Install QuestDB with dataframe support

Source: https://py-questdb-client.readthedocs.io/en/latest/index.html

Install the latest version of the library (5.0.0) with the 'dataframe' extra, which is required for Pandas dataframe ingestion.

```bash
python3 -m pip install -U questdb[dataframe]
```

--------------------------------

### questdb.Sender.__enter__

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Call Sender.establish() at the start of a with block.

```APIDOC
## __enter__()

### Description
Call Sender.establish() at the start of a `with` block.

### Method
__enter__

### Returns
Sender - The sender instance.
```

--------------------------------

### questdb.connect() usage examples

Source: https://py-questdb-client.readthedocs.io/en/latest/_modules/questdb.html

Two usage examples for questdb.connect(): one using a configuration string with 'ws::addr=localhost:9000;' and another using host and port keywords. The first example shows sending a row, writing a dataframe, and querying.

```python
with questdb.connect('ws::addr=localhost:9000;') as db:
    with db.sender() as sender:
        sender.row('trades', symbols={'sym': 'BTC-USD'},
                   columns={'price': 62000.0}, at=ts)
    db.dataframe(df, table_name='trades', at='ts')
    result = db.query('SELECT * FROM trades LIMIT 10')
```

```python
with questdb.connect(host='localhost', port=9000) as db:
    ...
```

--------------------------------

### connect() quick start: pooled sender and query

Source: https://py-questdb-client.readthedocs.io/en/latest/examples.html

Leases a pooled sender from a QuestDB handle, writes a row over QWP/WebSocket, flushes with wait=True, then runs a bind-parameter query into pandas. Uses TimestampNanos.now() and handles QuestDBError with code and in_doubt.

```python
import sys

import questdb
from questdb import QuestDBError, TimestampNanos


def example(host: str = 'localhost', port: int = 9000):
    try:
        conf = f'ws::addr={host}:{port};'
        with questdb.connect(conf) as db:
            # Lease a pooled sender for row-by-row ingestion.
            # Take one lease per thread; leaving the `with` block
            # returns it to the pool.
            with db.sender() as sender:
                sender.row(
                    'trades',
                    symbols={
                        'symbol': 'ETH-USD',
                        'side': 'sell'},
                    columns={
                        'price': 2615.54,
                        'amount': 0.00044},
                    at=TimestampNanos.now())

                # Pooled rows auto-publish at the configured thresholds.
                # `wait=True` also publishes any partial batch, then blocks
                # until the server acknowledges everything on this lease.
                sender.flush(wait=True)

            # Query with positional bind parameters ($1..$N) and read the
            # result straight into pandas. Fully draining the result
            # returns its connection to the pool.
            frame = db.query(
                'SELECT symbol, price, amount FROM trades '
                'WHERE symbol = $1 LIMIT 5',
                ['ETH-USD'],
            ).to_pandas()
            print(frame)

    except QuestDBError as e:
        sys.stderr.write(
            f'Got error: {e} (code={e.code}, in_doubt={e.in_doubt})\n')


if __name__ == '__main__':
    example()
```

--------------------------------

### Install row-only via poetry

Source: https://py-questdb-client.readthedocs.io/en/latest/installation.html

Adds the questdb package without extras using Poetry.

```bash
poetry add questdb
```

--------------------------------

### Install with dataframe extra via poetry

Source: https://py-questdb-client.readthedocs.io/en/latest/installation.html

Adds the questdb package with the 'dataframe' extra using Poetry.

```bash
poetry add questdb[dataframe]
```

--------------------------------

### Load Pandas DataFrame from Parquet and query QuestDB

Source: https://py-questdb-client.readthedocs.io/en/latest/examples.html

This example writes a Pandas DataFrame to a Parquet file, then reads it and ingests it into QuestDB using the dataframe's index name as the table name. It also demonstrates querying QuestDB and materializing the result as Pandas. The example relies on the dataframe's index name to determine the table name.

```python
import questdb
import pandas as pd


def write_parquet_file():
    df = pd.DataFrame({
        'location': pd.Categorical(
            ['BP-5541', 'UB-3355', 'SL-0995', 'BP-6653']),
        'provider': pd.Categorical(
            ['BP Pulse', 'Ubitricity', 'Source London', 'BP Pulse']),
        'speed_kwh': pd.Categorical(
            [50, 7, 7, 120]),
        'connector_type': pd.Categorical(
            ['Type 2 & 2+CCS', 'Type 1 & 2', 'Type 1 & 2', 'Type 2 & 2+CCS']),
        'current_type': pd.Categorical(
            ['dc', 'ac', 'ac', 'dc']),
        'price_pence':
            [54, 34, 32, 59],
        'in_use':
            [True, False, False, True],
        'ts': [
            pd.Timestamp('2022-12-30 12:15:00'),
            pd.Timestamp('2022-12-30 12:16:00'),
            pd.Timestamp('2022-12-30 12:18:00'),
            pd.Timestamp('2022-12-30 12:19:00')]})
    name = 'ev_chargers'
    df.index.name = name  # We set the dataframe's index name here!
    filename = f'{name}.parquet'
    df.to_parquet(filename)
    return filename


def example(host: str = 'localhost', port: int = 9000):
    filename = write_parquet_file()

    df = pd.read_parquet(filename)
    with questdb.connect(f"ws::addr={host}:{port};") as db:
        # Ingress: bulk-load a Pandas DataFrame into QuestDB.
        # Note: Table name is looked up from the dataframe's index name.
        db.dataframe(df, at='ts')

        # Egress: query QuestDB and materialise the result as Pandas.
        with db.query(
                "SELECT x AS charger_id, "
                "x * 25 AS speed_kwh "
                "FROM long_sequence(3)") as result:
            queried = result.to_pandas()
        print(queried)


if __name__ == '__main__':
    example()
```

--------------------------------

### Send data over HTTP with Sender.from_conf

Source: https://py-questdb-client.readthedocs.io/en/latest/changelog.html

Example of constructing a sender from a configuration string and sending data over HTTP. The flush() call will raise QuestDBError if there is an error from the server.

```python
conf = 'http::addr=localhost:9000;'
with Sender.from_conf(conf) as sender:
    sender.row(...)
    sender.dataframe(...)

    # Will raise `QuestDBError` if there is an error from the server.
    sender.flush()
```

--------------------------------

### Production configuration with TLS, token auth, multi-host, and spool

Source: https://py-questdb-client.readthedocs.io/en/latest/examples.html

Use this example for a production deployment: it connects over WSS with OS trust roots, a bearer token, and a multi-node address list. It also enables a disk-backed store-and-forward spool with a sender_id for replaying unacknowledged frames after restart. The connection listener prints events to stderr, and the sender flushes with wait=True to block until the server acknowledges all published data.

```python
import sys

import questdb
from questdb import QuestDBError, TimestampNanos


def on_connection_event(event):
    print(event.kind, event.host, event.port, event.cause_msg,
          file=sys.stderr)


def example():
    # A production-shaped configuration: TLS with OS trust roots, a
    # bearer token, every node of the deployment in one addr list, and
    # a disk-backed store-and-forward spool that replays
    # unacknowledged frames after a process restart with the same
    # sender_id. For HTTP basic auth, replace the token with
    # 'username=...;password=...;'.
    conf = (
        'wss::addr=db-primary.example.com:9000,db-replica.example.com:9000;'
        'token=YOUR_BEARER_TOKEN;'
        'tls_ca=os_roots;'
        'sf_dir=/var/spool/questdb;'
        'sender_id=ingest-01;'
    )
    try:
        with questdb.connect(
                conf, connection_listener=on_connection_event) as db:
            info = db.server_info()
            print('connected to', info.role)

            with db.sender() as sender:
                sender.row(
                    'trades',
                    symbols={'symbol': 'ETH-USD'},
                    columns={'price': 2615.54, 'amount': 0.00044},
                    at=TimestampNanos.now())
                # Block until the server acknowledges everything
                # published on this lease.
                sender.flush(wait=True)

            print('events delivered:', db.connection_events_delivered)

    except QuestDBError as e:
        sys.stderr.write(
            f'Got error: {e} (code={e.code}, in_doubt={e.in_doubt})\n')
        sys.exit(1)


if __name__ == '__main__':
    example()
```

--------------------------------

### Create table with DECIMAL column

Source: https://py-questdb-client.readthedocs.io/en/latest/troubleshooting.html

Pre-create a table with a DECIMAL column before ingesting decimal data, as DECIMAL columns cannot be auto-created. The example uses DECIMAL(18, 6) and a TIMESTAMP_NS column with a TIMESTAMP designation and PARTITION BY DAY.

```sql
CREATE TABLE my_table (
    symbol SYMBOL,
    price DECIMAL(18, 6),
    timestamp TIMESTAMP_NS
) TIMESTAMP(timestamp) PARTITION BY DAY;
```

--------------------------------

### Create Sender from environment variable

Source: https://py-questdb-client.readthedocs.io/en/latest/conf.html

Shows how to create a Sender using the QDB_CLIENT_CONF environment variable via Sender.from_env().

```python
from questdb import Sender

with Sender.from_env() as sender:
    ...
```

--------------------------------

### Log outgoing messages with legacy buffer

Source: https://py-questdb-client.readthedocs.io/en/latest/troubleshooting.html

Log the pending payload when constructing buffers explicitly through the legacy questdb.ingress shim. This example uses bytes(buffer) to get the payload, decodes it, and logs it with indentation before flushing the buffer.

```python
import logging
import textwrap

buffer = sender.new_buffer()
# buffer.row(...)
# buffer.row(...)
# ...
pending = bytes(buffer).decode('utf-8', errors='replace')
logging.info('About to flush:\n%s', textwrap.indent(pending, '    '))
sender.flush(buffer)
```

--------------------------------

### Log outgoing messages with Sender object

Source: https://py-questdb-client.readthedocs.io/en/latest/troubleshooting.html

Log the pending payload before flushing when using the Sender object. This example uses bytes(sender) to get the payload, decodes it, and logs it with indentation. Note that QWP transports encode at flush time, so bytes(sender) is empty for them.

```python
import logging
import textwrap

with Sender.from_conf(...) as sender:
    # sender.row(...)
    # sender.row(...)
    # ...
    pending = bytes(sender).decode('utf-8', errors='replace')
    logging.info('About to flush:\n%s', textwrap.indent(pending, '    '))
    sender.flush()
```

--------------------------------

### questdb.QuestDB.from_conf()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Creates a QuestDB instance from a configuration.

```APIDOC
## questdb.QuestDB.from_conf()

### Description
Creates a QuestDB instance from a configuration.

### Method
from_conf()

### Parameters
None

### Returns
QuestDB instance
```

--------------------------------

### questdb.connect()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Establishes a connection to a QuestDB instance. This is the entry point for using the client.

```APIDOC
## questdb.connect()

### Description
Establishes a connection to a QuestDB instance. This is the entry point for using the client.

### Method
connect

### Signature
questdb.connect()

### Parameters
None documented.

### Returns
A connection object (e.g., questdb.QuestDB or questdb.Sender).

### Example
```python
import questdb
conn = questdb.connect()
```
```

--------------------------------

### Sender.transaction()

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Starts an HTTP Transactions block.

```APIDOC
## Sender.transaction()

### Description
Start a HTTP Transactions block.

### Method
transaction(table_name: str)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **table_name** (str) - Required - The name of the table for the transaction.

### Returns
None
```

--------------------------------

### Sender.establish

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Prepares the sender for use. If using ILP/HTTP, this initializes the HTTP connection pool.

```APIDOC
## Sender.establish

### Description
Prepare the sender for use. If using ILP/HTTP this will initialize the HTTP connection pool.

### Method
Python method

### Signature
`establish()`
```

--------------------------------

### Connect with QuestDB using ws protocol

Source: https://py-questdb-client.readthedocs.io/en/latest/conf.html

Shows how to create a QuestDB handle using a configuration string with the ws protocol. The configuration string is passed to questdb.connect(). The keys are case-sensitive and only addr is mandatory.

```python
import questdb

conf = "ws::addr=localhost:9000;username=admin;password=quest;"
with questdb.connect(conf) as db:
    ...
```

--------------------------------

### questdb.TimestampNanos.now()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Class method of TimestampNanos to get the current timestamp in nanoseconds.

```APIDOC
## Method: questdb.TimestampNanos.now()

### Description
Class method of TimestampNanos to get the current timestamp in nanoseconds.

### Method
`now()`
```

--------------------------------

### Customising .from_env() with auto-flush interval

Source: https://py-questdb-client.readthedocs.io/en/latest/sender.html

Shows how to load a configuration string from an environment variable and customise it with a 10-second auto-flush interval. The environment variable QDB_CLIENT_CONF is set to an HTTP configuration string.

```bash
export QDB_CLIENT_CONF='http::addr=localhost:9000;'
```

```python
from questdb import Sender, Protocol
from datetime import timedelta

with Sender.from_env(auto_flush_interval=timedelta(seconds=10)) as sender:
    ...
```

--------------------------------

### questdb.TimestampMicros.now()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Class method of TimestampMicros to get the current timestamp in microseconds.

```APIDOC
## Method: questdb.TimestampMicros.now()

### Description
Class method of TimestampMicros to get the current timestamp in microseconds.

### Method
`now()`
```

--------------------------------

### connect(conf_str=None, *, host=None, port=None, tls=None, connection_listener=None, connection_event_inbox_capacity=0, error_handler=None, error_event_inbox_capacity=0, **params) -> QuestDB

Source: https://py-questdb-client.readthedocs.io/en/latest/_modules/questdb.html

Connects to a QuestDB deployment and returns a QuestDB handle. This is the deployment-level entry point for new code, owning connection pools for ingestion and queries.

```APIDOC
## connect(conf_str=None, *, host=None, port=None, tls=None, connection_listener=None, connection_event_inbox_capacity=0, error_handler=None, error_event_inbox_capacity=0, **params) -> QuestDB

### Description
Connect to a QuestDB deployment and return a QuestDB handle. This is the deployment-level entry point and the default for new code. The handle owns connection pools for both ingestion and queries: borrow row-building senders with QuestDB.sender, bulk-load DataFrames with QuestDB.dataframe, run SQL with QuestDB.query, and borrow reader leases with QuestDB.reader. The standalone Sender is the complementary connection-level API (one sender = one connection) for point-to-point needs: ILP/HTTP transactions, ILP/TCP, QWP/UDP datagrams, and manually driven single ws connections.

### Method
connect

### Parameters
#### Parameters
- **conf_str** (Optional[str]) - Optional - QWP/WebSocket configuration string (``ws::addr=host:port;`` or ``wss::...``).
- **host** (Optional[str]) - Optional - Host of the QuestDB deployment.
- **port** (Union[int, str, None]) - Optional - Port of the QuestDB deployment (default 9000).
- **tls** (Optional[bool]) - Optional - Whether to use TLS (default False).
- **connection_listener** (Optional[Callable[[ConnectionEvent], None]]) - Optional - Receives one ConnectionEvent per connection-state transition.
- **connection_event_inbox_capacity** (int) - Optional - Capacity of the connection event inbox.
- **error_handler** (Optional[Callable[[SenderError], None]]) - Optional - Receives one SenderError per server rejection.
- **error_event_inbox_capacity** (int) - Optional - Capacity of the error event inbox.
- **params** (Any) - Optional - Additional keyword arguments added as configuration-string settings (e.g., username='u', sender_pool_max=4). Booleans map to on/off, while tls_verify=False maps to unsafe_off.

### Request Example
```python
import questdb

# Example usage
handle = questdb.connect(
    host='localhost',
    port=9000,
    tls=False,
    username='admin',
    password='quest',
    sender_pool_max=4,
    lazy_connect=True,
)
```

### Response
#### Success Response
Returns a QuestDB handle.

#### Response Example
```python
# QuestDB handle
handle = questdb.connect(host='localhost', port=9000)
```

### Notes
- Pass either a QWP/WebSocket configuration string or the equivalent keywords: host, port (default 9000) and tls (default False) select the endpoint.
- Any further keyword arguments are added as configuration-string settings; a setting present both in the string and as a keyword raises ValueError.
- By default connect() opens the warm minimums up front and fails fast when the server is unreachable or rejects the credentials. Set lazy_connect=True (or lazy_connect=true in the string) to tolerate a down server at startup.
- Pooled row senders auto-flush by default at 1,000 rows, 100 milliseconds, or a cap-derived byte threshold. Set auto_flush_bytes='off' to disable only the byte trigger, or auto_flush='off' to disable all automatic publishing.
- connection_listener receives one ConnectionEvent per connection-state transition; error_handler receives one SenderError per server rejection (without it rejections are logged through the questdb logger). Each runs on its own dispatcher thread.
- When a handler or listener closes over the returned handle, call QuestDB.close explicitly (or use with) rather than leaving the handle to the garbage collector.
```

--------------------------------

### Polars DataFrame ingest and query example

Source: https://py-questdb-client.readthedocs.io/en/latest/examples.html

This example connects to QuestDB over WebSocket, ingests a Polars DataFrame into tables 'trades' and 'trades_chunked' using `db.dataframe()`, and queries data back into a Polars DataFrame with `result.to_polars()`. It demonstrates the Arrow PyCapsule Interface for direct ingestion. Requires the `polars` library.

```python
"""Polars DataFrame ingest and query example.

`QuestDB.dataframe()` accepts polars `DataFrame` and `LazyFrame` directly,
riding the Arrow PyCapsule Interface (`__arrow_c_stream__`) straight into
`column_sender_flush_arrow_batch`. `QuestDB.query()` can materialise query
results as a polars `DataFrame` with `QueryResult.to_polars()`.
"""

import questdb
from questdb import QuestDBError
import datetime
import sys


def example(host: str = 'localhost', port: int = 9000):
    import polars as pl

    df = pl.DataFrame({
        'symbol': ['ETH-USD', 'BTC-USD', 'ETH-USD'],
        'side':   ['sell', 'buy', 'buy'],
        'price':  [2615.54, 67234.12, 2620.88],
        'amount': [0.00044, 0.0012, 0.00033],
        'ts': [
            datetime.datetime(2025, 1, 1, 12, 0, 0),
            datetime.datetime(2025, 1, 1, 12, 0, 1),
            datetime.datetime(2025, 1, 1, 12, 0, 2),
        ],
    })

    try:
        conf = f'ws::addr={host}:{port};'
        with questdb.connect(conf) as db:
            # Ingress: publish a Polars DataFrame into QuestDB.
            db.dataframe(df, table_name='trades', at='ts')

            db.dataframe(
                df,
                table_name='trades_chunked',
                at='ts',
                max_rows_per_batch=2)

            # Egress: query QuestDB and materialise the result as Polars.
            with db.query(
                    "SELECT x AS trade_id, "
                    "x * 10.0 AS price, "
                    "timestamp_sequence("
                    "'2025-01-01T12:00:00.000000Z', 1000000) AS ts "
                    "FROM long_sequence(3)") as result:
                queried = result.to_polars()
            print(queried)
    except QuestDBError as e:
        sys.stderr.write(f'Got error: {e}\n')


def schema_overrides_example(host: str = 'localhost', port: int = 9000):
    """B-class wire types (IPv4 / Geohash / etc.) need an explicit hint
    because `arr.dtype` alone cannot disambiguate them from plain
    integer columns. `schema_overrides` injects the corresponding
    `questdb.*` Arrow Field metadata. Requires pyarrow.
    """
    import polars as pl

    df = pl.DataFrame({
        'addr': [0x0A000001, 0xC0A80101, 0x7F000001],
        'price': [100, 200, 300],
        'ts': [
            datetime.datetime(2025, 1, 1, 12, 0, 0),
            datetime.datetime(2025, 1, 1, 12, 0, 1),
            datetime.datetime(2025, 1, 1, 12, 0, 2),
        ],
    }, schema={'addr': pl.UInt32, 'price': pl.Int64, 'ts': pl.Datetime('us')})

    try:
        conf = f'ws::addr={host}:{port};'
        with questdb.connect(conf) as db:
            db.dataframe(
                df,
                table_name='ipv4_log',
                at='ts',
                schema_overrides={'addr': 'ipv4'})
    except QuestDBError as e:
        sys.stderr.write(f'Got error: {e}\n')


if __name__ == '__main__':
    example()
    schema_overrides_example()

```

--------------------------------

### questdb.QuestDBErrorCode attributes (S)

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Error code attributes starting with 'S' on the QuestDBErrorCode class.

```APIDOC
## Attributes: questdb.QuestDBErrorCode (S)

### Description
Error codes starting with 'S'.

### Attributes
- SchemaDrift
- ServerFlushError
- ServerInternalError
- ServerLimitExceeded
- ServerParseError
- ServerRejection
- ServerSchemaMismatch
- ServerSecurityError
- SocketError
- StoreResendRequired
```

--------------------------------

### Configuration string format

Source: https://py-questdb-client.readthedocs.io/en/latest/conf.html

Shows the general format of a configuration string: <protocol>::<key>=<value>;<key>=<value>;...;

```text
<protocol>::<key>=<value>;<key>=<value>;...;
```

--------------------------------

### Connect and use QuestDB client with context manager

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Shows how to connect to QuestDB using both a connection string and host/port parameters, then use the sender, dataframe, and query methods within a context manager. The ellipsis indicates omitted code.

```python
import questdb

with questdb.connect('ws::addr=localhost:9000;') as db:
    with db.sender() as sender:
        sender.row('trades', symbols={'sym': 'BTC-USD'},
                   columns={'price': 62000.0}, at=ts)
    db.dataframe(df, table_name='trades', at='ts')
    result = db.query('SELECT * FROM trades LIMIT 10')

with questdb.connect(host='localhost', port=9000) as db:
    ...
```

--------------------------------

### questdb.Sender.error_events_dropped()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Method on the Sender class to get the number of dropped error events.

```APIDOC
## Sender.error_events_dropped()

### Description
Method to retrieve the count of dropped error events.

### Method
`error_events_dropped()`

### Parameters
None documented.

### Returns
Not documented.
```

--------------------------------

### questdb.PooledSender.error_events_dropped()

Source: https://py-questdb-client.readthedocs.io/en/latest/genindex.html

Method on the PooledSender class to get the number of dropped error events.

```APIDOC
## PooledSender.error_events_dropped()

### Description
Method to retrieve the count of dropped error events.

### Method
`error_events_dropped()`

### Parameters
None documented.

### Returns
Not documented.
```

--------------------------------

### Buffer.row() usage examples

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Three examples of adding rows to a QuestDB ILP buffer. The first specifies all fields including symbols, columns, and a designated timestamp. The second specifies only symbols and lets the server assign the timestamp. The third uses float columns and a datetime.datetime timestamp, noting that unspecified timezones are interpreted as UTC.

```python
# All fields specified.
buffer.row(
    'table_name',
    symbols={'sym1': 'abc', 'sym2': 'def', 'sym3': None},
    columns={
        'col1': True,
        'col2': 123,
        'col3': 3.14,
        'col4': 'xyz',
        'col5': TimestampMicros(123456789),
        'col6': datetime(2019, 1, 1, 12, 0, 0),
        'col7': numpy.array([[1.0, 2.0, 3.0], [4.0, 5.0, 6.0]]),
        'col8': None},
    at=TimestampNanos(123456789))

# Only symbols specified. Designated timestamp assigned by the db.
buffer.row(
    'table_name',
    symbols={'sym1': 'abc', 'sym2': 'def'}, at=Server.Timestamp)

# Float columns and timestamp specified as `datetime.datetime`.
# Pay special attention to the timezone, which if unspecified is
# interpreted as UTC.
buffer.row(
    'sensor data',
    columns={
        'temperature': 24.5,
        'humidity': 0.5},
    at=datetime.datetime.now(tz=datetime.timezone.utc))
```

--------------------------------

### questdb.QuestDB.from_conf(conf_str, *, connection_listener=None, connection_event_inbox_capacity=0, error_handler=None, error_event_inbox_capacity=0)

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Constructs a QuestDB handle from a QWP/WebSocket configuration string. Prefer the questdb.connect() module-level factory. By default connects eagerly; with lazy_connect=true connects lazily.

```APIDOC
## from_conf(conf_str, *, connection_listener=None, connection_event_inbox_capacity=0, error_handler=None, error_event_inbox_capacity=0)

### Description
Construct a handle from a QWP/WebSocket configuration string. Prefer the `questdb.connect()` module-level factory. By default the handle connects eagerly; with `lazy_connect=true` construction opens no connection and errors surface from the first operation.

### Method
STATIC METHOD

### Parameters
- **conf_str** (str) - Required - The QWP/WebSocket configuration string.
- **connection_listener** (callable) - Optional - A callable receiving one `ConnectionEvent` per connection-state transition of the pool's ingress connections.
- **connection_event_inbox_capacity** (int) - Optional - Capacity of the bounded inbox for connection events; `0` selects the default of 64.
- **error_handler** (callable) - Optional - Error handler for connection errors.
- **error_event_inbox_capacity** (int) - Optional - Capacity of the bounded inbox for error events; `0` selects the default.

### Returns
QuestDB - A QuestDB handle.

### Notes
- Pooled row auto-flush is enabled by default at 1,000 rows, 100 milliseconds, or an estimated encoded size at 90% of the effective frame cap.
- Set `auto_flush_bytes=off` to disable only the byte trigger, or `auto_flush=off` to disable all automatic publishing.
- On a transient connection failure the frame is re-sent from the caller's DataFrame only when the failed operation is provably not delivered.
- `request_timeout` bounds each commit's no-progress ack wait; `request_timeout=0` disables that deadline.
- `connection_listener` runs on a dedicated dispatcher thread fed by a bounded inbox with a drop-oldest overflow policy.

### Example
```python
from questdb import QuestDB
handle = QuestDB.from_conf("http::addr=localhost:9000;username=admin;password=quest;")
```
```

--------------------------------

### Sender.from_env(*, ...)

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Constructs a sender from the QDB_CLIENT_CONF environment variable, which must be set to a valid configuration string. Additional arguments can specify parameters not present in the configuration string.

```APIDOC
## Sender.from_env(*, bind_interface=None, username=None, password=None, token=None, token_x=None, token_y=None, auth_timeout=None, tls_verify=None, tls_ca=None, tls_roots=None, tls_roots_password=None, max_buf_size=None, retry_timeout=None, retry_max_backoff=None, request_min_throughput=None, request_timeout=None, auto_flush=None, auto_flush_rows=None, auto_flush_bytes=None, auto_flush_interval=None, max_datagram_size=None, multicast_ttl=None, qwp_ws_progress=None, error_handler=None, connection_listener=None, connection_event_inbox_capacity=0, protocol_version=None, init_buf_size=None, max_name_len=None)

### Description
Constructs a sender from the `QDB_CLIENT_CONF` environment variable, which must be set to a valid configuration string. Additional arguments can specify parameters not present in the configuration string.

### Method
from_env (static)

### Parameters
- **bind_interface** (optional) - Additional parameter.
- **username** (optional) - Additional parameter.
- **password** (optional) - Additional parameter.
- **token** (optional) - Additional parameter.
- **token_x** (optional) - Additional parameter.
- **token_y** (optional) - Additional parameter.
- **auth_timeout** (optional) - Additional parameter.
- **tls_verify** (optional) - Additional parameter.
- **tls_ca** (optional) - Additional parameter.
- **tls_roots** (optional) - Additional parameter.
- **tls_roots_password** (optional) - Additional parameter.
- **max_buf_size** (optional) - Additional parameter.
- **retry_timeout** (optional) - Additional parameter.
- **retry_max_backoff** (optional) - Additional parameter.
- **request_min_throughput** (optional) - Additional parameter.
- **request_timeout** (optional) - Additional parameter.
- **auto_flush** (optional) - Additional parameter.
- **auto_flush_rows** (optional) - Additional parameter.
- **auto_flush_bytes** (optional) - Additional parameter.
- **auto_flush_interval** (optional) - Additional parameter.
- **max_datagram_size** (optional) - Additional parameter.
- **multicast_ttl** (optional) - Additional parameter.
- **qwp_ws_progress** (optional) - Additional parameter.
- **error_handler** (optional) - Additional parameter.
- **connection_listener** (optional) - Additional parameter.
- **connection_event_inbox_capacity** (int, optional) - Default: 0.
- **protocol_version** (optional) - Additional parameter.
- **init_buf_size** (optional) - Additional parameter.
- **max_name_len** (optional) - Additional parameter.

### Returns
- A Sender instance.
```

--------------------------------

### Set QDB_CLIENT_CONF environment variable

Source: https://py-questdb-client.readthedocs.io/en/latest/conf.html

Shows how to set the QDB_CLIENT_CONF environment variable to a configuration string, which can be used to keep sensitive information out of code.

```bash
export QDB_CLIENT_CONF="http::addr=localhost:9009;username=admin;password=quest;"
```

--------------------------------

### sender.row with ServerTimestamp

Source: https://py-questdb-client.readthedocs.io/en/latest/sender.html

Example showing how to use the row method with the ServerTimestamp value to let the server assign the designated timestamp.

```APIDOC
## sender.row with ServerTimestamp

### Description
Demonstrates using the `row` method with `at=ServerTimestamp` to instruct QuestDB to set the designated timestamp on the server side.

### Method
row

### Endpoint
N/A (SDK method)

### Parameters
- **table_name** (str) - Required - The name of the table to insert into.
- **symbols** (dict) - Required - A dictionary of symbol columns and their values.
- **columns** (dict) - Required - A dictionary of non-symbol columns and their values.
- **at** (ServerTimestamp) - Required - Set to `ServerTimestamp` to let the server assign the timestamp.

### Request Example
```python
import questdb
from questdb import ServerTimestamp

with questdb.connect('ws::addr=localhost:9000;') as db:
    with db.sender() as sender:
        sender.row(
            'trades',
            symbols={'symbol': 'ETH-USD', 'side': 'sell'},
            columns={'price': 2615.54, 'amount': 0.00044},
            at=ServerTimestamp)  # Legacy feature, not recommended.
        sender.flush(wait=True)
```

### Response
No explicit response documented.
```

--------------------------------

### questdb.connect

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Establishes a connection to a QuestDB deployment. The connection string format is 'ws::addr=host:port;' or keyword arguments can be used. Returns a QuestDB handle that can be used as a context manager.

```APIDOC
## questdb.connect

### Description
Establishes a connection to a QuestDB deployment over QWP/WebSocket. Returns a QuestDB handle that owns the connection pool.

### Method
connect

### Endpoint
questdb.connect(connection_string_or_kwargs)

### Parameters
- **connection_string** (str) - Optional - Connection string in format 'ws::addr=host:port;'
- **host** (str) - Optional - Hostname of the QuestDB server
- **port** (int) - Optional - Port of the QuestDB server

### Request Example
```python
import questdb

with questdb.connect('ws::addr=localhost:9000;') as db:
    ...

with questdb.connect(host='localhost', port=9000) as db:
    ...
```

### Response
Returns a QuestDB instance.

### Response Example
```python
db = questdb.connect('ws::addr=localhost:9000;')
```
```

--------------------------------

### QueryResult.cancel

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Cancel the query and drain to terminal. The result remains open; call close() before starting another query on the same reader.

```APIDOC
## QueryResult.cancel

### Description
Cancel the query and drain to terminal. The result remains open; call close() before starting another query on the same reader. On failure, the result is closed. Idempotent after success.

### Method
cancel

### Signature
cancel()

### Parameters
None

### Returns
None

### Behavior
- Cancels the query and drains to terminal.
- The result remains open; call close() before starting another query on the same reader.
- On failure, the result is closed.
- Idempotent after success.

### Usage Example
```python
result.cancel()
result.close()
```
```

--------------------------------

### QuestDB.dataframe

Source: https://py-questdb-client.readthedocs.io/en/latest/migration.html

Recommended entry point for DataFrame bulk loads over QWP/WebSocket. Opens a direct columnar path, commits the whole source before returning, and re-sends on transient failures.

```APIDOC
## QuestDB.dataframe

### Description
Recommended entry point for DataFrame bulk loads over QWP/WebSocket. Opens a direct columnar path, commits the whole source before returning, and re-sends on transient failures.

### Method
DataFrame bulk load (database operation)

### Endpoint
`QuestDB.dataframe(frame, table_name, at)`

### Parameters
- **frame** (pandas.DataFrame) - Required - The DataFrame to load.
- **table_name** (str) - Required - Target table name.
- **at** (str or Timestamp) - Required - Column name or timestamp for the designated timestamp.

### Request Example
```python
import pandas as pd
import questdb

frame = pd.DataFrame({
    't': [21.5, 20.9],
    'ts': pd.to_datetime(['2026-01-01T00:00:00Z', '2026-01-01T00:00:01Z'])})

with questdb.connect('ws::addr=localhost:9000;') as db:
    db.dataframe(frame, table_name='weather', at='ts')
```

### Response
Commits the whole source before returning. On transient failures, re-sends from the DataFrame; raises with `in_doubt` set when a blind re-send could duplicate rows.

```

--------------------------------

### questdb.QuestDBErrorCode.__str__()

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Returns the name of the enum member as a string. This method is inherited from the Enum class and is used to get a human-readable representation of the error code.

```APIDOC
## questdb.QuestDBErrorCode.__str__()

### Description
Returns the name of the enum member as a string.

### Method
__str__

### Signature
__str__() → str

### Returns
- **str** - The name of the enum member.

```

--------------------------------

### questdb.connect() implementation

Source: https://py-questdb-client.readthedocs.io/en/latest/_modules/questdb.html

The full implementation of the connect() function, which validates arguments, builds a configuration string, and creates a QuestDB instance. It raises TypeError for invalid argument combinations and ValueError for host/port issues.

```python
if (conf_str is None) == (host is None):
    raise TypeError(
        'connect() takes either a configuration string or a host= '
        'keyword (with optional port=, tls= and further settings), '
        'but not both.')
for key in params:
    if not key.isidentifier():
        raise TypeError(f'invalid settings keyword {key!r}')
if conf_str is not None:
    given = [name for name, value
             in (('port', port), ('tls', tls)) if value is not None]
    if given:
        raise TypeError(
            'connect() only accepts the endpoint keywords '
            f'({", ".join(given)}) together with host=, not with a '
            'configuration string; use ws::/wss:: and addr= in the '
            'string instead.')
    if params:
        # Insert right after 'ws::'/'wss::': appending at the tail
        # would mis-merge when the string ends inside an escaped
        # ';;' value.
        schema, sep, rest = conf_str.partition('::')
        conf_str = schema + sep + ''.join(
            f'{key}={_conf_value(key, value)};'
            for key, value in params.items()) + rest
else:
    if not isinstance(host, str):
        raise TypeError(
            f'"host" must be a str, not {type(host).__name__}')
    if host.startswith('['):
        if not host.endswith(']'):
            raise ValueError(
                f'"host" must not include a port ({host!r}); pass the '
                'port via port= instead.')
    elif host.count(':') >= 2:
        host = f'[{host}]'
    elif ':' in host:
        raise ValueError(
            f'"host" must not include a port ({host!r}); pass the port '
            'via port= instead.')
    settings = [('addr', f'{host}:{port if port is not None else 9000}')]
    settings.extend(params.items())
    conf_str = ('wss::' if tls else 'ws::') + ''.join(
        f'{key}={_conf_value(key, value)};' for key, value in settings)
try:
    return QuestDB.from_conf(
        conf_str,
        connection_listener=connection_listener,
        connection_event_inbox_capacity=connection_event_inbox_capacity,
        error_handler=error_handler,
        error_event_inbox_capacity=error_event_inbox_capacity)
except QuestDBError as e:
    # The native parser reports a keyword/string conflict as a
    # duplicate key at a position in the merged string the caller
    # never wrote; rephrase it like Sender.from_conf does.
    msg = str(e)
    for key in params:
        if f'duplicate key "{key}"' in msg:
            raise ValueError(
                f'"{key}" is already present in the conf_str '
                'and cannot be overridden.') from None
    raise
```

--------------------------------

### Sending DECIMAL values in Pandas dataframes with PyArrow decimal types

Source: https://py-questdb-client.readthedocs.io/en/latest/changelog.html

Example of using Sender.dataframe() with a Pandas DataFrame that uses PyArrow decimal128 type for better performance.

```python
import pandas as pd
import pyarrow as pa
from decimal import Decimal

# Create DataFrame with Arrow decimal types
df = pd.DataFrame({
    'prices': pd.array(
        [Decimal('-99999.99'), Decimal('-678.00')],
        dtype=pd.ArrowDtype(pa.decimal128(18, 2))
    )
})

with Sender.from_conf(conf) as sender:
    sender.dataframe(df, table_name='prices', at=TimestampNanos.now())
```

--------------------------------

### Write Pandas DataFrame to QuestDB with Sender.dataframe

Source: https://py-questdb-client.readthedocs.io/en/latest/api.html

Example from the questdb.Sender.dataframe documentation showing how to create a Pandas DataFrame and send it to QuestDB using qi.Sender.from_env() and sender.dataframe(df, table_name='race_metrics', at='ts').

```python
import pandas as pd
import questdb as qi

df = pd.DataFrame({
    'car': pd.Categorical(['Nic 42', 'Eddi', 'Nic 42', 'Eddi']),
    'position': [1, 2, 1, 2],
    'speed': [89.3, 98.2, 3, 4],
    'lat_gforce': [0.1, -0.2, -0.6, 0.4],
    'accelleration': [0.1, -0.2, 0.6, 4.4],
    'tyre_pressure': [2.6, 2.5, 2.6, 2.5],
    'ts': [
        pd.Timestamp('2022-08-09 13:56:00'),
        pd.Timestamp('2022-08-09 13:56:01'),
        pd.Timestamp('2022-08-09 13:56:02'),
        pd.Timestamp('2022-08-09 13:56:03')]})

with qi.Sender.from_env() as sender:
    sender.dataframe(df, table_name='race_metrics', at='ts')
```
Tokens:
Raw