Skip to content

Commit 9720106

Browse files
author
Jay Clifford
committed
updated python package
1 parent d5f8f29 commit 9720106

File tree

7 files changed

+76
-471
lines changed

7 files changed

+76
-471
lines changed

‎README.md

+71-128
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,87 @@
1-
# About
2-
This is a community repository of Python code for InfluxDB with IOx. While this code is built on officially supported APIs, the library and CLI here are not officially support by Influx Data.
3-
4-
When installed, you have access to 2 pieces of functionality:
5-
1. A CLI for reading and writing data to InfluxDB with IOx.
6-
2. A client library for reading and writing data to InfluxDB with IOx.
7-
8-
# Install
9-
To install only the client:
1+
<p align="center">
2+
<img src="python-logo.png" alt="Your Image" width="150px">
3+
</p>
4+
5+
<p align="center">
6+
<a href="https://pypi.org/project/influxdb3-python/">
7+
<img src="https://img.shields.io/pypi/v/influxdb3-python.svg" alt="PyPI version">
8+
</a>
9+
<a href="https://pypi.org/project/influxdb3-python/">
10+
<img src="https://img.shields.io/pypi/dm/influxdb3-python.svg" alt="PyPI downloads">
11+
</a>
12+
<a href="https://github.com/InfluxCommunity/influxdb3-python/actions/workflows/pylint.yml">
13+
<img src="https://github.com/InfluxCommunity/influxdb3-python/actions/workflows/pylint.yml/badge.svg" alt="Lint Code Base">
14+
</a>
15+
<a href="https://github.com/InfluxCommunity/influxdb3-python/actions/workflows/python-publish.yml">
16+
<img src="https://github.com/InfluxCommunity/influxdb3-python/actions/workflows/python-publish.yml/badge.svg" alt="Lint Code Base">
17+
</a>
18+
<a href="https://app.slack.com/huddle/influxcommunity/">
19+
<img src="https://img.shields.io/badge/slack-join_chat-white.svg?logo=slack&style=social" alt="Community Slack">
20+
</a>
21+
</p>
22+
23+
# InfluxDB 3.0 Python Client
24+
## Introduction
25+
26+
`influxdb_client_3` is a Python module that provides a simple and convenient way to interact with InfluxDB 3.0. This module supports both writing data to InfluxDB and querying data using the Flight client, which allows you to execute SQL and InfluxQL queries on InfluxDB 3.0.
27+
28+
## Dependencies
29+
30+
- `pyarrow`
31+
- `influxdb-client`
32+
33+
## Installation
34+
35+
You can install the dependencies using `pip`:
1036

1137
```bash
12-
python3 -m pip install pyinflux3
38+
pip install influxdb3-client
1339
```
1440

15-
To install the client and CLI:
16-
17-
```bash
18-
sudo python3 -m pip install "pyinflux3[cli]"
41+
# Usage
42+
## Importing the Module
43+
```python
44+
from influxdb_client_3 import InfluxDBClient3, Point
1945
```
2046

21-
***Note: Use sudo if you would like to directly install the client onto your path. Otherwise use the `--user` flag.**
22-
23-
# Add a Config
24-
25-
To configure `pyinflux3` and the CLI, do one of the following:
26-
27-
You can drop a config file called `config.json` in the directory where you are running the `influx3` command:
47+
## Initialization
48+
If you are using InfluxDB Cloud, then you should note that:
49+
1. You will need to supply your org id, this is not necessary for InfluxDB Dedicated.
50+
2. Use a bucketname for the database argument.
2851

29-
```json
30-
{
31-
"my-config": {
32-
"database": "your-database",
33-
"host": "your-host",
34-
"token": "your-token",
35-
"org": "your-org-id",
36-
"active": true
37-
}
38-
}
52+
```python
53+
client = InfluxDBClient3(token="your-token",
54+
host="your-host",
55+
org="your-org",
56+
database="your-database")
3957
```
4058

59+
## Writing Data
60+
You can write data using the Point class, or supplying line protocol.
4161

42-
- Use the `config` command to create or modify a config:
43-
44-
```
45-
influx3 config \
46-
--name="my-config" \
47-
--database="<database or bucket name>" \
48-
--host="us-east-1-1.aws.cloud2.influxdata.com" \
49-
--token="<your token>" \
50-
--org="<your org ID>"
51-
```
52-
53-
If you are running against InfluxDB Cloud Serverless, then use the _bucket name_ as the database in your configuration.
54-
55-
# Run as a Command
56-
62+
### Using Points
63+
```python
64+
point = Point("measurement").tag("location", "london").field("temperature", 42)
65+
client.write(point)
5766
```
58-
influx3 sql "select * from anomalies"
67+
### Using Line Protocol
68+
```python
69+
point = "measurement fieldname=0"
70+
client.write(point)
5971
```
6072

73+
## Querying with SQL
74+
```python
75+
query = "select * from measurement"
76+
reader = client.query(query=query, language="sql")
77+
table = reader.read_all()
78+
print(table.to_pandas().to_markdown())
6179
```
62-
influx3 write testmes f=7
63-
```
64-
65-
# Query and Write Interactively
66-
67-
In your terminal, enter the following command:
68-
69-
```
70-
influx3
71-
```
72-
73-
`influx3` displays the `(>)` interactive prompt and waits for input.
74-
75-
```
76-
Welcome to my IOx CLI.
77-
78-
(>)
79-
```
80-
81-
To query, type `sql` at the prompt.
82-
83-
```
84-
(>) sql
85-
```
86-
87-
At the `(sql >)` prompt, enter your query statement:
8880

81+
## Querying with influxql
82+
```python
83+
query = "select * from measurement"
84+
reader = client.query(query=query, language="influxql")
85+
table = reader.read_all()
86+
print(table.to_pandas().to_markdown())
8987
```
90-
(sql >) select * from home
91-
```
92-
93-
The `influx3` CLI displays query results in Markdown table format--for example:
94-
95-
```
96-
| | co | hum | room | temp | time |
97-
|----:|-----:|------:|:------------|-------:|:------------------------------|
98-
| 0 | 0 | 35.9 | Kitchen | 21 | 2023-03-09 08:00:00 |
99-
| 1 | 0 | 35.9 | Kitchen | 21 | 2023-03-09 08:00:50 |
100-
```
101-
102-
To write, type `write` at the `(>)` prompt.
103-
104-
```
105-
(>) write
106-
```
107-
108-
At the `(write >)` prompt, enter line protocol data.
109-
110-
```
111-
(>) write
112-
home,room=kitchen temp=70.5,hum=80
113-
```
114-
115-
To exit a prompt, enter `exit`.
116-
117-
# Write from a File
118-
119-
Both the InfluxDB CLI and Client libary support writing from a CSV file. The CSV file must have a header row with the column names. The there must be a column containing a timestamp. Here are the parse options:
120-
* `--file` - The path to the csv file.
121-
* `--time` - The name of the column containing the timestamp.
122-
* `--measurement` - The name of the measurment to store the CSV data under. (Currently only supports user specified string)
123-
* `--tags` - (optional) Specify an array of column names to use as tags. (Currently only supports user specified strings) for example: `--tags=host,region`
124-
125-
```bash
126-
influx3 write_csv --file ./Examples/example.csv --measurement table2 --time Date --tags host,region
127-
```
128-
129-
# Client library
130-
This project also includes a new client library that strives for utter simplicity. It includes 3 functions, a constuctor, write(), and read().
131-
132-
# Contribution
133-
If you are working on a new feature for either the CLI or the Client Libary please make sure you test both for breaking changes. This can currently be achived using the following method:
134-
```bash
135-
python3 -m venv .venv
136-
source .venv/bin/activate
137-
chmod +x ./test/test-package.sh
138-
./test/test-package.sh
139-
```
140-
Any time you make changes in your code and want to retest just run the script again:
141-
```
142-
./test/test-package.sh
143-
```
144-

‎influxdb_cli/__init__.py

Whitespace-only changes.

0 commit comments

Comments
 (0)