Python SDK

Official Python SDK for Arc time-series database.

What is it?

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

• Writing time-series data at scale (9M+ records/sec)
• 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

Documentation

📦 Installation

Install the SDK and optional dependencies for pandas, polars, or all features.

Get Started

📥 Data Ingestion

Write data using columnar format, DataFrames, buffered writes, or line protocol.

Learn More

🔍 Querying

Run SQL queries and get results as JSON, pandas, polars, or PyArrow tables.

Learn More

🔄 Data Management

Manage retention policies, continuous queries, delete operations, and authentication.

Learn More

Source Code

• Repository: github.com/basekick-labs/arc-client-python
• PyPI: pypi.org/project/arc-tsdb-client