Skip to content

Commit 74d89a7

Browse files
bednarbednar
authored
docs: add Migration Guide (#331)
1 parent 2d5abca commit 74d89a7

File tree

4 files changed

+342
-0
lines changed

4 files changed

+342
-0
lines changed

‎CHANGELOG.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
## 1.22.0 [unreleased]
22

3+
### Documentation
4+
1. [#331](https://github.com/influxdata/influxdb-client-python/pull/331): Add [Migration Guide](MIGRATION_GUIDE.rst)
5+
36
## 1.21.0 [2021-09-17]
47

58
### Features

‎MIGRATION_GUIDE.rst

Lines changed: 337 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,337 @@
1+
Migration Guide
2+
===============
3+
4+
This guide is meant to help you migrate your Python code from
5+
`influxdb-python <https://github.com/influxdata/influxdb-python>`__ to
6+
``influxdb-client-python`` by providing code examples that cover common
7+
usages.
8+
9+
If there is something missing, please feel free to create a `new
10+
request <https://github.com/influxdata/influxdb-client-python/issues/new?assignees=&labels=documentation&title=docs(migration%20guide):%20&template=feature_request.md>`__
11+
for a guide enhancement.
12+
13+
Before You Start
14+
----------------
15+
16+
Please take a moment to review the following client docs:
17+
18+
- `User Guide <https://influxdb-client.readthedocs.io/en/stable/usage.html>`__, `README.rst <https://github.com/influxdata/influxdb-client-python#influxdb-client-python>`__
19+
- `Examples <https://github.com/influxdata/influxdb-client-python/tree/master/examples#examples>`__
20+
- `API Reference <https://influxdb-client.readthedocs.io/en/stable/api.html>`__
21+
- `CHANGELOG.md <https://github.com/influxdata/influxdb-client-python/blob/master/CHANGELOG.md>`__
22+
23+
Content
24+
-------
25+
26+
- `Initializing Client <#initializing-client>`__
27+
- `Creating Database/Bucket <#creating-databasebucket>`__
28+
- `Dropping Database/Bucket <#dropping-databasebucket>`__
29+
- Writes
30+
- `LineProtocol <#writing-lineprotocol>`__
31+
- `Dictionary-style object <#writing-dictionary-style-object>`__
32+
- `Structured data <#writing-structured-data>`__
33+
- `Pandas DataFrame <#writing-pandas-dataframe>`__
34+
- `Querying <#querying>`__
35+
36+
Initializing Client
37+
-------------------
38+
39+
**influxdb-python**
40+
41+
.. code:: python
42+
43+
from influxdb import InfluxDBClient
44+
45+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
46+
47+
**influxdb-client-python**
48+
49+
.. code:: python
50+
51+
from influxdb_client import InfluxDBClient
52+
53+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
54+
pass
55+
56+
Creating Database/Bucket
57+
------------------------
58+
59+
**influxdb-python**
60+
61+
.. code:: python
62+
63+
from influxdb import InfluxDBClient
64+
65+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
66+
67+
dbname = 'example'
68+
client.create_database(dbname)
69+
client.create_retention_policy('awesome_policy', '60m', 3, database=dbname, default=True)
70+
71+
**influxdb-client-python**
72+
73+
.. code:: python
74+
75+
from influxdb_client import InfluxDBClient, BucketRetentionRules
76+
77+
org = 'my-org'
78+
79+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org=org) as client:
80+
buckets_api = client.buckets_api()
81+
82+
# Create Bucket with retention policy set to 3600 seconds and name "bucket-by-python"
83+
retention_rules = BucketRetentionRules(type="expire", every_seconds=3600)
84+
created_bucket = buckets_api.create_bucket(bucket_name="bucket-by-python",
85+
retention_rules=retention_rules,
86+
org=org)
87+
88+
Dropping Database/Bucket
89+
------------------------
90+
91+
**influxdb-python**
92+
93+
.. code:: python
94+
95+
from influxdb import InfluxDBClient
96+
97+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
98+
99+
dbname = 'example'
100+
client.drop_database(dbname)
101+
102+
**influxdb-client-python**
103+
104+
.. code:: python
105+
106+
from influxdb_client import InfluxDBClient
107+
108+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
109+
buckets_api = client.buckets_api()
110+
111+
bucket = buckets_api.find_bucket_by_name("my-bucket")
112+
buckets_api.delete_bucket(bucket)
113+
114+
Writing LineProtocol
115+
--------------------
116+
117+
**influxdb-python**
118+
119+
.. code:: python
120+
121+
from influxdb import InfluxDBClient
122+
123+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
124+
125+
client.write('h2o_feet,location=coyote_creek water_level=1.0 1', protocol='line')
126+
127+
**influxdb-client-python**
128+
129+
.. code:: python
130+
131+
from influxdb_client import InfluxDBClient
132+
from influxdb_client.client.write_api import SYNCHRONOUS
133+
134+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
135+
write_api = client.write_api(write_options=SYNCHRONOUS)
136+
137+
write_api.write(bucket='my-bucket', record='h2o_feet,location=coyote_creek water_level=1.0 1')
138+
139+
Writing Dictionary-style object
140+
-------------------------------
141+
142+
**influxdb-python**
143+
144+
.. code:: python
145+
146+
from influxdb import InfluxDBClient
147+
148+
record = [
149+
{
150+
"measurement": "cpu_load_short",
151+
"tags": {
152+
"host": "server01",
153+
"region": "us-west"
154+
},
155+
"time": "2009-11-10T23:00:00Z",
156+
"fields": {
157+
"Float_value": 0.64,
158+
"Int_value": 3,
159+
"String_value": "Text",
160+
"Bool_value": True
161+
}
162+
}
163+
]
164+
165+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
166+
167+
client.write_points(record)
168+
169+
**influxdb-client-python**
170+
171+
.. code:: python
172+
173+
from influxdb_client import InfluxDBClient
174+
from influxdb_client.client.write_api import SYNCHRONOUS
175+
176+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
177+
write_api = client.write_api(write_options=SYNCHRONOUS)
178+
179+
record = [
180+
{
181+
"measurement": "cpu_load_short",
182+
"tags": {
183+
"host": "server01",
184+
"region": "us-west"
185+
},
186+
"time": "2009-11-10T23:00:00Z",
187+
"fields": {
188+
"Float_value": 0.64,
189+
"Int_value": 3,
190+
"String_value": "Text",
191+
"Bool_value": True
192+
}
193+
}
194+
]
195+
196+
write_api.write(bucket='my-bucket', record=record)
197+
198+
Writing Structured Data
199+
-----------------------
200+
201+
**influxdb-python**
202+
203+
.. code:: python
204+
205+
from influxdb import InfluxDBClient
206+
from influxdb import SeriesHelper
207+
208+
my_client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
209+
210+
211+
class MySeriesHelper(SeriesHelper):
212+
class Meta:
213+
client = my_client
214+
series_name = 'events.stats.{server_name}'
215+
fields = ['some_stat', 'other_stat']
216+
tags = ['server_name']
217+
bulk_size = 5
218+
autocommit = True
219+
220+
221+
MySeriesHelper(server_name='us.east-1', some_stat=159, other_stat=10)
222+
MySeriesHelper(server_name='us.east-1', some_stat=158, other_stat=20)
223+
224+
MySeriesHelper.commit()
225+
226+
227+
The ``influxdb-client-python`` doesn't have an equivalent implementation for ``MySeriesHelper``, but there is an option
228+
to use Python `Data Classes <https://docs.python.org/3/library/dataclasses.html>`__ way:
229+
230+
**influxdb-client-python**
231+
232+
.. code:: python
233+
234+
from dataclasses import dataclass
235+
236+
from influxdb_client import InfluxDBClient
237+
from influxdb_client.client.write_api import SYNCHRONOUS
238+
239+
240+
@dataclass
241+
class Car:
242+
"""
243+
DataClass structure - Car
244+
"""
245+
engine: str
246+
type: str
247+
speed: float
248+
249+
250+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
251+
write_api = client.write_api(write_options=SYNCHRONOUS)
252+
253+
car = Car('12V-BT', 'sport-cars', 125.25)
254+
255+
write_api.write(bucket="my-bucket",
256+
record=car,
257+
record_measurement_name="performance",
258+
record_tag_keys=["engine", "type"],
259+
record_field_keys=["speed"])
260+
261+
Writing Pandas DataFrame
262+
------------------------
263+
264+
**influxdb-python**
265+
266+
.. code:: python
267+
268+
import pandas as pd
269+
270+
from influxdb import InfluxDBClient
271+
272+
df = pd.DataFrame(data=list(range(30)),
273+
index=pd.date_range(start='2014-11-16', periods=30, freq='H'),
274+
columns=['0'])
275+
276+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
277+
278+
client.write_points(df, 'demo', protocol='line')
279+
280+
**influxdb-client-python**
281+
282+
.. code:: python
283+
284+
import pandas as pd
285+
286+
from influxdb_client import InfluxDBClient
287+
from influxdb_client.client.write_api import SYNCHRONOUS
288+
289+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org') as client:
290+
write_api = client.write_api(write_options=SYNCHRONOUS)
291+
292+
df = pd.DataFrame(data=list(range(30)),
293+
index=pd.date_range(start='2014-11-16', periods=30, freq='H'),
294+
columns=['0'])
295+
296+
write_api.write(bucket='my-bucket', record=df, data_frame_measurement_name='demo')
297+
298+
Querying
299+
--------
300+
301+
**influxdb-python**
302+
303+
.. code:: python
304+
305+
from influxdb import InfluxDBClient
306+
307+
client = InfluxDBClient(host='127.0.0.1', port=8086, username='root', password='root', database='dbname')
308+
309+
points = client.query('SELECT * from cpu').get_points()
310+
for point in points:
311+
print(point)
312+
313+
**influxdb-client-python**
314+
315+
.. code:: python
316+
317+
from influxdb_client import InfluxDBClient
318+
319+
with InfluxDBClient(url='http://localhost:8086', token='my-token', org='my-org', debug=True) as client:
320+
query = '''from(bucket: "my-bucket")
321+
|> range(start: -10000d)
322+
|> filter(fn: (r) => r["_measurement"] == "cpu")
323+
|> pivot(rowKey:["_time"], columnKey: ["_field"], valueColumn: "_value")
324+
'''
325+
326+
tables = client.query_api().query(query)
327+
for record in [record for table in tables for record in table.records]:
328+
print(record.values)
329+
330+
If you would like to omit boilerplate columns such as ``_result``, ``_table``, ``_start``, ... you can filter the record values by
331+
following expression:
332+
333+
.. code:: python
334+
335+
print({k: v for k, v in record.values.items() if k not in ['result', 'table', '_start', '_stop', '_measurement']})
336+
337+
For more info see `Flux Response Format <https://github.com/influxdata/flux/blob/master/docs/SPEC.md#response-format>`__.

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ InfluxDB 2.0 python client
88

99
usage
1010
api
11+
migration
1112

1213
.. include:: ../README.rst
1314
:start-after: marker-index-start

‎docs/migration.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
.. include:: ../MIGRATION_GUIDE.rst

0 commit comments

Comments
 (0)