driver/docs/misc.rst

Miscellaneous
=============

Client configuring from URL
---------------------------

*New in version 0.1.1.*

Client can be configured from the given URL:

    .. code-block:: python

        >>> from datastore_driver import Client
        >>> client = Client.from_url(
        ...     'datastore://login:password@host:port/database'
        ... )

Port 9000 is default for schema ``datastore``, port 9440 is default for schema ``datastores``.

Connection to default database:

    .. code-block:: python

        >>> client = Client.from_url('datastore://localhost')


Querystring arguments will be passed along to the :meth:`~datastore_driver.connection.Connection` class’s initializer:

    .. code-block:: python

        >>> client = Client.from_url(
        ...     'datastore://localhost/database?send_logs_level=trace&'
        ...     'client_name=myclient&'
        ...     'compression=lz4'
        ... )

If parameter doesn't match Connection's init signature will be treated as settings parameter.

.. _insert-from-csv-file:

Inserting data from CSV file
----------------------------

Let's assume you have following data in CSV file.

    .. code-block:: shell

        $ cat /tmp/data.csv
        time,order,qty
        2019-08-01 15:23:14,New order1,5
        2019-08-05 09:14:45,New order2,3
        2019-08-13 12:20:32,New order3,7

Data can be inserted into Datastore in the following way:


    .. code-block:: python

        >>> from csv import DictReader
        >>> from datetime import datetime
        >>>
        >>> from datastore_driver import Client
        >>>
        >>>
        >>> def iter_csv(filename):
        ...     converters = {
        ...         'qty': int,
        ...         'time': lambda x: datetime.strptime(x, '%Y-%m-%d %H:%M:%S')
        ...     }
        ...
        ...     with open(filename, 'r') as f:
        ...         reader = DictReader(f)
        ...         for line in reader:
        ...             yield {k: (converters[k](v) if k in converters else v) for k, v in line.items()}
        ...
        >>> client = Client('localhost')
        >>>
        >>> client.execute(
        ...     'CREATE TABLE IF NOT EXISTS data_csv '
        ...     '('
        ...         'time DateTime, '
        ...         'order String, '
        ...         'qty Int32'
        ...     ') Engine = Memory'
        ... )
        >>> []
        >>> client.execute('INSERT INTO data_csv VALUES', iter_csv('/tmp/data.csv'))
        3



Table can be populated with json file in the similar way.


Adding missed settings
----------------------

It's hard to keep package settings in consistent state with Datastore
server's. Some settings can be missed if your server is old. But, if setting
is *supported by your server* and missed in the package it can be added by
simple monkey pathing. Just look into Datastore server source and pick
corresponding setting type from package or write your own type.

    .. code-block:: python

        >>> from datastore_driver.settings.available import settings as available_settings, SettingBool
        >>> from datastore_driver import Client
        >>>
        >>> available_settings['allow_suspicious_low_cardinality_types'] = SettingBool
        >>>
        >>> client = Client('localhost', settings={'allow_suspicious_low_cardinality_types': True})
        >>> client.execute('CREATE TABLE test (x LowCardinality(Int32)) Engine = Null')
        []


*New in version 0.1.5.*

Modern Datastore servers (20.*+) use text serialization for settings instead of
binary serialization. You don't have to add missed settings manually into
available. Just specify new settings and it will work.

    .. code-block:: python

        >>> client = Client('localhost', settings={'brand_new_setting': 42})
        >>> client.execute('SELECT 1')


Inserting NULL into NOT NULL columns
------------------------------------

*New in version 0.2.4.*

Client option ``input_format_null_as_default`` does the same thing as in
``datastore-client``. But in this package it's disabled by default. You should
enable it if you want cast ``None`` value into default value for current type:

    .. code-block:: python

        >>> settings = {'input_format_null_as_default': True}
        >>> client = Client('localhost', settings=settings)


Client revision downgrading
---------------------------

*New in version 0.2.6.*

For various purposes client can be downgraded with ``client_revision``
parameter.

    .. code-block:: python

        >>> from datastore_driver import Client, defines
        >>>
        >>> client = Client('localhost', client_revision=defines.DBMS_MIN_PROTOCOL_VERSION_WITH_INITIAL_QUERY_START_TIME)
        >>> client.execute('SELECT version()')