Python SDK

arc-tsdb-client for Arc Enterprise: point ArcClient at a cluster endpoint with an RBAC-scoped token, then write, query, and administer retention and continuous queries from Python.

Official Python SDK for the Arc Enterprise time-series database.

What is it?

The arc-tsdb-client package is the official Python client for Arc, an open, SQL-native time-series database. It provides a high-level, Pythonic interface for:

Writing data at scale
Querying with SQL and getting results as DataFrames
Managing data lifecycle (retention, aggregation, deletion)
Handling authentication (tokens, permissions)

Why use the SDK?

While you can interact with Arc's REST API directly, the SDK provides significant advantages:

Feature	Raw API	Python SDK
Connection management	Manual	Automatic (context managers)
Data serialization	Manual MessagePack	Automatic
DataFrame support	Convert manually	Native pandas/polars/arrow
Buffered writes	Implement yourself	Built-in with auto-batching
Error handling	Parse HTTP responses	Typed exceptions
Async support	Manual httpx/aiohttp	Built-in `AsyncArcClient`
Compression	Configure headers	Automatic gzip

Quick example

from arc_client import ArcClient

with ArcClient(host="localhost", token="your-token") as client:
    # Write metrics
    client.write.write_columnar(
        measurement="cpu",
        columns={
            "time": [1704067200000000, 1704067260000000],
            "host": ["server01", "server01"],
            "usage_idle": [95.2, 94.8],
        },
    )

    # Query to pandas
    df = client.query.query_pandas(
        "SELECT * FROM default.cpu WHERE host = 'server01'"
    )
    print(df)

Architecture

The SDK is organized into specialized clients for different operations:

ArcClient
├── .write          # Data ingestion (WriteClient)
│   ├── write_columnar()
│   ├── write_dataframe()
│   ├── write_line_protocol()
│   └── buffered()
│
├── .query          # Data querying (QueryClient)
│   ├── query()
│   ├── query_pandas()
│   ├── query_polars()
│   ├── query_arrow()
│   └── estimate()
│
├── .retention      # Retention policies (RetentionClient)
├── .continuous_queries  # CQs (ContinuousQueryClient)
├── .delete         # Delete operations (DeleteClient)
├── .auth           # Authentication (AuthClient)
└── .health()       # Health check