Перейти к основному содержимому

Python SDK StarterEnterpriseEnterprise +

dbt-sl-sdk Python software development kit (SDK) — это Python‑библиотека, которая предоставляет удобный доступ к dbt Semantic Layer из Python. Она позволяет разработчикам взаимодействовать с API dbt Semantic Layer и запрашивать метрики и измерения (dimensions) в downstream‑инструментах.

Установка​

Для установки Python SDK вам нужно указать дополнительные зависимости в зависимости от того, хотите ли вы использовать его синхронно, с поддержкой requests, или асинхронно (asyncio с поддержкой aiohttp).

Python SDK поддерживает версии Python с долгосрочной поддержкой (LTS), такие как 3.9, 3.10, 3.11 и 3.12. Когда Python прекращает поддержку версии, Python SDK также прекращает поддержку этой версии. Если вы используете неподдерживаемую версию, вы можете столкнуться с проблемами совместимости и не получите обновления или исправления безопасности от SDK.

Синхронная установка означает, что ваша программа ждет завершения каждой задачи перед переходом к следующей.

Это проще, легче для понимания и подходит для небольших задач или когда вашей программе не нужно обрабатывать много задач одновременно.

pip install "dbt-sl-sdk[sync]"

Если вы используете асинхронные фреймворки, такие как FastAPI или Strawberry, установка синхронной версии SDK заблокирует ваш цикл событий и может значительно замедлить вашу программу. В этом случае мы настоятельно рекомендуем использовать асинхронную установку.

Использование​

Чтобы выполнять операции с API Semantic Layer, необходимо создать (инициализировать) экземпляр SemanticLayerClient, указав ваши конкретные параметры подключения к API:

from dbtsl import SemanticLayerClient

client = SemanticLayerClient(
    environment_id=123,
    auth_token="<your-semantic-layer-api-token>",
    host="semantic-layer.cloud.getdbt.com",
)

# запрос первой метрики по `metric_time`
def main():
    with client.session():
        metrics = client.metrics()
        table = client.query(
            metrics=[metrics[0].name],
            group_by=["metric_time"],
        )
        print(table)

main()

Примечание: Все вызовы методов, обращающихся к API, должны находиться в контексте client.session(). Это позволяет клиенту установить соединение с API только один раз и повторно использовать то же соединение между вызовами API.

Мы рекомендуем создавать сессию на уровне всего приложения и повторно использовать ту же сессию в течение всего приложения для оптимальной производительности. Создание сессии для каждого запроса не рекомендуется и неэффективно.

Использование asyncio​

Если вы используете asyncio, импортируйте AsyncSemanticLayerClient из dbtsl.asyncio. API SemanticLayerClient и AsyncSemanticLayerClient идентичны, но асинхронная версия имеет асинхронные методы, которые нужно await.

import asyncio
from dbtsl.asyncio import AsyncSemanticLayerClient

client = AsyncSemanticLayerClient(
    environment_id=123,
    auth_token="<your-semantic-layer-api-token>",
    host="semantic-layer.cloud.getdbt.com",
)

async def main():
    async with client.session():
        metrics = await client.metrics()
        table = await client.query(
            metrics=[metrics[0].name],
            group_by=["metric_time"],
        )
        print(table)

asyncio.run(main())

Ленивaя загрузка для больших полей​

По умолчанию Python SDK жадно загружает вложенные списки объектов, такие как dimensions, entities и measures, для каждого объекта Metric — даже если они вам не нужны. В большинстве случаев это удобно, но в крупных проектах может приводить к более медленным ответам из‑за большого объёма возвращаемых данных.

Чтобы повысить производительность, вы можете включить ленивую загрузку, передав lazy=True при создании клиента. При включённой ленивой загрузке SDK пропускает получение крупных вложенных полей до тех пор, пока вы явно не запросите их для конкретной модели.

В настоящее время ленивая загрузка поддерживается только для полей dimensions, entities и measures у объектов Metric.

Например, следующий код получает все доступные метрики из Metadata API и выводит только измерения (dimensions) для некоторых метрик:

list_metrics_lazy_sync.py
"""Fetch all available metrics from the metadata API and display only the dimensions of certain metrics."""

from argparse import ArgumentParser

from dbtsl import SemanticLayerClient


def get_arg_parser() -> ArgumentParser:
    p = ArgumentParser()

    p.add_argument("--env-id", required=True, help="The dbt environment ID", type=int)
    p.add_argument("--token", required=True, help="The API auth token")
    p.add_argument("--host", required=True, help="The API host")

    return p


def main() -> None:
    arg_parser = get_arg_parser()
    args = arg_parser.parse_args()

    client = SemanticLayerClient(
        environment_id=args.env_id,
        auth_token=args.token,
        host=args.host,
        lazy=True,
    )

    with client.session():
        metrics = client.metrics()
        for i, m in enumerate(metrics):
            print(f"📈 {m.name}")
            print(f"     type={m.type}")
            print(f"     description={m.description}")

            assert len(m.dimensions) == 0

            # skip if index is odd
            if i & 1:
                print("     dimensions=skipped")
                continue

            # load dimensions only if index is even
            m.load_dimensions()

            print("     dimensions=[")
            for dim in m.dimensions:
                print(f"        {dim.name},")
            print("     ]")


if __name__ == "__main__":
    main()

Подробнее см. в примере с ленивой загрузкой.

Интеграция с библиотеками для работы с датафреймами​

Python SDK возвращает все данные запросов в виде таблиц pyarrow.

Библиотека Python SDK не поставляется в комплекте с Polars или Pandas. Если вы используете эти библиотеки, добавьте их в зависимости вашего проекта.

Чтобы использовать данные с такими библиотеками, как Polars или Pandas, вручную преобразуйте данные в нужный формат. Например:

Если вы используете pandas​

# ... инициализация клиента

arrow_table = client.query(...)
pandas_df = arrow_table.to_pandas()

Если вы используете polars​

import polars as pl

# ... инициализация клиента

arrow_table = client.query(...)
polars_df = pl.from_arrow(arrow_table)

Примеры использования​

Для дополнительных примеров использования ознакомьтесь с примерами использования, некоторые из которых включают:

Отключение телеметрии​

По умолчанию, Python SDK отправляет некоторую информацию о платформе в dbt Labs. Чтобы отказаться от этого, установите атрибут PLATFORM.anonymous в True:

from dbtsl.env import PLATFORM
PLATFORM.anonymous = True

# ... инициализация клиента

Вклад​

Чтобы внести вклад в этот проект, ознакомьтесь с нашими руководствами по вкладу и откройте GitHub issue или pull request.

Нашли ошибку?

0
Loading