Metadata-Version: 2.1
Name: influxalchemy
Version: 0.3.0
Summary: InfluxDB Alchemy.
Author-email: Alexander Mancevice <alexander.mancevice@hey.com>
Requires-Python: >= 3.7
Description-Content-Type: text/markdown
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Dist: influxdb >= 5.0
Requires-Dist: pytz >= 2018.3
Requires-Dist: requests >= 2.20
Requires-Dist: six >= 1.11
Project-URL: Home, https://github.com/amancevice/knackhq

# InfluxAlchemy

![pypi](https://img.shields.io/pypi/v/influxalchemy?color=yellow&logo=python&logoColor=eee&style=flat-square)
![python](https://img.shields.io/pypi/pyversions/influxalchemy?logo=python&logoColor=eee&style=flat-square)
[![pytest](https://img.shields.io/github/actions/workflow/status/amancevice/influxalchemy/pytest.yml?logo=github&style=flat-square)](https://github.com/amancevice/influxalchemy/actions/workflows/pytest.yml)
[![coverage](https://img.shields.io/codeclimate/coverage/amancevice/influxalchemy?logo=code-climate&style=flat-square)](https://codeclimate.com/github/amancevice/influxalchemy/test_coverage)
[![maintainability](https://img.shields.io/codeclimate/maintainability/amancevice/influxalchemy?logo=code-climate&style=flat-square)](https://codeclimate.com/github/amancevice/influxalchemy/maintainability)

Query InfluxDB using SQLAlchemy-style syntax

## Installation

```bash
pip install influxalchemy
```

## Usage

```python
import influxdb
import influxalchemy
```

### Define InfluxAlchemy Measurements

```python
class Widgets(influxalchemy.Measurement):
    __measurement__ = 'widgets'


class Wombats(influxalchemy.Measurement):
    __measurement__ = 'wombats'
```

The class-attribute `__measurement__` can be omitted and will default to the class name if absent.

### Open InfluxAlchemy Connection

```python
db = influxdb.DataFrameClient(database="example")
flux = influxalchemy.InfluxAlchemy(db)
```

## Query InfluxDB

### Query Single Measurement

```python
# SELECT * FROM widgets;
flux.query(Widgets)
```

### Query Ad Hoc Measurement

```python
# SELECT * from /.*/;
flux.query(influxalchemy.Measurement.new("/.*/"))
```

### Select Fields of Measurement

```python
# SELECT tag1, field2 FROM widgets;
flux.query(Widgets.tag1, Widgets.field2)
```

### Query Across Measurements

```python
# SELECT * FROM /widgets|wombats/;
flux.query(Widgets | Wombats)
```

### Filter Tags

```python
# SELECT * FROM widgets WHERE tag1 = 'fizz';
flux.query(Widgets).filter(Widgets.tag1 == "fizz")
```

### Filter Tags with 'like'

```python
# SELECT * FROM widgets WHERE tag1 =~ /z$/;
flux.query(Widgets).filter(Widgets.tag1.like("/z$/"))
```

### Chain Filters

```python
clause1 = Widgets.tag1 == "fizz"
clause2 = Widgets.tag2 == "buzz"

# SELECT * FROM widgets WHERE tag1 = 'fizz' AND tag2 = 'buzz';
flux.query(Widgets).filter(clause1 & clause2)

# SELECT * FROM widgets WHERE tag1 = 'fizz' OR tag2 = 'buzz';
flux.query(Widgets).filter(clause1 | clause2)
```

### Group By

```python
# SELECT * FROM widgets GROUP BY time(1d);
flux.query(Widgets).group_by("time(1d)")

# SELECT * FROM widgets GROUP BY tag1;
flux.query(Widgets).group_by(Widgets.tag1)
```

### Time

```python
# SELECT * FROM widgets WHERE (time > now() - 7d);
flux.query(Widgets).filter(Widgets.time > "now() - 7d")

# SELECT * FROM widgets WHERE time >= '2016-01-01' AND time <= now() - 7d;
d = date(2016, 1, 1)
flux.query(Widgets).filter(Widgets.time.between(d, "now() - 7d"))
```

Note that naive datetime object will be assumed in UTC timezone.

