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

Запросы к Discovery API

Discovery API поддерживает ad-hoc запросы и интеграции. Если вы впервые работаете с этим API, ознакомьтесь с документом About the Discovery API, где приведено вводное описание.

Используйте Discovery API для оценки состояния конвейеров данных и состояния проекта как на протяжении нескольких запусков, так и в конкретный момент времени. dbt Labs предоставляет стандартный GraphQL explorer для этого API, который позволяет выполнять запросы и просматривать схему. При этом вы также можете использовать любой другой GraphQL-клиент по своему выбору для обращения к API.

Поскольку GraphQL описывает данные, доступные в API, схема, отображаемая в GraphQL explorer, точно отражает граф и поля, доступные для запросов.

Предварительные требования​

Авторизация​

В настоящее время авторизация запросов осуществляется с использованием service token. Пользователи с правами администратора dbt могут сгенерировать service token с типом Metadata Only, который будет авторизован на выполнение конкретного запроса к Discovery API.

После создания токена вы можете использовать его в заголовке Authorization при выполнении запросов к Discovery API dbt. Обязательно указывайте префикс Token в заголовке Authorization, иначе запрос завершится ошибкой 401 Unauthorized. Обратите внимание, что вместо Token в заголовке Authorization можно использовать Bearer. Оба варианта эквивалентны.

Доступ к Discovery API​

  1. Создайте service account token для авторизации запросов. Пользователи с правами администратора dbt могут сгенерировать service token типа Metadata Only, который можно использовать для выполнения конкретного запроса к Discovery API и авторизации запросов.

  2. Определите URL API, который нужно использовать, из таблицы Discovery API endpoints.

  3. Для конкретных точек запроса обратитесь к документации схемы.

Выполнение запросов с помощью HTTP-запросов​

Вы можете выполнять запросы, отправляя POST-запросы к Discovery API, не забыв заменить:

  • YOUR_API_URL на соответствующий Discovery API endpoint для вашего региона и тарифного плана.

  • YOUR_TOKEN в заголовке Authorization на ваш реальный API-токен. Обязательно указывайте префикс Token.

  • QUERY_BODY на GraphQL-запрос, например { "query": "<query text>", "variables": "<variables in json>" }

  • VARIABLES на словарь с переменными вашего GraphQL-запроса, например ID job или фильтр.

  • ENDPOINT на endpoint, к которому вы обращаетесь, например environment.

    curl 'YOUR_API_URL' \
      -H 'authorization: Bearer YOUR_TOKEN' \
      -H 'content-type: application/json'
      -X POST
      --data QUERY_BODY

Пример на Python:

response = requests.post(
    'YOUR_API_URL',
    headers={"authorization": "Bearer "+YOUR_TOKEN, "content-type": "application/json"},
    json={"query": QUERY_BODY, "variables": VARIABLES}
)

metadata = response.json()['data'][ENDPOINT]

Каждый запрос требует указания ID environment или ID job. Вы можете получить этот ID из URL dbt или с помощью Admin API.

На этой странице приведено несколько наглядных примеров запросов. Дополнительные примеры см. в разделе Use cases and examples for the Discovery API.

Discovery API endpoints​

Ниже приведены endpoints для доступа к Discovery API. Используйте тот, который соответствует вашему региону и тарифному плану.

Deployment typeDiscovery API URL
North America multi-tenanthttps://metadata.cloud.getdbt.com/graphql
EMEA multi-tenanthttps://metadata.emea.dbt.com/graphql
APAC multi-tenanthttps://metadata.au.dbt.com/graphql
Multi-cellhttps://YOUR_ACCOUNT_PREFIX.metadata.REGION.dbt.com/graphql

Замените YOUR_ACCOUNT_PREFIX на идентификатор вашего аккаунта, а REGION — на ваш регион, например us1.dbt.com.
Single-tenanthttps://metadata.YOUR_ACCESS_URL/graphql

Замените YOUR_ACCESS_URL на префикс вашего аккаунта с соответствующим Access URL для вашего региона и тарифного плана.
Loading table...

Разумное использование​

Использование Discovery (GraphQL) API ограничено лимитами на частоту запросов и размер ответов, чтобы поддерживать производительность и стабильность платформы метаданных и предотвращать злоупотребления.

Endpoints уровня job подчиняются ограничениям на сложность запросов. Вложенные узлы (например, parents), код (например, rawCode) и колонки каталога считаются наиболее сложными. Слишком сложные запросы рекомендуется разбивать на несколько отдельных запросов, включая только необходимые поля. dbt Labs рекомендует в большинстве случаев использовать endpoint environment, чтобы получать актуальные описательные и результатные метаданные для проекта dbt.

Ограничения хранения данных​

Вы можете использовать Discovery API для запросов данных за последние два месяца. Например, если сегодня 1 апреля, вы сможете запрашивать данные начиная с 1 февраля.

Выполнение запросов с помощью GraphQL explorer​

Вы можете выполнять ad-hoc запросы напрямую в GraphQL API explorer и использовать document explorer в левой части экрана, чтобы увидеть все доступные узлы и поля.

Информацию о настройке и авторизации GraphQL см. в документации Apollo explorer.

  1. Откройте GraphQL API explorer и выберите поля, которые вы хотите запросить.

  2. Внизу explorer выберите Variables и замените все поля со значением null на ваши уникальные значения.

  3. Аутентифицируйтесь, используя Bearer auth с YOUR_TOKEN. Внизу explorer выберите Headers и нажмите +New header.

  4. В выпадающем списке header key выберите Authorization и в поле value укажите ваш Bearer-токен. Не забудьте включить префикс Token. Заголовок должен иметь формат: {"Authorization": "Bearer <YOUR_TOKEN>}.


Введите значения header key и Bearer auth tokenВведите значения header key и Bearer auth token
  1. Запустите запрос, нажав синюю кнопку выполнения запроса в правом верхнем углу редактора Operation (справа от запроса). Справа в explorer вы должны увидеть успешный ответ на запрос.
Выполнение запросов с помощью Apollo Server GraphQL explorerВыполнение запросов с помощью Apollo Server GraphQL explorer

Фрагменты​

Используйте нотацию ... on для выполнения запросов по lineage и получения результатов для конкретных типов узлов.

query ($environmentId: BigInt!, $first: Int!) {
  environment(id: $environmentId) {
    applied {
      models(first: $first, filter: { uniqueIds: "MODEL.PROJECT.MODEL_NAME" }) {
        edges {
          node {
            name
            ancestors(types: [Model, Source, Seed, Snapshot]) {
              ... on ModelAppliedStateNestedNode {
                name
                resourceType
                materializedType
                executionInfo {
                  executeCompletedAt
                }
              }
              ... on SourceAppliedStateNestedNode {
                sourceName
                name
                resourceType
                freshness {
                  maxLoadedAt
                }
              }
              ... on SnapshotAppliedStateNestedNode {
                name
                resourceType
                executionInfo {
                  executeCompletedAt
                }
              }
              ... on SeedAppliedStateNestedNode {
                name
                resourceType
                executionInfo {
                  executeCompletedAt
                }
              }
            }
          }
        }
      }
    }
  }
}

Пагинация​

Запросы к большим наборам данных могут негативно влиять на производительность различных частей API. Пагинация снижает нагрузку, возвращая данные небольшими порциями — по одной странице за раз. Это полезно для получения как части набора данных, так и всего набора поэтапно, что улучшает производительность. dbt использует курсорную пагинацию, которая упрощает работу с постоянно изменяющимися данными.

Используйте объект PageInfo, чтобы получить информацию о странице. Доступные поля:

  • startCursor тип string — соответствует первому node в edge.
  • endCursor тип string — соответствует последнему node в edge.
  • hasNextPage тип boolean — указывает, есть ли дополнительные nodes после возвращённых результатов.

При выполнении запроса доступны следующие переменные соединения:

  • first тип integer — возвращает первые n nodes на странице, максимум 500.
  • after тип string — задаёт курсор, после которого нужно вернуть nodes. Рекомендуется указывать значение after, используя ID объекта из endCursor предыдущей страницы.

Ниже приведён пример, который возвращает первые 500 моделей (first) после указанного Object ID (after) в переменных. Объект PageInfo показывает, с какого Object ID начинается курсор, где он заканчивается и есть ли следующая страница.

Пример пагинацииПример пагинации

Ниже приведён пример кода для объекта PageInfo:

pageInfo {
  startCursor
  endCursor
  hasNextPage
}
totalCount # Total number of records across all pages

Фильтры​

Фильтрация помогает сузить результаты API-запроса. Например, если вы хотите получить только модели и тесты с ошибками или найти модели, которые выполняются слишком долго, вы можете запросить такие детали выполнения, как executionTime, runElapsedTime или status. Это помогает командам данных отслеживать производительность моделей, выявлять узкие места и оптимизировать общий конвейер данных.

Ниже приведён пример фильтрации результатов для моделей, которые успешно выполнились по значению lastRunStatus:

Пример фильтрацииПример фильтрации

Ниже приведён пример фильтрации моделей с ошибкой на последнем запуске и тестов, которые завершились с ошибкой:

query ModelsAndTests($environmentId: BigInt!, $first: Int!) {
  environment(id: $environmentId) {
    applied {
      models(first: $first, filter: { lastRunStatus: error }) {
        edges {
          node {
            name
            executionInfo {
              lastRunId
            }
          }
        }
      }
      tests(first: $first, filter: { status: "fail" }) {
        edges {
          node {
            name
            executionInfo {
              lastRunId
            }
          }
        }
      }
    }
  }
}

Связанные материалы​

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

0
Loading