JDBC

Java Database Connectivity (JDBC) API семантического слоя dbt позволяет пользователям выполнять запросы к метрикам и измерениям с использованием протокола JDBC, а также предоставляет стандартную функциональность метаданных.

JDBC-драйвер — это программный компонент, позволяющий Java-приложению взаимодействовать с платформой данных. Вот дополнительная информация о нашем JDBC API:

• JDBC API семантического слоя использует open-source JDBC-драйвер с протоколом ArrowFlight SQL.
• Вы можете скачать JDBC-драйвер с Maven.
• Семантический слой dbt поддерживает драйвер ArrowFlight SQL версии 12.0.0 и выше.
• Вы можете встроить драйвер в ваш стек приложений по мере необходимости и использовать пример проекта от dbt Labs в качестве справки.
• Если вы являетесь партнером или пользователем, создающим собственное приложение, вам потребуется установить корневой сертификат AWS в Java Trust документацию (специфично для Java и JDBC вызовов).

Партнеры dbt Labs могут использовать JDBC API для создания интеграций в своих инструментах с семантическим слоем dbt.

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

Если вы являетесь пользователем dbt или партнером с доступом к dbt Cloud и семантическому слою dbt, вы можете настроить и протестировать этот API с данными из вашей собственной инстанции, настроив семантический слой и получив правильные параметры подключения JDBC, описанные в этом документе.

Вы можете использовать наш JDBC API с инструментами, которые не имеют официальной интеграции с семантическим слоем dbt. Если ваш инструмент позволяет вам писать SQL и поддерживает опцию универсального JDBC-драйвера (например, DataGrip) или поддерживает Dremio и использует драйвер ArrowFlightSQL версии 12.0.0 или выше, вы можете получить доступ к API семантического слоя.

Обратитесь к Начало работы с семантическим слоем dbt для получения дополнительной информации.

Обратите внимание, что API семантического слоя dbt не поддерживает ref для вызова объектов dbt. Вместо этого используйте полное квалифицированное имя таблицы. Если вы используете макросы dbt во время выполнения запроса для расчета ваших метрик, вы должны перенести эти вычисления в определения метрик вашего семантического слоя в виде кода.

Аутентификация

dbt Cloud авторизует запросы к API семантического слоя dbt. Вам необходимо предоставить ID окружения, хост и токены учетной записи сервиса.

Параметры подключения

Подключение JDBC требует нескольких различных параметров подключения.

Вот пример строки подключения URL и отдельных компонентов:

jdbc:arrow-flight-sql://semantic-layer.cloud.getdbt.com:443?&environmentId=202339&token=SERVICE_TOKEN

Параметр JDBC	Описание	Пример
jdbc:arrow-flight-sql://	Протокол для JDBC-драйвера.	jdbc:arrow-flight-sql://
semantic-layer.cloud.getdbt.com	URL доступа для региона вашего аккаунта в dbt Cloud. Вы всегда должны добавлять префикс semantic-layer перед URL доступа.	Для развертывания dbt Cloud, размещенного в Северной Америке, используйте semantic-layer.cloud.getdbt.com
environmentId	Уникальный идентификатор для производственного окружения dbt, вы можете получить его из URL dbt Cloud при переходе в Environments под Deploy.	Если ваш URL заканчивается на .../environments/222222, ваш environmentId — 222222
SERVICE_TOKEN	Токен сервиса dbt Cloud с разрешениями "Только семантический слой" и "Только метаданные". Создайте новый токен сервиса на странице Account Settings.	token=SERVICE_TOKEN

*Примечание — Если вы тестируете локально на инструменте, таком как DataGrip, вам также может потребоваться предоставить следующую переменную в конце или начале URL JDBC &disableCertificateVerification=true.

Запрос API для метаданных метрик

JDBC API семантического слоя имеет встроенные вызовы метаданных, которые могут предоставить пользователю информацию о его метриках и измерениях.

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

 Получить определенные метрики

Вы можете использовать этот запрос для получения всех определенных метрик в вашем проекте dbt:

select * from {{ 
	semantic_layer.metrics() 
}}

 Получить измерения для метрики

Вы можете использовать этот запрос для получения всех измерений для метрики.

Обратите внимание, что метрики — это обязательный аргумент, который перечисляет одну или несколько метрик.

select * from {{ 
    semantic_layer.dimensions(metrics=['food_order_amount'])}}

 Получить значения измерений

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

Обратите внимание, что метрики — это обязательный аргумент, который перечисляет одну или несколько метрик, и одно измерение.

select * from {{ 
semantic_layer.dimension_values(metrics=['food_order_amount'], group_by=['customer__customer_name'])}}

 Получить гранулярности для метрик

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

Этот запрос API позволяет вам показывать только те временные гранулярности, которые имеют смысл для основной временной размерности метрик (например, metric_time), но если вы хотите получить доступные гранулярности для других временных размерностей, вы можете использовать вызов dimensions() и найти столбец queryable_granularities.

Обратите внимание, что метрики — это обязательный аргумент, который перечисляет одну или несколько метрик.

select * from {{
    semantic_layer.queryable_granularities(metrics=['food_order_amount', 'order_gross_profit'])}}

 Получить доступные метрики для заданных измерений

Вы можете использовать этот запрос для получения доступных метрик для заданных измерений. Эта команда по сути является противоположностью получения измерений для списка метрик.

Обратите внимание, что group_by — это обязательный аргумент, который перечисляет одно или несколько измерений.

select * from {{
    semantic_layer.metrics_for_dimensions(group_by=['customer__customer_type'])
}}

 Получить гранулярности для всех временных измерений

Вы можете использовать этот пример запроса для получения доступных гранулярностей для всех временных измерений (аналогичный вызов API queryable granularities возвращает только гранулярности для основных временных измерений для метрик).

Следующий вызов является производным от вызова dimensions() и специально выбирает поле гранулярности.

select NAME, QUERYABLE_GRANULARITIES from {{
    semantic_layer.dimensions(
        metrics=["order_total"]
    )
}}

 Получить имена основных временных измерений

В вашем приложении может быть полезно отображать имена временных измерений, которые представляют metric_time или общую нить для всех метрик.

Сначала вы можете выполнить запрос аргумента metrics() для получения списка мер, затем использовать вызов measures(), который вернет имя(а) временных измерений, составляющих metric_time.

select * from {{
    semantic_layer.measures(metrics=['orders'])
}}

 Получить метрики по поиску подстроки

Вы можете отфильтровать ваши метрики, чтобы включить только те, которые содержат определенную подстроку (последовательность символов, содержащаяся в более длинной строке (тексте)). Используйте аргумент search, чтобы указать подстроку, которую вы хотите сопоставить.

select * from {{ semantic_layer.metrics(search='order') }}

Если подстрока не указана, запрос возвращает все метрики.

 Пагинация вызовов метаданных

В случае, если вы не хотите возвращать полный набор результатов из вызова метаданных, вы можете разбить результаты на страницы как для вызовов semantic_layer.metrics(), так и для semantic_layer.dimensions() с использованием параметров page_size и page_number.

• page_size: Это необязательная переменная, которая устанавливает количество записей на странице. Если оставить None, ограничения на количество страниц нет.
• page_number: Это необязательная переменная, которая указывает номер страницы для получения. По умолчанию 1 (первая страница), если не указано.

Примеры:

-- Получает 5-ю страницу с размером страницы 10 метрик
select * from {{ semantic_layer.metrics(page_size=10, page_number=5) }}

-- Получает 1-ю страницу с размером страницы 10 метрик
select * from {{ semantic_layer.metrics(page_size=10) }}

-- Получает все метрики без пагинации
select * from {{ semantic_layer.metrics() }}

Вы можете использовать те же параметры пагинации для semantic_layer.dimensions(...).

 Список сохраненных запросов

Вы можете использовать этот пример запроса, чтобы перечислить все доступные сохраненные запросы в вашем проекте dbt.

Команда

select * from semantic_layer.saved_queries()

Вывод

| NAME | DESCRIPTION | LABEL | METRICS | GROUP_BY | WHERE_FILTER |

Запрос API для значений метрик

Для запроса значений метрик доступны следующие параметры. Ваш запрос должен иметь либо параметр metric, либо параметр group_by, чтобы быть действительным.

Параметр	Описание	Пример
metrics	Имя метрики, как определено в вашей конфигурации метрик dbt	metrics=['revenue']
group_by	Имена измерений или сущностей для группировки. Мы требуем ссылки на сущность измерения (кроме основной временной размерности), которая добавляется перед именем измерения с двойным подчеркиванием.	group_by=['user__country', 'metric_time']
grain	Параметр, специфичный для любой временной размерности, изменяющий гранулярность данных по умолчанию для метрики.	group_by=[Dimension('metric_time') grain('week|day|month|quarter|year')]
where	Условие where, позволяющее фильтровать по измерениям и сущностям с использованием параметров. Это принимает список фильтров ИЛИ строку. Входные данные поставляются с объектами Dimension и Entity. Гранулярность требуется, если Dimension является временной размерностью	"{{ where=Dimension('customer__country') }} = 'US')"
limit	Ограничение на возвращаемые данные	limit=10
order	Упорядочивание возвращаемых данных по определенному полю	order_by=['order_gross_profit'], используйте - для убывания, или полную нотацию объекта, если объект подвергается операции: order_by=[Metric('order_gross_profit').descending(True)]
compile	Если true, возвращает сгенерированный SQL для платформы данных, но не выполняет его	compile=True
saved_query	Сохраненный запрос, который вы можете использовать для часто используемых запросов.	select * from {{ semantic_layer.query(saved_query="new_customer_orders"

Примечание о временных измерениях и metric_time

Вы заметите, что в списке измерений для всех метрик есть измерение под названием metric_time. Metric_time — это зарезервированное ключевое слово для временных измерений агрегации, специфичных для меры. Для любой временной метрики ключевое слово metric_time всегда должно быть доступно для использования в запросах. Это общее измерение для всех метрик в семантическом графе.

Вы можете рассматривать одну метрику или сотни метрик, и если вы группируете по metric_time, это всегда даст вам правильный временной ряд.

Кроме того, при выполнении расчетов гранулярности, которые являются глобальными (не специфичными для конкретного временного измерения), мы рекомендуем всегда работать с metric_time, и вы получите правильный ответ.

Обратите внимание, что metric_time должен быть доступен в дополнение к любым другим временным измерениям, доступным для метрики(ов). В случае, если вы рассматриваете одну метрику (или несколько метрик из одного источника данных), значения в серии для основной временной размерности и metric_time эквивалентны.

Примеры

Обратитесь к следующим примерам, чтобы помочь вам начать работу с JDBC API.

Получить метаданные для метрик

Вы можете фильтровать/добавлять любой SQL вне синтаксиса шаблонизации. Например, вы можете использовать следующий запрос для получения имени и измерений для метрики:

select name, dimensions from {{ 
	semantic_layer.metrics() 
	}}
	WHERE name='food_order_amount'

Запрос общих измерений

Вы можете выбрать общие измерения для нескольких метрик. Используйте следующий запрос для получения имени и измерений для нескольких метрик:

select * from {{ 
	semantic_layer.dimensions(metrics=['food_order_amount', 'order_gross_profit'])
	}}

Запрос с группировкой по времени

Следующий пример запроса использует сокращенный метод для получения дохода и новых клиентов с группировкой по времени:

select * from {{
	semantic_layer.query(metrics=['food_order_amount','order_gross_profit'], 
	group_by=['metric_time'])
	}}

Запрос с временной гранулярностью

Используйте следующий пример запроса для получения нескольких метрик с изменением гранулярности временной размерности:

select * from {{
	semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], 
	group_by=[Dimension('metric_time').grain('month')])
	}}

Группировка по категориальному измерению

Используйте следующий запрос для группировки по категориальному измерению:

select * from {{
	semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'], 
	group_by=[Dimension('metric_time').grain('month'), 'customer__customer_type'])
	}}

Запрос только измерения

В этом случае вы получите полный список значений измерений для выбранного измерения.

select * from {{
    semantic_layer.query(group_by=['customer__customer_type'])
                  }}

Запрос с фильтрами where

Фильтры where в API позволяют использовать список фильтров или строку. Мы рекомендуем использовать список фильтров для производственных приложений, так как этот формат реализует все преимущества там, где это возможно.

Фильтры Where имеют несколько объектов, которые вы можете использовать:

• Dimension() — Используется для любых категориальных или временных измерений. Dimension('metric_time').grain('week') или Dimension('customer__country').

• TimeDimension() — Используется как более явное определение для временных измерений, опционально принимает гранулярность TimeDimension('metric_time', 'month').

• Entity() — Используется для сущностей, таких как первичные и внешние ключи - Entity('order_id').

Для TimeDimension() гранулярность требуется в фильтре WHERE только в том случае, если временные измерения агрегации для мер и метрик, связанных с фильтром where, имеют разные гранулярности.

Например, рассмотрим эту конфигурацию семантической модели и метрики, которая содержит две метрики, агрегированные по разным временным гранулярностям. Этот пример показывает одну семантическую модель, но то же самое относится к метрикам в более чем одной семантической модели.

semantic_model:
  name: my_model_source

defaults:
  agg_time_dimension: created_month
  measures:
    - name: measure_0
      agg: sum
    - name: measure_1
      agg: sum
      agg_time_dimension: order_year
  dimensions:
    - name: created_month
      type: time
      type_params:
        time_granularity: month
    - name: order_year
      type: time
      type_params:
        time_granularity: year

metrics:
  - name: metric_0
    description: Метрика с месячной гранулярностью.
    type: simple
    type_params:
      measure: measure_0
  - name: metric_1
    description: Метрика с годовой гранулярностью.
    type: simple
    type_params:
      measure: measure_1

Предположим, пользователь запрашивает metric_0 и metric_1 вместе в одном запросе, допустимый фильтр WHERE будет:

• "{{ TimeDimension('metric_time', 'year') }} > '2020-01-01'"

Недопустимые фильтры будут:

• "{{ TimeDimension('metric_time') }} > '2020-01-01'" — метрики в запросе определены на основе мер с разными гранулярностями.

• "{{ TimeDimension('metric_time', 'month') }} > '2020-01-01'" — metric_1 недоступна на месячной гранулярности.

• Используйте следующий пример для запроса с использованием фильтра where в строковом формате:

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'],
where="{{ Dimension('metric_time').grain('month')  }} >= '2017-03-09' AND {{ Dimension('customer__customer_type' }} in ('new') AND {{ Entity('order_id') }} = 10")
}}

• (Рекомендуется для лучшей производительности) Используйте следующий пример для запроса с использованием фильтра where в формате списка фильтров:

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'],
where=["{{ Dimension('metric_time').grain('month') }} >= '2017-03-09'", "{{ Dimension('customer__customer_type') }} in ('new')", "{{ Entity('order_id') }} = 10"])
}}

Запрос с ограничением

Используйте следующий пример для запроса с использованием limit или order_by:

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
  group_by=[Dimension('metric_time')],
  limit=10)
  }}

Запрос с примерами Order By

Order By может принимать простую строку, которая является Dimension, Metric или Entity, и по умолчанию будет использовать порядок по возрастанию

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
  group_by=[Dimension('metric_time')],
  limit=10,
  order_by=['order_gross_profit'])
  }}

Для убывающего порядка вы можете добавить знак - перед объектом. Однако вы можете использовать эту сокращенную нотацию только в том случае, если вы не выполняете операции над объектом или используете полную нотацию объекта.

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
  group_by=[Dimension('metric_time')],
  limit=10,
  order_by=['-order_gross_profit'])
  }}

Если вы упорядочиваете по объекту, который подвергся операции (например, вы изменили гранулярность временной размерности), или вы используете полную нотацию объекта, убывающий порядок должен выглядеть так:

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
  group_by=[Dimension('metric_time').grain('week')],
  limit=10,
  order_by=[Metric('order_gross_profit').descending(True), Dimension('metric_time').grain('week').descending(True) ])
  }}

Аналогично, это приведет к порядку по возрастанию:

select * from {{
semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
  group_by=[Dimension('metric_time').grain('week')],
  limit=10,
  order_by=[Metric('order_gross_profit'), Dimension('metric_time').grain('week')])
  }}

Запрос с ключевым словом compile

• Используйте следующий пример для запроса с использованием ключевого слова compile:

  select * from {{
  semantic_layer.query(metrics=['food_order_amount', 'order_gross_profit'],
      group_by=[Dimension('metric_time').grain('month'),'customer__customer_type'],
      compile=True)
      }}

• Используйте следующий пример для компиляции SQL с сохраненным запросом. Вы можете использовать это для часто используемых запросов.

  select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5, compile=True}}

Примечание о запросе сохраненных запросов

При запросе сохраненных запросов вы можете использовать такие параметры, как where, limit, order, compile и так далее. Однако имейте в виду, что вы не можете получить доступ к параметрам metric или group_by в этом контексте. Это связано с тем, что они являются предопределенными и фиксированными параметрами для сохраненных запросов, и вы не можете изменить их во время выполнения запроса. Если вы хотите запросить больше метрик или измерений, вы можете построить запрос, используя стандартный формат.

Запрос сохраненного запроса

Используйте следующий пример для запроса сохраненного запроса:

select * from {{ semantic_layer.query(saved_query="new_customer_orders", limit=5}}

JDBC API будет использовать сохраненный запрос (new_customer_orders) как определено и применит ограничение в 5 записей.

Многозвенные соединения

В случаях, когда вам нужно выполнить запрос через несколько связанных таблиц (многозвенные соединения), используйте аргумент entity_path, чтобы указать путь между связанными сущностями. Вот примеры того, как вы можете определить эти соединения:

• В этом примере вы запрашиваете измерение location_name, но указываете, что оно должно быть соединено с использованием поля order_id.

  {{Dimension('location__location_name', entity_path=['order_id'])}}
• В этом примере измерение salesforce_account_owner соединено с полем region, с путем, проходящим через salesforce_account.

  {{ Dimension('salesforce_account_owner__region',['salesforce_account']) }}

Часто задаваемые вопросы

Я получаю ошибку `Failed ALPN` при попытке подключиться к семантическому слою dbt.

Если вы получаете ошибку Failed ALPN при попытке подключиться к семантическому слою dbt с помощью различных инструментов интеграции данных (таких как Tableau, DBeaver, Datagrip, ADBC или JDBC), это обычно происходит при подключении с компьютера, находящегося за корпоративным VPN или прокси (например, Zscaler или Check Point).

Основная причина заключается в том, что прокси мешает выполнению TLS рукопожатия, так как семантический слой dbt использует gRPC/HTTP2 для подключения. Чтобы решить эту проблему:

• Если ваш прокси поддерживает gRPC/HTTP2, но не настроен на разрешение ALPN, измените его настройки, чтобы разрешить ALPN. Или создайте исключение для домена dbt Cloud.
• Если ваш прокси не поддерживает gRPC/HTTP2, добавьте исключение для перехвата SSL для домена dbt Cloud в настройках вашего прокси.

Это должно помочь успешно установить соединение без ошибки Failed ALPN.

 Почему некоторые измерения используют разный синтаксис, например, `metric_time` против `Dimension('metric_time')`?

Когда вы выбираете измерение само по себе, например, metric_time, вы можете использовать сокращенный метод, который не требует синтаксиса “Dimension”.

Однако, когда вы выполняете операции над измерением, такие как добавление гранулярности, требуется объектный синтаксис [Dimension('metric_time').

 Что означает синтаксис двойного подчеркивания `'__'` в измерениях?

Синтаксис двойного подчеркивания "__" указывает на отображение от сущности к измерению, а также на то, где находится измерение. Например, user__country означает, что кто-то смотрит на измерение country из таблицы user.

 Каков формат вывода по умолчанию при добавлении гранулярности?

Формат вывода по умолчанию следует формату {{time_dimension_name}__{granularity_level}}.

Так, например, если time_dimension_name — это ds, а уровень гранулярности — годовой, вывод будет ds__year.

Связанные документы

• Лучшие практики интеграции семантического слоя dbt