# API Reference — Plasma

## SupersetClient

Основной клиент для работы с Superset REST API.

### Инициализация

```python
from src.superset_client import SupersetClient

client = SupersetClient(
    url="http://localhost:8088",
    username="admin",
    password="admin",
    timeout=30,
    retries=3
)

# Логин
client.login()
```

### Database Operations

#### get_databases()
Получить список всех БД.

```python
databases = client.get_databases()
for db in databases:
    print(f"{db['id']}: {db['database_name']}")
```

#### get_database(database_id)
Получить информацию о конкретной БД.

```python
db = client.get_database(1)
print(db['sqlalchemy_uri'])
```

#### test_database_connection(sqlalchemy_uri)
Проверить подключение к БД.

```python
is_connected = client.test_database_connection("postgresql://user:pass@localhost/db")
```

### Dataset Operations

#### get_datasets(limit=100)
Получить список датасетов.

```python
datasets = client.get_datasets(limit=50)
```

#### create_dataset(name, database_id, table_name, schema="public", columns=None)
Создать датасет.

```python
dataset = client.create_dataset(
    name="sales_data",
    database_id=1,
    table_name="sales",
    schema="public",
    columns=["id", "date", "amount", "region"]
)
dataset_id = dataset['id']
```

#### get_dataset(dataset_id)
Получить информацию о датасете.

```python
dataset = client.get_dataset(5)
print(dataset['table_name'])
print(dataset['columns'])
```

#### update_dataset(dataset_id, **kwargs)
Обновить датасет.

```python
client.update_dataset(5, description="Updated description")
```

#### delete_dataset(dataset_id)
Удалить датасет.

```python
client.delete_dataset(5)
```

#### get_dataset_samples(dataset_id)
Получить примеры данных.

```python
samples = client.get_dataset_samples(5)
print(samples['data'])
```

### Chart Operations

#### create_chart(name, dataset_id, viz_type, dimensions=None, metrics=None, filters=None, **kwargs)
Создать чарт.

```python
chart = client.create_chart(
    name="Sales by Region",
    dataset_id=5,
    viz_type="bar",
    dimensions=["region"],
    metrics=["sum__amount"],
    filters=[
        {
            "clause": "WHERE",
            "subject": "date",
            "operator": ">=",
            "comparator": "2026-01-01"
        }
    ]
)
chart_id = chart['id']
```

**Поддерживаемые viz_type:**
- `bar` — Bar chart
- `line` — Line chart
- `pie` — Pie chart
- `table` — Table
- `scatter` — Scatter plot
- `heatmap` — Heatmap
- `big_number` — KPI number
- `gauge` — Gauge chart

#### get_chart(chart_id)
Получить информацию о чарте.

```python
chart = client.get_chart(10)
```

#### update_chart(chart_id, **kwargs)
Обновить чарт.

```python
client.update_chart(10, slice_name="Updated Chart Name")
```

#### delete_chart(chart_id)
Удалить чарт.

```python
client.delete_chart(10)
```

### Dashboard Operations

#### create_dashboard(name, description="", charts=None, layout=None)
Создать дашборд.

```python
dashboard = client.create_dashboard(
    name="Sales Dashboard",
    description="Main sales metrics",
    charts=[
        {"id": 10},
        {"id": 11},
        {"id": 12}
    ],
    layout={
        10: {"x": 0, "y": 0, "w": 6, "h": 4},
        11: {"x": 6, "y": 0, "w": 6, "h": 4},
        12: {"x": 0, "y": 4, "w": 12, "h": 4}
    }
)
dashboard_id = dashboard['id']
```

#### get_dashboard(dashboard_id)
Получить информацию о дашборде.

```python
dashboard = client.get_dashboard(1)
```

#### update_dashboard(dashboard_id, name=None, description=None, layout=None, published=None)
Обновить дашборд.

```python
client.update_dashboard(
    1,
    name="Updated Dashboard",
    published=True
)
```

#### delete_dashboard(dashboard_id)
Удалить дашборд.

```python
client.delete_dashboard(1)
```

#### publish_dashboard(dashboard_id)
Опубликовать дашборд.

```python
client.publish_dashboard(1)
```

#### add_chart_to_dashboard(dashboard_id, chart_id, x=0, y=0, w=6, h=4)
Добавить чарт на дашборд.

```python
client.add_chart_to_dashboard(
    dashboard_id=1,
    chart_id=10,
    x=0,
    y=0,
    w=6,
    h=4
)
```

---

## DataLoader

Загрузка и подготовка данных.

### load_csv(file_path, **kwargs)
Загрузить CSV файл.

```python
from src.data_loader import DataLoader

loader = DataLoader()
df = loader.load_csv("data/sales.csv")
```

### load_json(file_path, **kwargs)
Загрузить JSON файл.

```python
df = loader.load_json("data/data.json")
```

### validate_dataframe(df)
Валидировать DataFrame.

```python
stats = loader.validate_dataframe(df)
print(f"Rows: {stats['rows']}")
print(f"Columns: {stats['columns']}")
print(f"Null counts: {stats['null_counts']}")
```

### clean_dataframe(df, drop_duplicates=True, drop_nulls=False)
Очистить DataFrame.

```python
df_clean = loader.clean_dataframe(df, drop_duplicates=True)
```

### infer_column_types(df)
Определить типы колонок.

```python
types = loader.infer_column_types(df)
# {'date': 'DATETIME', 'amount': 'FLOAT', 'region': 'STRING'}
```

### detect_metrics_and_dimensions(df)
Автоматически определить metrics и dimensions.

```python
result = loader.detect_metrics_and_dimensions(df)
# {'metrics': ['amount', 'quantity'], 'dimensions': ['date', 'region']}
```

---

## VizTemplates

Шаблоны визуализаций.

### bar_chart(dimensions, metrics, title, sort_by=None, limit=None)
Создать конфиг bar chart.

```python
from src.viz_templates import VizTemplates

config = VizTemplates.bar_chart(
    dimensions=["region"],
    metrics=["sum__revenue"],
    title="Revenue by Region",
    limit=10
)
```

### line_chart(dimensions, metrics, title, sort_by=None)
Создать конфиг line chart.

```python
config = VizTemplates.line_chart(
    dimensions=["date"],
    metrics=["sum__revenue"],
    title="Revenue Trend"
)
```

### pie_chart(dimensions, metrics, title, limit=10)
Создать конфиг pie chart.

```python
config = VizTemplates.pie_chart(
    dimensions=["category"],
    metrics=["count"],
    title="Distribution"
)
```

### table_chart(columns, title, limit=1000, show_index=False)
Создать конфиг table chart.

```python
config = VizTemplates.table_chart(
    columns=["id", "date", "amount", "region"],
    title="Sales Data"
)
```

### number_chart(metric, title, format_spec=".0f")
Создать конфиг KPI number.

```python
config = VizTemplates.number_chart(
    metric="sum__revenue",
    title="Total Revenue",
    format_spec=",.0f"
)
```

---

## SchemaBuilder

Построение схемы датасета.

### configure_columns(dataset_id, columns)
Настроить свойства колонок.

```python
from src.schema_builder import SchemaBuilder

builder = SchemaBuilder(client)
builder.configure_columns(
    dataset_id=5,
    columns={
        "date": {"is_dttm": True, "filterable": True},
        "region": {"filterable": True, "groupby": True},
        "amount": {"filterable": False}
    }
)
```

### add_metric(dataset_id, metric_name, expression, description="")
Добавить virtual metric.

```python
builder.add_metric(
    dataset_id=5,
    metric_name="total_revenue",
    expression="SUM(amount)",
    description="Total revenue"
)
```

### set_temporal_column(dataset_id, column_name, date_format="YYYY-MM-DD")
Установить temporal column.

```python
builder.set_temporal_column(5, "order_date")
```

### set_filterable_columns(dataset_id, column_names)
Установить filterable колонки.

```python
builder.set_filterable_columns(5, ["region", "category", "date"])
```

---

## DashboardComposer

Сборка дашбордов.

### create_dashboard(name, description="", charts=None, layout=None, publish=False)
Создать дашборд.

```python
from src.dashboard_composer import DashboardComposer

composer = DashboardComposer(client)
dashboard = composer.create_dashboard(
    name="Sales Dashboard",
    charts=[chart1, chart2],
    publish=True
)
```

### create_kpi_dashboard(name, kpi_charts, detail_charts=None, description="")
Создать KPI дашборд.

```python
dashboard = composer.create_kpi_dashboard(
    name="KPI Dashboard",
    kpi_charts=[kpi1, kpi2, kpi3],
    detail_charts=[detail1, detail2]
)
```

### create_time_series_dashboard(name, time_series_chart, breakdown_charts=None, description="")
Создать time series дашборд.

```python
dashboard = composer.create_time_series_dashboard(
    name="Trend Analysis",
    time_series_chart=ts_chart,
    breakdown_charts=[breakdown1, breakdown2]
)
```

---

## PlasmaAgent

Оркестратор для автоматизации.

### create_dashboard_from_csv(csv_file, dashboard_name, database_id, dataset_name=None, charts_config=None, publish=False)
Создать полный дашборд из CSV.

```python
from src.agent import PlasmaAgent

agent = PlasmaAgent()
dashboard = agent.create_dashboard_from_csv(
    csv_file="data/sales.csv",
    dashboard_name="Sales Dashboard",
    database_id=1,
    charts_config=[
        {
            "viz_type": "bar",
            "dimensions": ["region"],
            "metrics": ["amount"],
            "title": "Sales by Region"
        }
    ],
    publish=True
)
```

### create_kpi_dashboard(dataset_id, dashboard_name, kpi_metrics, detail_charts=None, publish=False)
Создать KPI дашборд.

```python
dashboard = agent.create_kpi_dashboard(
    dataset_id=5,
    dashboard_name="Sales KPI",
    kpi_metrics=[
        {"metric": "count", "title": "Total Orders"},
        {"metric": "sum__revenue", "title": "Total Revenue"}
    ],
    publish=True
)
```

### create_time_series_dashboard(dataset_id, dashboard_name, time_dimension, metric, breakdown_dimension=None, publish=False)
Создать time series дашборд.

```python
dashboard = agent.create_time_series_dashboard(
    dataset_id=5,
    dashboard_name="Revenue Trend",
    time_dimension="order_date",
    metric="sum__revenue",
    breakdown_dimension="region",
    publish=True
)
```

### list_datasets(), list_dashboards(), list_charts()
Получить списки объектов.

```python
datasets = agent.list_datasets()
dashboards = agent.list_dashboards()
charts = agent.list_charts()
```

### delete_dashboard(dashboard_id), delete_dataset(dataset_id), delete_chart(chart_id)
Удалить объекты.

```python
agent.delete_dashboard(1)
agent.delete_dataset(5)
agent.delete_chart(10)
```

---

## Ошибки и обработка

### 401 Unauthorized
- Проверь username и password
- Убедись, что пользователь имеет права Editor или Admin

### 400 Bad Request
- Проверь структуру JSON
- Убедись, что dataset_id существует
- Проверь типы данных (dimensions — строки, metrics — числа)

### 404 Not Found
- Проверь, что объект существует
- Используй правильный ID

### Retry Logic
Клиент автоматически повторяет запросы при ошибке (по умолчанию 3 попытки).

```python
client = SupersetClient(retries=5)  # Увеличить количество повторов
```

---

**Версия:** 0.1  
**Дата:** 2026-04-27