From 3bdbfeae18a0c23e7342135c63e35610d5cd8dd8 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 13:39:53 +0200 Subject: [PATCH 01/17] docs: add initial version of Migration Guide --- MIGRATION_GUIDE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 MIGRATION_GUIDE.md diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md new file mode 100644 index 00000000..58a16052 --- /dev/null +++ b/MIGRATION_GUIDE.md @@ -0,0 +1,17 @@ +# 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](https://github.com/influxdata/influxdb-client-python/issues/new?assignees=&labels=documentation&title=docs(migration%20guide):%20&template=feature_request.md) for a guide enhancement. + +## Before You Start + +Please take a moment to review the following client docs: + +- [User Guide](https://influxdb-client.readthedocs.io/en/stable/usage.html), [README](README.rst) +- [Examples](examples/README.md#examples) +- [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) +- [CHANGELOG](CHANGELOG.md) + + + + From d7dedead421f1650da57d9ce231e28ae65327dac Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 13:41:26 +0200 Subject: [PATCH 02/17] docs: typos --- MIGRATION_GUIDE.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 58a16052..a0dfafba 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -1,16 +1,17 @@ # 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. +This guide is meant to help you migrate your Python code from [influxdb-python](https://github.com/influxdata/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](https://github.com/influxdata/influxdb-client-python/issues/new?assignees=&labels=documentation&title=docs(migration%20guide):%20&template=feature_request.md) for a guide enhancement. ## Before You Start Please take a moment to review the following client docs: -- [User Guide](https://influxdb-client.readthedocs.io/en/stable/usage.html), [README](README.rst) +- [User Guide](https://influxdb-client.readthedocs.io/en/stable/usage.html), [README.rst](README.rst) - [Examples](examples/README.md#examples) - [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) -- [CHANGELOG](CHANGELOG.md) +- [CHANGELOG.md](CHANGELOG.md) From 3e7eb963a6cce46ce667ba67786e07b821e193c3 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 13:46:45 +0200 Subject: [PATCH 03/17] docs: update CHANGELOG.md --- CHANGELOG.md | 3 +++ MIGRATION_GUIDE.md | 4 ---- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c5d29042..eced6717 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.md) + ## 1.21.0 [2021-09-17] ### Features diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index a0dfafba..7def5591 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -12,7 +12,3 @@ Please take a moment to review the following client docs: - [Examples](examples/README.md#examples) - [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) - [CHANGELOG.md](CHANGELOG.md) - - - - From 9d6d312add1d18e4a008a27b56f620db0905f1e6 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 14:15:47 +0200 Subject: [PATCH 04/17] docs: add how to initialize client --- MIGRATION_GUIDE.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 7def5591..9d386343 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -12,3 +12,33 @@ Please take a moment to review the following client docs: - [Examples](examples/README.md#examples) - [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) - [CHANGELOG.md](CHANGELOG.md) + +## Initializing Client + +##### `influxdb-python` +```python +from influxdb import InfluxDBClient + +client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') +``` + +##### `influxdb-client-python` + +```python +from influxdb_client import InfluxDBClient + +client = InfluxDBClient(url="http://localhost:8086", token="my-token", org="my-org") +``` + +## Creating Database/Bucket + +## Dropping Database/Bucket + +## Writing LineProtocol + +## Writing Point Object + +## Writing Structured Data + +## Querying + From 7fd398c93a35faf760da3755ce9acd63a2888b7b Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 14:18:21 +0200 Subject: [PATCH 05/17] docs: styles --- MIGRATION_GUIDE.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 9d386343..49f2b258 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -15,14 +15,15 @@ Please take a moment to review the following client docs: ## Initializing Client -##### `influxdb-python` +**influxdb-python** + ```python from influxdb import InfluxDBClient client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') ``` -##### `influxdb-client-python` +**influxdb-client-python** ```python from influxdb_client import InfluxDBClient From b18d8595df6f00d69d7bd488992706a56f2b8218 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Wed, 22 Sep 2021 14:19:23 +0200 Subject: [PATCH 06/17] docs: use same styles --- MIGRATION_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 49f2b258..060f4216 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -28,7 +28,7 @@ client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password=' ```python from influxdb_client import InfluxDBClient -client = InfluxDBClient(url="http://localhost:8086", token="my-token", org="my-org") +client = InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') ``` ## Creating Database/Bucket From e63a221ae11b0a2060e5cf214cf0410854b67a7e Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:05:50 +0200 Subject: [PATCH 07/17] docs: how to create db/bucket --- MIGRATION_GUIDE.md | 82 +++++++++++++++++++++++++++++++++- examples/buckets_management.py | 35 ++------------- 2 files changed, 84 insertions(+), 33 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 060f4216..abd6b9a4 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -28,18 +28,98 @@ client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password=' ```python from influxdb_client import InfluxDBClient -client = InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') +with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: + pass ``` ## Creating Database/Bucket +**influxdb-python** + +```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** + +```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) + print(created_bucket) +``` + ## Dropping Database/Bucket +**influxdb-python** + +```python +``` + +**influxdb-client-python** + +```python +``` + ## Writing LineProtocol +**influxdb-python** + +```python +``` + +**influxdb-client-python** + +```python +``` + ## Writing Point Object +**influxdb-python** + +```python +``` + +**influxdb-client-python** + +```python +``` + ## Writing Structured Data +**influxdb-python** + +```python +``` + +**influxdb-client-python** + +```python +``` + ## Querying +**influxdb-python** + +```python +``` + +**influxdb-client-python** + +```python +``` diff --git a/examples/buckets_management.py b/examples/buckets_management.py index c376f77c..8b963cee 100644 --- a/examples/buckets_management.py +++ b/examples/buckets_management.py @@ -1,42 +1,13 @@ -""" -How to How to create, list and delete Buckets. -""" - from influxdb_client import InfluxDBClient, BucketRetentionRules -""" -Define credentials -""" -url = "http://localhost:8086" -token = "my-token" -org = "my-org" +org = 'my-org' -with InfluxDBClient(url=url, token=token) as client: +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" - """ - print(f"------- Create -------\n") + # 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) print(created_bucket) - - """ - List all Buckets - """ - print(f"\n------- List -------\n") - buckets = buckets_api.find_buckets().buckets - print("\n".join([f" ---\n ID: {bucket.id}\n Name: {bucket.name}\n Retention: {bucket.retention_rules}" - for bucket in buckets])) - print("---") - - """ - Delete previously created bucket - """ - print(f"------- Delete -------\n") - buckets_api.delete_bucket(created_bucket) - print(f" successfully deleted bucket: {created_bucket.name}") - From a547cecf950431d64b5aa28162b2cddc2cfef95b Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:16:04 +0200 Subject: [PATCH 08/17] docs: how to drop db/bucket --- MIGRATION_GUIDE.md | 22 +++++++++++++++++++-- examples/buckets_management.py | 35 +++++++++++++++++++++++++++++++--- 2 files changed, 52 insertions(+), 5 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index abd6b9a4..6ed90f48 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -13,6 +13,12 @@ Please take a moment to review the following client docs: - [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) - [CHANGELOG.md](CHANGELOG.md) +## Content + +- [Initializing Client](#initializing-client) +- [Creating Database/Bucket](#creating-databasebucket) +- [Dropping Database/Bucket](#dropping-databasebucket) + ## Initializing Client **influxdb-python** @@ -40,8 +46,8 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') from influxdb import InfluxDBClient client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') -dbname = 'example' +dbname = 'example' client.create_database(dbname) client.create_retention_policy('awesome_policy', '60m', 3, database=dbname, default=True) ``` @@ -61,7 +67,6 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org=org) as c created_bucket = buckets_api.create_bucket(bucket_name="bucket-by-python", retention_rules=retention_rules, org=org) - print(created_bucket) ``` ## Dropping Database/Bucket @@ -69,11 +74,24 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org=org) as c **influxdb-python** ```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** ```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 diff --git a/examples/buckets_management.py b/examples/buckets_management.py index 8b963cee..c376f77c 100644 --- a/examples/buckets_management.py +++ b/examples/buckets_management.py @@ -1,13 +1,42 @@ +""" +How to How to create, list and delete Buckets. +""" + from influxdb_client import InfluxDBClient, BucketRetentionRules -org = 'my-org' +""" +Define credentials +""" +url = "http://localhost:8086" +token = "my-token" +org = "my-org" -with InfluxDBClient(url='http://localhost:8086', token='my-token', org=org) as client: +with InfluxDBClient(url=url, token=token) as client: buckets_api = client.buckets_api() - # Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python" + """ + Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python" + """ + print(f"------- Create -------\n") 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) print(created_bucket) + + """ + List all Buckets + """ + print(f"\n------- List -------\n") + buckets = buckets_api.find_buckets().buckets + print("\n".join([f" ---\n ID: {bucket.id}\n Name: {bucket.name}\n Retention: {bucket.retention_rules}" + for bucket in buckets])) + print("---") + + """ + Delete previously created bucket + """ + print(f"------- Delete -------\n") + buckets_api.delete_bucket(created_bucket) + print(f" successfully deleted bucket: {created_bucket.name}") + From ac284d20e75608e8170f8ae96f148c0532b15f72 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:28:21 +0200 Subject: [PATCH 09/17] docs: how to write LineProtocol --- MIGRATION_GUIDE.md | 12 +++++++++ examples/buckets_management.py | 45 ++++------------------------------ 2 files changed, 17 insertions(+), 40 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 6ed90f48..8b8b6c60 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -99,11 +99,23 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') **influxdb-python** ```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** ```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 Point Object diff --git a/examples/buckets_management.py b/examples/buckets_management.py index c376f77c..b2d75894 100644 --- a/examples/buckets_management.py +++ b/examples/buckets_management.py @@ -1,42 +1,7 @@ -""" -How to How to create, list and delete Buckets. -""" +from influxdb_client import InfluxDBClient +from influxdb_client.client.write_api import SYNCHRONOUS -from influxdb_client import InfluxDBClient, BucketRetentionRules - -""" -Define credentials -""" -url = "http://localhost:8086" -token = "my-token" -org = "my-org" - -with InfluxDBClient(url=url, token=token) as client: - buckets_api = client.buckets_api() - - """ - Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python" - """ - print(f"------- Create -------\n") - 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) - print(created_bucket) - - """ - List all Buckets - """ - print(f"\n------- List -------\n") - buckets = buckets_api.find_buckets().buckets - print("\n".join([f" ---\n ID: {bucket.id}\n Name: {bucket.name}\n Retention: {bucket.retention_rules}" - for bucket in buckets])) - print("---") - - """ - Delete previously created bucket - """ - print(f"------- Delete -------\n") - buckets_api.delete_bucket(created_bucket) - print(f" successfully deleted bucket: {created_bucket.name}") +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') From 6fed0893ad38b10c77f9854ba23a789d43587683 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:33:15 +0200 Subject: [PATCH 10/17] docs: how to write Dictionary-style object --- examples/buckets_management.py | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/examples/buckets_management.py b/examples/buckets_management.py index b2d75894..b85e703e 100644 --- a/examples/buckets_management.py +++ b/examples/buckets_management.py @@ -4,4 +4,21 @@ 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') + 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) From 5aa9ac2a5aab80a5aed20ea768d2d660b15b1419 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:35:14 +0200 Subject: [PATCH 11/17] docs: how to write Dictionary-style object --- MIGRATION_GUIDE.md | 51 +++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 8b8b6c60..78ae62ce 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -18,6 +18,8 @@ Please take a moment to review the following client docs: - [Initializing Client](#initializing-client) - [Creating Database/Bucket](#creating-databasebucket) - [Dropping Database/Bucket](#dropping-databasebucket) +- [Writing LineProtocol](#writing-lineprotocol) +- [Writing Dictionary-style object](#writing-dictionary-style-object) ## Initializing Client @@ -118,16 +120,63 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') write_api.write(bucket='my-bucket', record='h2o_feet,location=coyote_creek water_level=1.0 1') ``` -## Writing Point Object +## Writing Dictionary-style object **influxdb-python** ```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** ```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 From 0bfccb64879ce6b70060fb55db87411a4bbd3a04 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:41:05 +0200 Subject: [PATCH 12/17] docs: how to write Pandas DataFrame --- MIGRATION_GUIDE.md | 43 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 41 insertions(+), 2 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 78ae62ce..63b6d0ea 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -18,8 +18,10 @@ Please take a moment to review the following client docs: - [Initializing Client](#initializing-client) - [Creating Database/Bucket](#creating-databasebucket) - [Dropping Database/Bucket](#dropping-databasebucket) -- [Writing LineProtocol](#writing-lineprotocol) -- [Writing Dictionary-style object](#writing-dictionary-style-object) +- Writes + - [LineProtocol](#writing-lineprotocol) + - [Dictionary-style object](#writing-dictionary-style-object) + - [Pandas DataFrame](#writing-pandas-dataframe) ## Initializing Client @@ -191,6 +193,43 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') ```python ``` +## Writing Pandas DataFrame + +**influxdb-python** + +```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** + +```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** From 1ec4f03dd33f091a458e6d8f7ff9855977546ea6 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:49:09 +0200 Subject: [PATCH 13/17] docs: how to write Structured data --- MIGRATION_GUIDE.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 63b6d0ea..6e3ab6de 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -21,6 +21,7 @@ Please take a moment to review the following client docs: - Writes - [LineProtocol](#writing-lineprotocol) - [Dictionary-style object](#writing-dictionary-style-object) + - [Strutured data](#writing-structured-data) - [Pandas DataFrame](#writing-pandas-dataframe) ## Initializing Client @@ -186,11 +187,75 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') **influxdb-python** ```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): + """Instantiate SeriesHelper to write points to the backend.""" + + class Meta: + """Meta class stores time series helper configuration.""" + + # The client should be an instance of InfluxDBClient. + client = my_client + + # The series name must be a string. Add dependent fields/tags + # in curly brackets. + series_name = 'events.stats.{server_name}' + + # Defines all the fields in this time series. + fields = ['some_stat', 'other_stat'] + + # Defines all the tags for the series. + tags = ['server_name'] + + # Defines the number of data points to store prior to writing + # on the wire. + bulk_size = 5 + + # autocommit must be set to True when using bulk_size + 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() ``` +There `influxdb-client-python` doesn't have an equivalent implementation for `MySeriesHelper`, but there is an option +to use Python [Data Classes](https://docs.python.org/3/library/dataclasses.html) way. + **influxdb-client-python** ```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 From bc75844245d601c47b029349c980d8a77ccc91a5 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:49:22 +0200 Subject: [PATCH 14/17] docs: how to write Structured data --- MIGRATION_GUIDE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 6e3ab6de..805d7814 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -21,7 +21,7 @@ Please take a moment to review the following client docs: - Writes - [LineProtocol](#writing-lineprotocol) - [Dictionary-style object](#writing-dictionary-style-object) - - [Strutured data](#writing-structured-data) + - [Structured data](#writing-structured-data) - [Pandas DataFrame](#writing-pandas-dataframe) ## Initializing Client From d1909c5f8badcfc81a1e4a5ced7cc9882a840261 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 10:51:03 +0200 Subject: [PATCH 15/17] docs: how to write Structured data --- MIGRATION_GUIDE.md | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 805d7814..9d663911 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -192,40 +192,25 @@ from influxdb import SeriesHelper my_client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') -class MySeriesHelper(SeriesHelper): - """Instantiate SeriesHelper to write points to the backend.""" +class MySeriesHelper(SeriesHelper): class Meta: - """Meta class stores time series helper configuration.""" - - # The client should be an instance of InfluxDBClient. client = my_client - - # The series name must be a string. Add dependent fields/tags - # in curly brackets. series_name = 'events.stats.{server_name}' - - # Defines all the fields in this time series. fields = ['some_stat', 'other_stat'] - - # Defines all the tags for the series. tags = ['server_name'] - - # Defines the number of data points to store prior to writing - # on the wire. bulk_size = 5 - - # autocommit must be set to True when using bulk_size 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() ``` -There `influxdb-client-python` doesn't have an equivalent implementation for `MySeriesHelper`, but there is an option -to use Python [Data Classes](https://docs.python.org/3/library/dataclasses.html) way. +The `influxdb-client-python` doesn't have an equivalent implementation for `MySeriesHelper`, but there is an option +to use Python [Data Classes](https://docs.python.org/3/library/dataclasses.html) way: **influxdb-client-python** From 73689e1de212483b94be3aaaad1acfbf9e3840a1 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 11:50:31 +0200 Subject: [PATCH 16/17] docs: Querying --- MIGRATION_GUIDE.md | 28 ++++++++++++++++ examples/buckets_management.py | 60 ++++++++++++++++++++++------------ 2 files changed, 67 insertions(+), 21 deletions(-) diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md index 9d663911..f2908153 100644 --- a/MIGRATION_GUIDE.md +++ b/MIGRATION_GUIDE.md @@ -23,6 +23,7 @@ Please take a moment to review the following client docs: - [Dictionary-style object](#writing-dictionary-style-object) - [Structured data](#writing-structured-data) - [Pandas DataFrame](#writing-pandas-dataframe) +- [Querying](#querying) ## Initializing Client @@ -285,9 +286,36 @@ with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') **influxdb-python** ```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** ```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: + +```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](https://github.com/influxdata/flux/blob/master/docs/SPEC.md#response-format). \ No newline at end of file diff --git a/examples/buckets_management.py b/examples/buckets_management.py index b85e703e..c376f77c 100644 --- a/examples/buckets_management.py +++ b/examples/buckets_management.py @@ -1,24 +1,42 @@ -from influxdb_client import InfluxDBClient -from influxdb_client.client.write_api import SYNCHRONOUS +""" +How to How to create, list and delete Buckets. +""" -with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client: - write_api = client.write_api(write_options=SYNCHRONOUS) +from influxdb_client import InfluxDBClient, BucketRetentionRules - 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 - } - } - ] +""" +Define credentials +""" +url = "http://localhost:8086" +token = "my-token" +org = "my-org" + +with InfluxDBClient(url=url, token=token) as client: + buckets_api = client.buckets_api() + + """ + Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python" + """ + print(f"------- Create -------\n") + 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) + print(created_bucket) + + """ + List all Buckets + """ + print(f"\n------- List -------\n") + buckets = buckets_api.find_buckets().buckets + print("\n".join([f" ---\n ID: {bucket.id}\n Name: {bucket.name}\n Retention: {bucket.retention_rules}" + for bucket in buckets])) + print("---") + + """ + Delete previously created bucket + """ + print(f"------- Delete -------\n") + buckets_api.delete_bucket(created_bucket) + print(f" successfully deleted bucket: {created_bucket.name}") - write_api.write(bucket='my-bucket', record=record) From 5293880bb7c955e83bf7d48c5d31cc562c2f87e6 Mon Sep 17 00:00:00 2001 From: Jakub Bednar Date: Mon, 4 Oct 2021 12:12:01 +0200 Subject: [PATCH 17/17] docs: add Migration Guide to readthedocs --- CHANGELOG.md | 2 +- MIGRATION_GUIDE.md | 321 ----------------------------------------- MIGRATION_GUIDE.rst | 337 ++++++++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + docs/migration.rst | 1 + 5 files changed, 340 insertions(+), 322 deletions(-) delete mode 100644 MIGRATION_GUIDE.md create mode 100644 MIGRATION_GUIDE.rst create mode 100644 docs/migration.rst diff --git a/CHANGELOG.md b/CHANGELOG.md index eced6717..1eaaf3bc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,7 +1,7 @@ ## 1.22.0 [unreleased] ### Documentation -1. [#331](https://github.com/influxdata/influxdb-client-python/pull/331): Add [Migration Guide](MIGRATION_GUIDE.md) +1. [#331](https://github.com/influxdata/influxdb-client-python/pull/331): Add [Migration Guide](MIGRATION_GUIDE.rst) ## 1.21.0 [2021-09-17] diff --git a/MIGRATION_GUIDE.md b/MIGRATION_GUIDE.md deleted file mode 100644 index f2908153..00000000 --- a/MIGRATION_GUIDE.md +++ /dev/null @@ -1,321 +0,0 @@ -# Migration Guide - -This guide is meant to help you migrate your Python code from [influxdb-python](https://github.com/influxdata/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](https://github.com/influxdata/influxdb-client-python/issues/new?assignees=&labels=documentation&title=docs(migration%20guide):%20&template=feature_request.md) for a guide enhancement. - -## Before You Start - -Please take a moment to review the following client docs: - -- [User Guide](https://influxdb-client.readthedocs.io/en/stable/usage.html), [README.rst](README.rst) -- [Examples](examples/README.md#examples) -- [API Reference](https://influxdb-client.readthedocs.io/en/stable/api.html) -- [CHANGELOG.md](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** - -```python -from influxdb import InfluxDBClient - -client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname') -``` - -**influxdb-client-python** - -```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** - -```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** - -```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** - -```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** - -```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** - -```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** - -```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** - -```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** - -```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** - -```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](https://docs.python.org/3/library/dataclasses.html) way: - -**influxdb-client-python** - -```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** - -```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** - -```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** - -```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** - -```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: - -```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](https://github.com/influxdata/flux/blob/master/docs/SPEC.md#response-format). \ No newline at end of file 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