Semantic Layer API и BI integrations

В предыдущих уроках мы строили семантический слой. Сейчас — как consumer’ы его используют. dbt Semantic Layer exposes несколько API:

• JDBC — для классических BI tools (Tableau, Looker).
• GraphQL — для programmatic access (web apps, custom tools).
• Python SDK — для notebooks и data science.
• MCP — для AI инструментов (Claude, ChatGPT).

В этом уроке — обзор каждого, integrations с popular BI tools, и осознанный взгляд: когда НЕ нужен Semantic Layer.

Три типа API

Базовая модель: каждый API делает то же самое — query metrics + dimensions с filters — но в формате удобном для своего consumer’а.

Python SDK — самый простой пример

# Установка
# pip install dbt-sl-client

from dbt_sl_client import SemanticLayerClient
import os

client = SemanticLayerClient(
    environment_id=os.environ['DBT_CLOUD_ENVIRONMENT_ID'],
    auth_token=os.environ['DBT_CLOUD_TOKEN'],
    host='cloud.getdbt.com'
)

# Простой query
df = client.query(
    metrics=['net_revenue', 'total_orders'],
    group_by=['metric_time__month', 'customers__region'],
    where=["{'{{ Dimension(\'customers__country\') }}'} = 'US'"],
    order_by=['metric_time__month'],
    limit=100
)

# Это pandas DataFrame
print(df.head())
#     metric_time__month  customers__region  net_revenue  total_orders
# 0   2026-01-01          west              125000.00    1250
# 1   2026-01-01          east              98000.00      980
# ...

Возвращает DataFrame — стандартный data science workflow.

Метаданные

# Список доступных metrics
metrics = client.list_metrics()
for m in metrics:
    print(f"{m['name']}: {m['description']}")
# net_revenue: Revenue minus refunds
# total_orders: Count of orders
# ...

# Список dimensions для metric
dims = client.list_dimensions(metric='net_revenue')
# [customers__region, customers__tier, metric_time__day, metric_time__month, orders__status]

# Список saved queries
queries = client.list_saved_queries()
# [executive_monthly, sales_daily, finance_quarterly_cumulative]

# Query через saved query
df = client.query_saved_query('executive_monthly')

Это discovery API — позволяет analyst исследовать что доступно.

JDBC для BI tools

JDBC URL для dbt Cloud:

jdbc:arrow-flight-sql://semantic-layer.cloud.getdbt.com:443?
  environmentId=12345&
  useEncryption=1

С API token в Header.

Tableau

Tableau Desktop -> Other Database (JDBC) ->
  URL: jdbc:arrow-flight-sql://...
  Driver: dbt-sl-tableau-driver.jar
  Auth: dbt Cloud token

После connection в Tableau вы видите metrics как fields и dimensions как columns — Tableau native experience, но данные приходят через SL.

Looker

Looker LookML может декларировать metrics через SL:

# В LookML model
connection: dbt_sl_jdbc
explore: orders {
  measure: net_revenue {
    sql: ${'{{TABLE}}'}.net_revenue ;;
    description: "Through dbt SL"
  }
}

Looker calls JDBC, retrieves results. Looker measures уже инициализируется из SL — не нужно дублировать формулы.

Power BI

В Power BI -> Get Data -> JDBC connector -> dbt Cloud SL endpoint. Metrics появляются как fields. DAX measures могут быть проксированы через SL queries.

GraphQL для programmatic access

# Запрос
query {
  query(
    metrics: ["net_revenue", "total_orders"]
    groupBy: ["metric_time__month", "customers__region"]
    where: "{'{{ Dimension(\'customers__country\') }}'} = 'US'"
    orderBy: ["metric_time__month"]
    limit: 100
  ) {
    queryResult {
      schema
      data
      sql
    }
  }
}

Response:

{
  "data": {
    "query": {
      "queryResult": {
        "schema": ["metric_time__month", "customers__region", "net_revenue", "total_orders"],
        "data": [
          ["2026-01-01", "west", 125000.00, 1250],
          ["2026-01-01", "east", 98000.00, 980]
        ],
        "sql": "SELECT DATE_TRUNC('month', order_date), region, ..."
      }
    }
  }
}

sql в response — полезно для debugging: показывает что SL сгенерировал. Можно скопировать в warehouse console для optimize.

GraphQL хорош для web apps, embedded analytics, custom internal tools.

MCP integration для AI tools

В 2026 актуально — AI агенты как consumers SL.

MCP (Model Context Protocol) — protocol для AI tools (Claude, ChatGPT-Enterprise, и т.д.) общаться с external tools. dbt Cloud exposes MCP server для SL access.

// MCP server config (для Claude Desktop)
{
  "mcpServers": {
    "dbt-semantic-layer": {
      "command": "dbt-sl-mcp",
      "env": {
        "DBT_CLOUD_TOKEN": "...",
        "DBT_CLOUD_ENVIRONMENT_ID": "..."
      }
    }
  }
}

После этого пользователь спрашивает Claude в обычном чате:

User: какая выручка в США за Q4 2025 по регионам?

Claude (через MCP):
  -> Tool call: query(metrics=['net_revenue'], group_by=['customers__region'],
                     where="country='US' AND quarter='2025-Q4'")
  -> Получает результат от SL
  -> Отвечает: "Q4 2025 net revenue в США:
              - West: $4.2M
              - East: $3.1M
              - Midwest: $2.1M
              - South: $1.8M"

AI не пишет SQL. Не знает структуру warehouse. Просто spawns tool call с metric request.

Это future-proofing: AI tools становятся стандартными consumers данных, SL — стандартный API для них.

Сравнение API

Когда НЕ нужен Semantic Layer

Мы говорили в первом уроке про cost-benefit. Здесь — более конкретные сигналы что SL вам сейчас не нужен:

1. Один BI tool + одна команда

Если все пользователи метрик в одном Tableau, и одна data team owns dashboards — overhead SL не окупается. Tableau native calculated fields + data sources достаточно.

2. Метрики простые и стабильные

• Только базовые SUM/COUNT, нет ratio/cumulative.
• Бизнес-логика не меняется месяцами.

dbt marts + одна Tableau dashboard = solved.

3. Маленькая команда (менее 10 человек)

Setup cost (2-4 недели), maintenance (10% AE time) — для команды 5-8 человек это значимая доля. ROI слабый.

4. Стартап в exploration phase

Метрики ещё формируются. Business modeli меняется каждый квартал. SL добавляет rigidity, нужна experimentation. Лучше iterate через dbt marts напрямую.

5. Только Python notebooks, нет dashboards

Если все analytics через Python: query SQL напрямую, materialize в pandas/polars, делать своё. SL добавит abstraction overhead без выгоды.

6. Очень специфичные queries

Иногда SL не покрывает edge cases:

• Complex window functions внутри metric formula.
• Pivot tables с dynamic columns.
• Custom UDF аггрегации.

Если 50% queries требуют workarounds — SL мешает, не помогает.

Когда НУЖЕН Semantic Layer

Зеркальная сторона:

1. Multi-BI environment

Tableau + Looker + Power BI в разных командах. Без SL — formula fragmentation гарантирована.

2. Self-service analytics

Бизнес-пользователи (sales, CS, marketing) хотят сами explorating данные. SL даёт безопасный API без learning SQL.

3. AI/ML integration

Claude, ChatGPT, и др. — стандартные consumers. SL — стандартный API.

4. Composite metrics

NRR, churn rate, customer LTV, conversion rates — сложные derived calculations. SL поддерживает композицию.

5. Regulated industries

Finance, healthcare — где каждая метрика должна быть auditable. SL предоставляет audit trail (все queries логированы), version control (через git).

6. Multi-team organization

Финансы хотят revenue. Marketing — customer acquisition. Ops — fulfillment. Без SL каждая команда строит свой mart, метрики разъезжаются.

Migration strategy

Если решили начать с SL:

Phase 1 (1-2 недели): Pilot
- Один semantic_model (например, orders)
- 3-5 metrics (revenue, orders, AOV)
- Tableau JDBC pilot dashboard
- Сравнить cifrы с existing dashboard — должны совпадать

Phase 2 (1 месяц): Expand
- Добавить semantic_models для customers, products
- 10-15 metrics включая ratio и cumulative
- 2-3 dashboard'а через SL

Phase 3 (2-3 месяца): Replace
- Все executive dashboards через SL
- Saved queries для production dashboards
- BI tool legacy queries deprecated

Phase 4 (ongoing): Optimize
- Pre-aggregation через saved queries + exports
- AI integration через MCP
- Self-service for non-data users

Не пытайтесь делать всё сразу. Pilot -> expand -> replace.

Попробуй сам

В вашем dbt-проекте:

1. Установите dbt-sl-client (если есть Cloud account) или используйте CLI:

# Через CLI
dbt sl query --metrics total_orders --group_by metric_time__month

# Через CLI с saved query
dbt sl query-saved monthly_revenue_dashboard

2. Получите compiled SQL:

dbt sl query --metrics total_orders --group_by metric_time__month --explain

3. Через Python (для cloud users):

from dbt_sl_client import SemanticLayerClient
client = SemanticLayerClient(...)
df = client.query(metrics=['total_orders'], group_by=['metric_time__month'])
print(df)

4. Изучите MCP integration:

   • Открываем https://docs.getdbt.com/docs/use-dbt-semantic-layer/sl-mcp
   • Если используете Claude Desktop — можете попробовать MCP server config.

5. Прочитайте обзорный документ по SL integrations:

   • https://docs.getdbt.com/docs/use-dbt-semantic-layer/avail-sl-integrations

Бонус: спроектируйте «pilot SL setup» для воображаемого проекта. 1 semantic_model + 3 metrics + 1 saved query + Tableau integration. Это minimum viable SL.

Ключевые выводы

1. dbt SL имеет 4 API: JDBC (BI tools), GraphQL (web apps), Python SDK (notebooks), MCP (AI tools).
2. JDBC — стандарт для Tableau/Looker/Power BI. Через driver + token. Metrics появляются как native fields.
3. GraphQL — для programmatic access. Возвращает structured JSON + compiled SQL для debugging.
4. Python SDK — dbt_sl_client. Возвращает pandas DataFrame. Идеал для data science workflow.
5. MCP integration — AI tools (Claude, ChatGPT) как consumers SL. Без SQL learning.
6. Когда SL не нужен: 1 BI tool + 1 team + simple metrics + small team + exploration phase + только notebooks + специфичные queries.
7. Когда SL нужен: multi-BI + multi-team + AI integration + composite metrics + self-service + regulated industries.
8. Migration strategy: Pilot (1-2 нед, 1 model + 3-5 metrics) -> Expand (1 мес, full coverage) -> Replace (2-3 мес, deprecate legacy) -> Optimize (ongoing).