greptimedb-ingester

中文

Python write client for GreptimeDB, binding greptimedb-ingester 0.19.0. Python 3.10 and later. Calls are synchronous.

• Client.insert: gRPC row writes. If the table does not exist, GreptimeDB creates it from the schema in the request.
• Client.bulk_writer: Arrow Flight bulk writes. The table must already exist.

The client connects to the gRPC port, 127.0.0.1:4001 by default.

See docs/usage.md for the full guide and docs/api.md for the API reference.

Install

pip:

pip install greptimedb-ingester

uv:

uv add greptimedb-ingester

requirements.txt:

greptimedb-ingester

pip install -r requirements.txt

or:

uv pip install -r requirements.txt

The installer picks the wheel for the local OS and CPU. One wheel covers Python 3.10, 3.11, 3.12, and later on that platform.

You can also download a wheel from the GitHub Release.

The examples below use the Linux x86_64 filename. Substitute the file that matches the local platform.

pip:

pip install greptimedb_ingester-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl

uv:

uv add greptimedb_ingester-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl

To install into an existing virtual environment:

uv pip install greptimedb_ingester-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl

Put the wheel path in requirements.txt:

./greptimedb_ingester-0.1.0-cp310-abi3-manylinux_2_28_x86_64.whl

Then:

pip install -r requirements.txt

or:

uv pip install -r requirements.txt

Building from source requires Rust 1.85 or later:

pip install maturin
maturin build --release
pip install dist/greptimedb_ingester-*.whl

Write

from datetime import datetime, timezone

from greptimedb_ingester import Client, Column, ColumnDataType, SemanticType

client = Client(["127.0.0.1:4001"], database="public")

affected = client.insert(
    "sensor_data",
    columns=[
        Column("device_id", ColumnDataType.STRING, SemanticType.TAG),
        Column("ts", ColumnDataType.TIMESTAMP_MILLISECOND, SemanticType.TIMESTAMP),
        Column("temperature", ColumnDataType.FLOAT64, SemanticType.FIELD),
    ],
    rows=[
        ["device_001", datetime(2009, 2, 13, 23, 31, 30, tzinfo=timezone.utc), 23.5],
        {"device_id": "device_002", "ts": 1_234_567_890_001, "temperature": 24.0},
    ],
)
print(affected)

If sensor_data does not exist, this insert creates it. examples/insert_example.py also writes into a table that already exists. Bulk writes are in examples/bulk_example.py; the table must already exist.

Development

uv python pin 3.10
uv sync --group dev
uv run maturin develop
uv run pytest

pytest checks value conversion only. It does not connect to GreptimeDB.