Skip to content

Commit 74d89a7

Browse files
bednarbednar
authored
docs: add Migration Guide (influxdata#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)
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy