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

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

session_key.mp4

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:

1. Clone the repository

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

2. Install development dependencies with Poetry

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

# Install dependencies
poetry install

3. Run tests

poetry run pytest

4. Build package

poetry build

PyPI Publication

The package is configured for easy PyPI publication:

1. Update version in pyproject.toml
2. Build distribution: poetry build
3. Publish: poetry publish

License

MIT License - see LICENSE file for details.

Support

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