Metabase

Metabase — это инструмент бизнес-аналитики с открытым исходным кодом, который поддерживает анализ и визуализацию данных, интерактивные дашборды, детализацию данных, редактирование SQL-запросов и экспорт данных. С помощью Metabase Apache Doris Driver можно подключать базы данных и таблицы Apache Doris к Metabase в качестве источников данных, выполнять запросы к внутренним и внешним данным Doris и создавать дашборды с визуализациями.

Это отдельный драйвер сообщества Metabase, который не входит в состав Metabase.

В этой статье рассматриваются пользовательские сценарии и описывается, как выполнить следующие операции:

Сценарий	Цель пользователя	Основные операции
Подготовка среды Metabase	Обеспечить распознавание Apache Doris в Metabase как источника данных	Установить Metabase, затем скачать и установить драйвер Doris
Настройка источника данных Doris	Подключиться к базе данных Doris tpch в Metabase	Указать узел FE, Query Port, Catalog, базу данных, имя пользователя и пароль
Создание аналитических визуализаций	Проанализировать, как со временем меняются суммы заказов с разными способами доставки	Создать вопрос, написать SQL, настроить линейный график и сохранить его на дашборде
Использование расширенных возможностей	Получить доступ к внешним источникам данных и повысить удобство работы с запросами	Использовать Catalog, параметризованные запросы, отсечение секций, материализованные представления и кэширование

Подготовка среды Metabase

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

Перед началом настройки убедитесь, что среда соответствует следующим требованиям:

Компонент	Требование
Metabase	Скачайте и установите Metabase 0.59.6.3 или более поздней версии. Инструкции по установке см. в документации по установке Metabase
Java	Для запуска Metabase требуется Java 21
Apache Doris	Подготовьте доступный кластер Apache Doris
Драйвер Doris	Скачайте Metabase Doris Driver

Скачивание и проверка драйвера

предупреждение

Metabase Doris Driver предоставляется и поддерживается сторонним разработчиком. Он не является частью проекта Apache Doris, не выпускается сообществом Apache Doris и не имеет его официального одобрения. Перед использованием драйвера в рабочей среде самостоятельно оцените его пригодность, проверьте контрольную сумму скачанного файла и соблюдайте условия лицензии стороннего проекта. Об обнаруженных проблемах с драйвером сообщайте в проект, который его предоставляет.

Скачайте JAR-файл релиза и файл с его контрольной суммой:

curl -LO https://github.com/velodb/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar
curl -LO https://github.com/velodb/metabase-doris-driver/releases/download/v1.0.0/doris.metabase-driver-v1.0.0.jar.sha256
sha256sum -c doris.metabase-driver-v1.0.0.jar.sha256

Ожидаемое значение SHA-256:

b23e82f19a7f9226343e42566e1e192b6df7a0dfc48a73d2101fc74bfec243f3

Установка драйвера при обычном развёртывании

Если Metabase развёрнут обычным способом, установите драйвер Doris следующим образом:

1. Скачайте и проверьте файлы релиза драйвера, как описано выше.

2. Если каталог плагинов Metabase отсутствует, создайте его:

   mkdir -p /path/to/metabase/plugins

3. Скопируйте JAR-файл релиза в каталог плагинов:

   cp doris.metabase-driver-v1.0.0.jar /path/to/metabase/plugins/doris.metabase-driver.jar

4. Перезапустите службу Metabase.

5. Проверьте журнал запуска Metabase и убедитесь, что драйвер doris зарегистрирован. В разделе Настройки администратора > Базы данных > Добавить базу данных должен появиться тип базы данных Apache Doris.

Установка драйвера при развёртывании в Docker

Если вы запускаете Metabase в Docker, рекомендуется подключить doris.metabase-driver.jar с помощью монтирования. Путь к плагинам внутри контейнера Docker — /plugins/.

1. Скачайте и проверьте файлы релиза драйвера.

2. Запустите контейнер с образом Metabase, который соответствует предварительным требованиям:

   docker run -d \
     -p 3000:3000 \
     --name metabase \
     -v "$(pwd)/doris.metabase-driver-v1.0.0.jar:/plugins/doris.metabase-driver.jar:ro" \
     metabase/metabase

Настройка источника данных Doris

После установки Metabase и metabase-doris-driver вы можете добавить в Metabase источник данных для подключения к базе данных Doris tpch.

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

При подключении к Apache Doris используются следующие поля:

Параметр	Значение	Пример
Отображаемое имя	Отображаемое имя источника данных	Doris-TPCH
Хост	Адрес узла FE Doris	127.0.0.1
Порт	Query Port Doris (порт протокола MySQL), по умолчанию 9030	9030
Catalog	Имя Catalog. Необязательное поле, по умолчанию internal	internal
База данных (необязательно)	База данных в выбранном Catalog. Необязательное поле; если оставить его пустым, будут обнаружены все доступные базы данных в Catalog	tpch
Имя пользователя	Имя пользователя	root
Пароль	Пароль	your_password
SSL	Включение TLS для JDBC. Драйвер использует MariaDB sslMode=trust и не проверяет сертификат сервера или имя хоста	false
Схемы для включения в синхронизацию	Необязательное поле. Используется, когда поле База данных (необязательно) пусто. Список разрешённых баз данных через запятую	tpch
Схемы для исключения из синхронизации	Необязательное поле. Используется, когда поле База данных (необязательно) пусто. Список исключённых баз данных через запятую. Правило исключения имеет приоритет над правилом включения	information_schema
Дополнительные параметры строки подключения JDBC	Другие параметры URL для MariaDB JDBC	connectTimeout=10000

Выберите Catalog и область баз данных следующим образом:

• Внутренние таблицы: оставьте в поле Catalog значение internal и укажите базу данных, например tpch.
• Внешние таблицы: укажите внешний Catalog и доступную в нём базу данных.
• Несколько баз данных: оставьте поле База данных (необязательно) пустым. Драйвер обнаружит базы данных, доступные настроенной учётной записи, и применит списки включения и исключения перед выводом списка таблиц в этих базах данных.

Если поле База данных (необязательно) пусто, драйвер по умолчанию исключает information_schema, __internal_schema и mysql. Правила включения и исключения применяются без учёта регистра; если одна и та же база данных указана в обоих списках, приоритет имеет правило исключения. Если поле База данных (необязательно) задано явно, область синхронизации ограничивается этой базой данных, а настройки включения и исключения на неё не влияют.

Порядок настройки

1. Запустите Metabase и войдите в систему.

2. Нажмите значок шестерёнки в правом верхнем углу и выберите Настройки администратора.

3. В меню слева выберите Базы данных и нажмите кнопку Добавить базу данных в правом верхнем углу.

4. В раскрывающемся списке Тип базы данных выберите Apache Doris.

5. Укажите сведения для подключения:

   Параметр	Пример значения
   Отображаемое имя	Doris-TPCH
   Хост	127.0.0.1
   Порт	9030
   Catalog	internal
   База данных (необязательно)	tpch
   Имя пользователя	admin
   Пароль	******

6. Нажмите Сохранить, чтобы сохранить настройки.

7. Metabase проверит подключение и начнёт синхронизацию метаданных базы данных. При успешном подключении появится соответствующее сообщение.

После настройки источника данных можно создавать визуализации в Metabase.

Создание дашборда с визуализациями

В этом примере в качестве источника используются данные TPC-H. О том, как подготовить источник данных Doris TPC-H, см. в документации по тестированию производительности Doris TPC-H.

Предположим, для анализа затрат нужно выяснить, как со временем растут суммы заказов с разными способами доставки. Настроить визуализацию можно следующим образом.

Создание вопроса

1. Нажмите кнопку Создать + в правом верхнем углу главной страницы и выберите Вопрос.

2. Выберите источник данных:

   Параметр	Пример значения
   База данных	Doris TPCH
   Таблица	lineitem

Создание пользовательской метрики с помощью SQL

Для расчёта выручки необходимо использовать пользовательское SQL-выражение.

1. Нажмите просмотреть SQL в правом верхнем углу, затем нажмите преобразовать этот вопрос в SQL, чтобы отредактировать SQL.

2. Введите следующий SQL-запрос:

   SELECT
     DATE_FORMAT(l_shipdate, '%Y-%m') AS ship_month,
     l_shipmode,
     SUM(l_extendedprice * (1 - l_discount)) AS revenue
   FROM lineitem
   WHERE l_shipdate >= '1995-01-01'
     AND l_shipdate < '1997-01-01'
   GROUP BY
     DATE_FORMAT(l_shipdate, '%Y-%m'),
     l_shipmode
   ORDER BY ship_month, l_shipmode

3. Нажмите кнопку Визуализировать в правом нижнем углу, чтобы просмотреть результаты.

Настройка графика

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

2. При необходимости настройте параметры графика. Metabase автоматически формирует следующую конфигурацию:

   Настройка	Пример значения	Значение
   Ось X	ship_month	Месяц отправки
   Ось Y	revenue	Выручка
   Ряды	l_shipmode	Способ доставки

3. Настройте оформление графика:

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

4. После настройки графика нажмите Сохранить в правом верхнем углу.

5. Введите имя вопроса my-tpch и выберите коллекцию, в которой его нужно сохранить.

Создание дашборда

1. Нажмите + Создать > Дашборд, чтобы создать новый дашборд, и введите его имя my-tpch.

2. Нажмите Добавить график, чтобы добавить сохранённый вопрос на дашборд.

3. Настройте положение и размер графика, затем нажмите Сохранить в правом верхнем углу, чтобы сохранить дашборд.

Вы успешно подключили Metabase к Apache Doris, выполнили анализ данных и создали дашборд с визуализациями.

Возможности и ограничения драйвера

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

Возможность	Поддержка и ограничения
Внутренний Catalog	Поддерживает синхронизацию внутренних таблиц Doris и выполнение запросов к ним
Native SQL	Поддерживается. SQL выполняется с правами настроенной учётной записи Doris; драйвер не ограничивает операторы режимом только для чтения
Конструктор запросов (Query Builder)	Поддерживает агрегацию с группировкой и разбиение по дням
Внешний Catalog	Поддерживает синхронизацию данных во внешних Catalog Doris и выполнение запросов к ним; доступная область данных и полнота метаданных зависят от конкретного коннектора
Параметры нативных шаблонов	Поддерживает числовые и текстовые параметры, а также необязательные блоки
Сложные типы	Поля верхнего уровня типов ARRAY, MAP, JSON, а также сложные поля с непрозрачной структурой остаются видимыми; вложенные поля не раскрываются
Метаданные ключей и индексов	Первичные ключи, внешние ключи, индексы и права доступа к таблицам не синхронизируются
Функции записи Metabase	Загрузка данных, обратная запись, Actions, редактирование данных и сохраняемые модели не поддерживаются

Расширенные сценарии

Использование Catalog для доступа к внешним данным

Задайте Catalog и База данных (необязательно) на странице подключения, чтобы синхронизировать таблицы во внешнем Catalog Doris:

Настройка	Пример значения	Описание
Catalog	hive_catalog	Выберите Catalog Doris с именем hive_catalog
Database (optional)	warehouse	Выберите базу данных warehouse в Catalog

Явно укажите Catalog в SQL-запросе:

SELECT * FROM hive.warehouse.orders LIMIT 100;

Использование параметризованных запросов

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

SELECT
  category,
  COUNT(*) AS row_count,
  SUM(amount) AS total_amount
FROM orders
WHERE amount > {{min_amount}}
[[AND category = {{category}}]]
GROUP BY category

Если значение category не задано, Metabase удаляет необязательный блок целиком.

Возможность шаблона	Поддержка
Числовые переменные	Поддерживаются
Текстовые переменные	Поддерживаются
Необязательные блоки [[ ... ]]	Поддерживаются
Фильтры полей	Не поддерживаются
Ссылки на карточки, например {{#card-id}}	Не поддерживаются
Динамические ссылки на таблицы	Не поддерживаются

Типы данных

При синхронизации метаданных драйвер сопоставляет типы Doris с базовыми типами Metabase, как показано в следующей таблице:

Тип Doris	Базовый тип Metabase
BOOLEAN	type/Boolean
TINYINT, SMALLINT, INT, INTEGER, включая ширину отображения, например INT(11)	type/Integer
BIGINT, LARGEINT, включая ширину отображения, например BIGINT(20)	type/BigInteger
FLOAT, DOUBLE	type/Float
DECIMAL	type/Decimal
DATE, DATEV2	type/Date
TIME, включая точность долей секунды	type/Time
DATETIME, DATETIMEV2, TIMESTAMP	type/DateTime
TIMESTAMPTZ	type/DateTimeWithTZ
CHAR, VARCHAR, STRING, TEXT	type/Text
JSON, JSONB	type/JSON
ARRAY	type/Array
MAP	type/Dictionary
STRUCT, VARIANT, HLL, BITMAP	type/*

Вложенные поля внутри значений ARRAY, MAP, JSON, STRUCT или VARIANT не раскрываются как вложенные поля Metabase. Тип LARGEINT сопоставляется с type/BigInteger и не требует преобразования в строку.

Рекомендации по настройке производительности

Рекомендация	Описание
Используйте отсечение секций	Добавляйте условия фильтрации по столбцу секционирования в предложение WHERE, например WHERE date >= '2024-01-01' AND date < '2024-02-01'
Используйте материализованные представления	Для ускорения сложных запросов с агрегацией создавайте материализованные представления в Doris
Ограничивайте размер результирующего набора	Используйте LIMIT, чтобы ограничить количество возвращаемых строк и избежать одновременной загрузки слишком большого объёма данных
Используйте кэширование запросов	Metabase автоматически кэширует результаты запросов. Настройка подходящего времени хранения кэша может повысить производительность

Советы по подключению и использованию

Сценарий	Рекомендация
Установка драйвера	Убедитесь, что doris.metabase-driver.jar находится в каталоге Metabase plugins, и перезапустите Metabase
Настройка часового пояса	При возникновении проблем с часовым поясом добавьте serverTimezone=Asia/Shanghai в строку подключения JDBC
Оптимизация секционированных таблиц	Правильно создавайте секционированные таблицы Doris, используя секционирование и бакетирование по времени, чтобы эффективно сократить объём данных, сканируемых запросами
Сетевое подключение	Используйте частные подключения VPC, чтобы избежать рисков безопасности, связанных с доступом через общедоступную сеть
Управление правами доступа	Детально настройте роли учётных записей пользователей Doris и права доступа, соблюдая принцип минимальных привилегий
Синхронизация метаданных	При изменении структуры таблицы в Doris нажмите Синхронизировать схему базы данных сейчас на странице администрирования Metabase, чтобы выполнить синхронизацию вручную
Мониторинг производительности	Для медленных запросов используйте SHOW QUERY PROFILE в Doris, чтобы проанализировать узкие места производительности

Некорректное отображение типов данных

Если типы данных в Metabase отображаются некорректно, сначала убедитесь, что вы используете последнюю версию Doris Driver. Для типа Doris largeint необходимо выполнить явное преобразование в SQL:

SELECT CAST(large_int_col AS STRING) FROM table