0
# InfluxDB
1
2
A comprehensive Python client library for InfluxDB, the open-source time series database. Provides full functionality for connecting to InfluxDB instances, writing time series data points, querying data with InfluxQL, managing databases and retention policies, and working with time series measurements. The library supports both standard JSON-based operations and DataFrame integration via pandas for data analysis workflows, with built-in authentication, connection pooling, batch operations, and comprehensive error handling for robust production deployments.
3
4
## Package Information
5
6
- **Package Name**: influxdb
7
- **Language**: Python
8
- **Installation**: `pip install influxdb`
9
- **Dependencies**: `requests`, `python-dateutil`, `pytz`, `six`
10
- **Optional Dependencies**: `pandas` (for DataFrameClient)
11
12
## Core Imports
13
14
```python
15
from influxdb import InfluxDBClient, DataFrameClient, SeriesHelper
16
```
17
18
For exception handling:
19
20
```python
21
from influxdb.exceptions import InfluxDBClientError, InfluxDBServerError
22
```
23
24
For line protocol utilities:
25
26
```python
27
from influxdb.line_protocol import make_line, make_lines
28
```
29
30
## Basic Usage
31
32
### Quick Start with InfluxDBClient
33
34
```python
35
from influxdb import InfluxDBClient
36
import datetime
37
38
# Connect to InfluxDB
39
client = InfluxDBClient(host='localhost', port=8086, username='root', password='root')
40
41
# Create database
42
client.create_database('mydb')
43
client.switch_database('mydb')
44
45
# Write data points
46
json_body = [
47
{
48
"measurement": "cpu_load_short",
49
"tags": {
50
"host": "server01",
51
"region": "us-west"
52
},
53
"time": "2023-09-07T07:18:24Z",
54
"fields": {
55
"value": 0.64
56
}
57
}
58
]
59
60
client.write_points(json_body)
61
62
# Query data
63
result = client.query('SELECT * FROM cpu_load_short')
64
print("Result: {0}".format(result))
65
66
# Close connection
67
client.close()
68
```
69
70
### Context Manager Usage
71
72
```python
73
from influxdb import InfluxDBClient
74
75
with InfluxDBClient(host='localhost', port=8086, database='mydb') as client:
76
# Write data
77
client.write_points([
78
{
79
"measurement": "temperature",
80
"tags": {"location": "room1"},
81
"fields": {"value": 23.5},
82
"time": "2023-09-07T07:18:24Z"
83
}
84
])
85
86
# Query data
87
results = client.query('SELECT * FROM temperature')
88
```
89
90
## Architecture
91
92
The InfluxDB Python client follows a layered architecture:
93
94
- **InfluxDBClient**: Core client with complete InfluxDB API support
95
- **DataFrameClient**: Extends InfluxDBClient for pandas DataFrame integration
96
- **SeriesHelper**: Bulk data insertion with configurable auto-commit
97
- **ResultSet**: Query result processing with filtering and iteration
98
- **Line Protocol**: Efficient data serialization for high-throughput writes
99
- **Legacy Support**: Backward compatibility with InfluxDB 0.8.x via `influxdb08` module
100
101
## Capabilities
102
103
### Core Client Operations
104
105
Comprehensive InfluxDB client with connection management, authentication, database operations, data querying and writing, user management, retention policies, continuous queries, and UDP support.
106
107
```python { .api }
108
class InfluxDBClient:
109
def __init__(self, host='localhost', port=8086, username='root', password='root',
110
database=None, ssl=False, verify_ssl=False, timeout=None, retries=3,
111
use_udp=False, udp_port=4444, proxies=None, pool_size=10, path='',
112
cert=None, gzip=False, session=None, headers=None, socket_options=None): ...
113
114
def query(self, query, params=None, bind_params=None, epoch=None,
115
expected_response_code=200, database=None, raise_errors=True,
116
chunked=False, chunk_size=0, method="GET"): ...
117
118
def write_points(self, points, time_precision=None, database=None,
119
retention_policy=None, tags=None, batch_size=None,
120
protocol='json', consistency=None): ...
121
122
def ping(self): ...
123
def close(self): ...
124
```
125
126
[Core Client](./client.md)
127
128
### DataFrame Integration
129
130
Pandas DataFrame integration for data analysis workflows, enabling direct DataFrame-to-InfluxDB operations and query results as DataFrames.
131
132
```python { .api }
133
class DataFrameClient(InfluxDBClient):
134
def write_points(self, dataframe, measurement, tags=None, tag_columns=None,
135
field_columns=None, time_precision=None, database=None,
136
retention_policy=None, batch_size=None, protocol='line',
137
numeric_precision=None): ...
138
139
def query(self, query, params=None, bind_params=None, epoch=None,
140
expected_response_code=200, database=None, raise_errors=True,
141
chunked=False, chunk_size=0, method="GET", dropna=True,
142
data_frame_index=None): ...
143
```
144
145
[DataFrame Client](./dataframe-client.md)
146
147
### Data Management Utilities
148
149
Bulk data insertion, line protocol formatting, and query result processing utilities for efficient data operations.
150
151
```python { .api }
152
class SeriesHelper:
153
def __init__(self, **kw): ...
154
def commit(cls, client=None): ...
155
156
def make_line(measurement, tags=None, fields=None, time=None, precision=None): ...
157
def make_lines(data, precision=None): ...
158
159
class ResultSet:
160
def __init__(self, series, raise_errors=True): ...
161
def get_points(self, measurement=None, tags=None): ...
162
```
163
164
[Data Management](./data-management.md)
165
166
### Database Operations
167
168
Complete database lifecycle management including database creation/deletion, user management, retention policies, continuous queries, and measurement operations.
169
170
```python { .api }
171
def create_database(self, dbname): ...
172
def drop_database(self, dbname): ...
173
def get_list_database(self): ...
174
175
def create_user(self, username, password, admin=False): ...
176
def drop_user(self, username): ...
177
def get_list_users(self): ...
178
179
def create_retention_policy(self, name, duration, replication, database=None,
180
default=False, shard_duration="0s"): ...
181
def get_list_retention_policies(self, database=None): ...
182
```
183
184
[Database Operations](./database-operations.md)
185
186
### Legacy InfluxDB 0.8 Support
187
188
Backward compatibility support for InfluxDB 0.8.x servers with dedicated client implementations.
189
190
```python { .api }
191
from influxdb.influxdb08 import InfluxDBClient as LegacyClient
192
# Legacy API with different method signatures for InfluxDB 0.8.x
193
```
194
195
[Legacy Support](./legacy.md)
196
197
## Error Handling
198
199
The library provides specific exception types for different error conditions:
200
201
```python { .api }
202
class InfluxDBClientError(Exception):
203
"""Raised when an error occurs in the request."""
204
def __init__(self, content, code=None): ...
205
206
class InfluxDBServerError(Exception):
207
"""Raised when a server error occurs (5xx status codes)."""
208
def __init__(self, content): ...
209
```
210
211
## Connection Configuration
212
213
### SSL/TLS Configuration
214
215
```python
216
client = InfluxDBClient(
217
host='influxdb.example.com',
218
port=8086,
219
ssl=True,
220
verify_ssl=True,
221
cert='/path/to/client.crt'
222
)
223
```
224
225
### Connection Pooling
226
227
```python
228
client = InfluxDBClient(
229
host='localhost',
230
pool_size=20, # Number of connections in pool
231
timeout=30 # Request timeout in seconds
232
)
233
```
234
235
### UDP Configuration
236
237
```python
238
client = InfluxDBClient(
239
host='localhost',
240
use_udp=True,
241
udp_port=4444
242
)
243
244
# Send UDP packets
245
client.send_packet(packet_data, protocol='json')
246
```