diff --git a/CHANGELOG.md b/CHANGELOG.md index c5d29042..1eaaf3bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,8 @@ ## 1.22.0 [unreleased] +### Documentation +1. [#331](https://github.com/influxdata/influxdb-client-python/pull/331): Add [Migration Guide](MIGRATION_GUIDE.rst) + ## 1.21.0 [2021-09-17] ### Features diff --git a/MIGRATION_GUIDE.rst b/MIGRATION_GUIDE.rst new file mode 100644 index 00000000..5908e777 --- /dev/null +++ b/MIGRATION_GUIDE.rst @@ -0,0 +1,337 @@ +Migration Guide +=============== + +This guide is meant to help you migrate your Python code from +`influxdb-python `__ to +``influxdb-client-python`` by providing code examples that cover common +usages. + +If there is something missing, please feel free to create a `new +request `__ +for a guide enhancement. + +Before You Start +---------------- + +Please take a moment to review the following client docs: + +- `User Guide `__, `README.rst `__ +- `Examples `__ +- `API Reference `__ +- `CHANGELOG.md `__ + +Content +------- + +- `Initializing Client <#initializing-client>`__ +- `Creating Database/Bucket <#creating-databasebucket>`__ +- `Dropping Database/Bucket <#dropping-databasebucket>`__ +- Writes + - `LineProtocol <#writing-lineprotocol>`__ + - `Dictionary-style object <#writing-dictionary-style-object>`__ + - `Structured data <#writing-structured-data>`__ + - `Pandas DataFrame <#writing-pandas-dataframe>`__ +- `Querying <#querying>`__ + +Initializing Client +------------------- + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + pass + +Creating Database/Bucket +------------------------ + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + dbname = 'example' + client.create_database(dbname) + client.create_retention_policy('awesome_policy', '60m', 3, database=dbname, default=True) + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient, BucketRetentionRules + + org = 'my-org' + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org=org) as client: + buckets_api = client.buckets_api() + + # Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python" + retention_rules = BucketRetentionRules(type="expire", every_seconds=3600) + created_bucket = buckets_api.create_bucket(bucket_name="bucket-by-python", + retention_rules=retention_rules, + org=org) + +Dropping Database/Bucket +------------------------ + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + dbname = 'example' + client.drop_database(dbname) + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + buckets_api = client.buckets_api() + + bucket = buckets_api.find_bucket_by_name("my-bucket") + buckets_api.delete_bucket(bucket) + +Writing LineProtocol +-------------------- + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + client.write('h2o_feet,location=coyote_creek water_level=1.0 1', protocol='line') + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient + from influxdb_client.client.write_api import SYNCHRONOUS + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + write_api = client.write_api(write_options=SYNCHRONOUS) + + write_api.write(bucket='my-bucket', record='h2o_feet,location=coyote_creek water_level=1.0 1') + +Writing Dictionary-style object +------------------------------- + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + record = [ + { + "measurement": "cpu_load_short", + "tags": { + "host": "server01", + "region": "us-west" + }, + "time": "2009-11-10T23:00:00Z", + "fields": { + "Float_value": 0.64, + "Int_value": 3, + "String_value": "Text", + "Bool_value": True + } + } + ] + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + client.write_points(record) + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient + from influxdb_client.client.write_api import SYNCHRONOUS + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + write_api = client.write_api(write_options=SYNCHRONOUS) + + record = [ + { + "measurement": "cpu_load_short", + "tags": { + "host": "server01", + "region": "us-west" + }, + "time": "2009-11-10T23:00:00Z", + "fields": { + "Float_value": 0.64, + "Int_value": 3, + "String_value": "Text", + "Bool_value": True + } + } + ] + + write_api.write(bucket='my-bucket', record=record) + +Writing Structured Data +----------------------- + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + from influxdb import SeriesHelper + + my_client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + + class MySeriesHelper(SeriesHelper): + class Meta: + client = my_client + series_name = 'events.stats.{server_name}' + fields = ['some_stat', 'other_stat'] + tags = ['server_name'] + bulk_size = 5 + autocommit = True + + + MySeriesHelper(server_name='us.east-1', some_stat=159, other_stat=10) + MySeriesHelper(server_name='us.east-1', some_stat=158, other_stat=20) + + MySeriesHelper.commit() + + +The ``influxdb-client-python`` doesn't have an equivalent implementation for ``MySeriesHelper``, but there is an option +to use Python `Data Classes `__ way: + +**influxdb-client-python** + +.. code:: python + + from dataclasses import dataclass + + from influxdb_client import InfluxDBClient + from influxdb_client.client.write_api import SYNCHRONOUS + + + @dataclass + class Car: + """ + DataClass structure - Car + """ + engine: str + type: str + speed: float + + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + write_api = client.write_api(write_options=SYNCHRONOUS) + + car = Car('12V-BT', 'sport-cars', 125.25) + + write_api.write(bucket="my-bucket", + record=car, + record_measurement_name="performance", + record_tag_keys=["engine", "type"], + record_field_keys=["speed"]) + +Writing Pandas DataFrame +------------------------ + +**influxdb-python** + +.. code:: python + + import pandas as pd + + from influxdb import InfluxDBClient + + df = pd.DataFrame(data=list(range(30)), + index=pd.date_range(start='2014-11-16', periods=30, freq='H'), + columns=['0']) + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + client.write_points(df, 'demo', protocol='line') + +**influxdb-client-python** + +.. code:: python + + import pandas as pd + + from influxdb_client import InfluxDBClient + from influxdb_client.client.write_api import SYNCHRONOUS + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + write_api = client.write_api(write_options=SYNCHRONOUS) + + df = pd.DataFrame(data=list(range(30)), + index=pd.date_range(start='2014-11-16', periods=30, freq='H'), + columns=['0']) + + write_api.write(bucket='my-bucket', record=df, data_frame_measurement_name='demo') + +Querying +-------- + +**influxdb-python** + +.. code:: python + + from influxdb import InfluxDBClient + + client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') + + points = client.query('SELECT * from cpu').get_points() + for point in points: + print(point) + +**influxdb-client-python** + +.. code:: python + + from influxdb_client import InfluxDBClient + + with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org', debug=True) as client: + query = '''from(bucket: "my-bucket") + |> range(start: -10000d) + |> filter(fn: (r) => r["_measurement"] == "cpu") + |> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value") + ''' + + tables = client.query_api().query(query) + for record in [record for table in tables for record in table.records]: + print(record.values) + +If you would like to omit boilerplate columns such as ``_result``, ``_table``, ``_start``, ... you can filter the record values by +following expression: + +.. code:: python + + print({k: v for k, v in record.values.items() if k not in ['result', 'table', '_start', '_stop', '_measurement']}) + +For more info see `Flux Response Format `__. diff --git a/docs/index.rst b/docs/index.rst index b42027d0..b7504766 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,6 +8,7 @@ InfluxDB 2.0 python client usage api + migration .. include:: ../README.rst :start-after: marker-index-start diff --git a/docs/migration.rst b/docs/migration.rst new file mode 100644 index 00000000..98fc6478 --- /dev/null +++ b/docs/migration.rst @@ -0,0 +1 @@ +.. include:: ../MIGRATION_GUIDE.rst \ No newline at end of file