chakra-py

Chakra Python SDK

A Python SDK for interacting with the Chakra API. This SDK provides seamless integration with pandas DataFrames for data querying and manipulation.

Features

• Token-based Authentication: Secure authentication using DB Session keys
• Pandas Integration: Query results automatically converted to pandas DataFrames
• Automatic Table Management: Create and update tables with schema inference
• Batch Operations: Efficient data pushing with batched inserts

Installation

pip install chakra-py

Finding your DB Session Key

• Login to the Chakra Console
• Select Settings
• Navigate to the releveant database and copy the DB Session Key (not the access key or secret access key)

https://github.com/user-attachments/assets/9f1c1ab8-cb87-42a1-8627-184617bbb7d7

Quick Start

from chakra_py import Chakra
import pandas as pd

# Initialize client
client = Chakra("YOUR_DB_SESSION_KEY")

# Query data (returns pandas DataFrame)
df = client.execute("SELECT * FROM my_table")
print(df.head())

# Push data to a new or existing table
data = pd.DataFrame({
    "id": [1, 2, 3],
    "name": ["Alice", "Bob", "Charlie"],
    "score": [85.5, 92.0, 78.5]
})
client.push("students", data, create_if_missing=True)

Querying Data

Execute SQL queries and receive results as pandas DataFrames:

# Simple query
df = client.execute("SELECT * FROM table_name")

# Complex query with aggregations
df = client.execute("""
    SELECT 
        category,
        COUNT(*) as count,
        AVG(value) as avg_value
    FROM measurements
    GROUP BY category
    HAVING count > 10
    ORDER BY avg_value DESC
""")

# Work with results using pandas
print(df.describe())
print(df.groupby('category').agg({'value': ['mean', 'std']}))

Pushing Data

Push data from pandas DataFrames to tables with automatic schema handling:

# Create a sample DataFrame
df = pd.DataFrame({
    'id': range(1, 1001),
    'name': [f'User_{i}' for i in range(1, 1001)],
    'score': np.random.normal(75, 15, 1000).round(2),
    'active': np.random.choice([True, False], 1000)
})

# Create new table with inferred schema
client.push(
    table_name="users",
    data=df,
    create_if_missing=True  # Creates table if it doesn't exist
)

# Update existing table
new_users = pd.DataFrame({
    'id': range(1001, 1101),
    'name': [f'User_{i}' for i in range(1001, 1101)],
    'score': np.random.normal(75, 15, 100).round(2),
    'active': np.random.choice([True, False], 100)
})
client.push("users", new_users, create_if_missing=False)

The SDK automatically:

• Infers appropriate column types from DataFrame dtypes
• Creates tables with proper schema when needed
• Handles NULL values and type conversions
• Performs batch inserts for better performance

Development

To contribute to the SDK:

• Clone the repository

git clone https://github.com/Chakra-Network/python-sdk.git
cd python-sdk

• Install development dependencies with Poetry

# Install Poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies
poetry install

• Run tests

poetry run pytest

• Build package

poetry build

PyPI Publication

The package is configured for easy PyPI publication:

• Update version in pyproject.toml
• Build distribution: poetry build
• Publish: poetry publish

License

MIT License - see LICENSE file for details.

Support

For support and questions, please open an issue in the GitHub repository.