Metadata-Version: 2.4
Name: questdb
Version: 5.0.0
Summary: QuestDB client library for Python
Author-email: Vlad Ilyushchenko <vlad@questdb.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://questdb.com/
Project-URL: Changelog, https://py-questdb-client.readthedocs.io/en/latest/changelog.html
Project-URL: Documentation, https://py-questdb-client.readthedocs.io/en/latest/index.html
Project-URL: Source, https://github.com/questdb/py-questdb-client/
Project-URL: Tracker, https://github.com/questdb/py-questdb-client/issues
Project-URL: Community, http://community.questdb.com
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Plugins
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Cython
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Networking
Classifier: Topic :: Database :: Front-Ends
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: numpy>=1.21.0
Provides-Extra: publish
Requires-Dist: twine; extra == "publish"
Requires-Dist: wheel; extra == "publish"
Provides-Extra: ci
Requires-Dist: cibuildwheel; extra == "ci"
Provides-Extra: dataframe
Requires-Dist: pandas>=1.3.5; extra == "dataframe"
Requires-Dist: pyarrow>=10.0.1; extra == "dataframe"
Dynamic: license-file
Dynamic: platform
Dynamic: requires-python

=================================
QuestDB Client Library for Python
=================================

This is the official Python client library for `QuestDB <https://questdb.com>`_.

This client library implements the QuestDB Wire Protocol (QWP) over WebSocket
for pooled ingestion and queries — the deployment-level ``questdb.connect()``
API. A connection-level ``Sender`` (one sender = one connection) covers the
legacy ILP transports — QuestDB's variant of the
`InfluxDB Line Protocol <https://questdb.com/docs/reference/api/ilp/overview/>`_
over HTTP and TCP, including HTTP transactions — plus QWP over UDP.

This implementation supports `authentication
<https://py-questdb-client.readthedocs.io/en/latest/conf.html#authentication>`_
and full-connection encryption with
`TLS <https://py-questdb-client.readthedocs.io/en/latest/conf.html#tls>`_.

Install
=======

The latest version of the library is 5.0.0 (`changelog <https://py-questdb-client.readthedocs.io/en/latest/changelog.html>`_).

::

    python3 -m pip install -U questdb[dataframe]

Quickstart
==========

Start by `setting up QuestDB <https://questdb.com/docs/quick-start/>`_ .
Once set up, you can use this library to insert data.

The most common way to insert data is from a Pandas dataframe.

.. code-block:: python

    import numpy as np
    import pandas as pd
    import questdb

    df = pd.DataFrame({
        'symbol': pd.Categorical(['ETH-USD', 'BTC-USD']),
        'side': pd.Categorical(['sell', 'sell']),
        'price': [2615.54, 39269.98],
        'amount': [0.00044, 0.001],

        # NumPy float64 arrays require QuestDB server >= 9.0.0.
        'ord_book_bids': [
            np.array([2615.54, 2618.63]),
            np.array([39269.98, 39270.00])
        ],

        'timestamp': pd.to_datetime(['2021-01-01', '2021-01-02'])})

    conf = 'ws::addr=localhost:9000;'
    with questdb.connect(conf) as db:
        db.dataframe(df, table_name='trades', at='timestamp')

You can also send individual rows. This only requires a more minimal installation::

    python3 -m pip install -U questdb

.. code-block:: python

    import numpy as np
    import questdb
    from questdb import TimestampNanos

    conf = 'ws::addr=localhost:9000;'
    with questdb.connect(conf) as db:
        with db.sender() as sender:
            sender.row(
                'trades',
                symbols={'symbol': 'ETH-USD', 'side': 'sell'},
                columns={
                    'price': 2615.54,
                    'amount': 0.00044,

                    # NumPy float64 arrays require QuestDB server >= 9.0.0.
                    'ord_book_bids': np.array([2615.54, 2618.63]),
                },
                at=TimestampNanos.now())
            sender.flush(wait=True)


``questdb.connect()`` addresses a whole deployment through connection pools.
For `connection-level needs <https://py-questdb-client.readthedocs.io/en/latest/sender.html#two-api-layers>`_
— ILP/HTTP transactions, QWP/UDP datagrams, ILP/TCP — use the standalone
``Sender``, where one sender drives one connection. Set the
`configuration string <https://py-questdb-client.readthedocs.io/en/latest/conf.html>`_
to the transport you need:

.. code-block:: python

    from questdb import Sender

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

See the `5.0 migration guide
<https://py-questdb-client.readthedocs.io/en/latest/migration.html>`_ when
moving existing code to 5.0: ``questdb.connect()`` is the new
QWP/WebSocket entry point, DataFrame bulk loads over QWP/WebSocket go through
``QuestDB.dataframe()``, and the 4.x ``questdb.ingress`` import location is
now a deprecated compatibility shim.


You can continue by reading the
`Sending Data Over ILP <https://py-questdb-client.readthedocs.io/en/latest/sender.html>`_
guide.

Links
=====

* `Core database documentation <https://questdb.com/docs/>`_

* `Python library documentation <https://py-questdb-client.readthedocs.io/>`_

* `GitHub repository <https://github.com/questdb/py-questdb-client>`_

* `Package on PyPI <https://pypi.org/project/questdb/>`_

Community
=========

Stop by our `Community Forum <https://community.questdb.com>`_ to 
chat with the QuestDB team.

You can also `sign up to our mailing list <https://questdb.com/contributors/>`_
to get notified of new releases.


License
=======

The code is released under the `Apache License 2.0
<https://github.com/questdb/py-questdb-client/blob/main/LICENSE.txt>`_. 
