ma-platform-sdk 0.3.0
Python SDK for MA (Multi-dimensional Analysis) Platform - dbt semantic layer queries, drill-down analysis, and report generation
License: MIT
Requires Python: >=3.8
Keywords: analytics, data-platform, dbt, dimensions, metrics, multi-dimensional-analysis, olap, semantic-layer

# MA Platform SDK

Python SDK for the MA (Multi-dimensional Analysis) Platform - a dbt semantic layer service for metrics queries, drill-down analysis, and report generation.

## Features

- **Authentication**: JWT-based authentication with tenant/project context management
- **Semantic Layer Queries**: Execute metric queries with dimensions, filters, and aggregations
- **Shared Dimensions**: Support for shared dimension tables and time granularities
- **Metadata Management**: Browse semantic models, metrics, dimensions, and entities
- **Data Sources**: Manage database connectors and data source tables

## Installation

```bash
pip install ma-platform-sdk
```

## Quick Start

```python
from ma_platform_sdk import MAClient, create_client

# Method 1: Quick setup with create_client
client = create_client(
    username="admin",
    password="admin123",
    tenant_id="demo-tenant",
    project_id="demo-project"
)

# Method 2: Manual setup
client = MAClient()
client.login("admin", "admin123")
client.set_context(tenant_id="demo-tenant", project_id="demo-project")

# Execute a semantic layer query
result = client.execute_query(
    semantic_model_name="reimburse",
    metrics=["expense"],
    dimensions=["bm_name"],
    filters=[{"field": "bm_name", "op": "=", "value": "Human Resources"}],
    order_by="-expense",  # Prefix with "-" for descending
    limit=10
)

# Process results
for row in result.data:
    print(row)
```

## Working with Semantic Models

```python
# List all semantic models
models = client.list_semantic_models()
for model in models:
    print(f"{model.name}: {model.description}")

# Get model details with metrics and dimensions
model = client.get_semantic_model("reimburse")
print(f"Metrics: {[m.name for m in model.metrics]}")
print(f"Dimensions: {[d.name for d in model.dimensions]}")
```

## Time Dimensions with Granularity

```python
# Get time dimensions
time_dims = client.get_time_dimensions(model)
for dim in time_dims:
    print(f"{dim.name}: granularities = {dim.get_time_granularities()}")

# Query with time granularity
result = client.execute_query(
    semantic_model_name="reimburse",
    metrics=["expense"],
    dimensions=["bx_ts.month"],  # Use .month, .year, .day etc.
    limit=12
)
```

## Shared Dimensions

```python
# Get dimensions with shared dimension bindings
shared_dims = client.get_shared_dimensions(model)
for dim in shared_dims:
    print(f"{dim.name} -> {dim.shared_dimension_name}")
```

## API Reference

### MAClient

| Method | Description |
|--------|-------------|
| `login(username, password)` | Authenticate with the platform |
| `set_context(tenant_id, project_id)` | Set tenant/project context |
| `list_semantic_models()` | List available semantic models |
| `get_semantic_model(name)` | Get model with metrics/dimensions |
| `execute_query(...)` | Execute a semantic layer query |
| `list_saved_queries()` | List saved query definitions |

### Query Parameters

| Parameter | Type | Description |
|-----------|------|-------------|
| `semantic_model_name` | str | Name of the semantic model |
| `metrics` | list[str] | Metrics to query |
| `dimensions` | list[str] | Dimensions for grouping |
| `filters` | list[dict] | Filter conditions |
| `order_by` | str | Sort field (prefix "-" for desc) |
| `limit` | int | Maximum rows to return |

## Demo Accounts

For testing against `https://ma.infilake.com`:

| Username | Password | Role |
|----------|----------|------|
| admin | admin123 | Admin |
| engineer | engineer123 | Engineer |
| analyst | analyst123 | Analyst |

## License

MIT License