Python SDK

The arc-tsdb-client package for Arc: a typed Python client covering ingestion, querying into pandas or Arrow, and the data-lifecycle and admin endpoints.

Official Python SDK for the Arc 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

import os
from arc_client import ArcClient

ARC_TOKEN = os.environ["ARC_TOKEN"]

with ArcClient(host="localhost", token=os.environ["ARC_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