Trino Excel Client

Python-библиотека для генерации Excel-шаблона с Power Query клиентом к Trino REST API.

Основной артефакт для пользователей - готовый Excel-файл в templates/. Его можно собрать локально на Windows с установленным Microsoft Excel или через GitHub Actions на self-hosted Windows runner с desktop Excel.

Оглавление

• Для пользователей
  • Что скачать
  • Как работать в Excel
  • Advanced .xlsm шаблон
  • Лимиты и BigData
  • Безопасность
• Для разработчиков
  • Требования
  • Установка
  • Сборка стандартного .xlsx шаблона
  • Сборка advanced .xlsm шаблона
  • Python API
  • Встраивание в существующую книгу
  • Проверки
  • Структура проекта

Для пользователей

Что скачать

Для обычной работы скачайте стандартный шаблон:

templates/Trino_REST_Client.xlsx

Для продвинутой работы с выгрузкой разных SQL на разные листы используйте macro-enabled шаблон:

templates/Trino_REST_Advanced_Client.xlsm

Если файла нет или он устарел, попросите разработчика пересобрать шаблон на Windows через Excel COM и закоммитить новый файл в templates/.

Как работать в Excel

1. Откройте Trino_REST_Client.xlsx.
2. На листе Trino Config заполните:
   • trino_base_url
   • trino_user
   • trino_password
   • при необходимости trino_catalog и trino_schema
3. Если источник требует delegated credentials, заполните tblExtraCredentials.
4. На листе Trino Query введите SQL в таблицу tblTrinoSql.
5. Нажмите Данные -> Обновить все.
6. Результат появится на листе Trino Result.

В обычном .xlsx шаблоне даты форматируются без макросов. Для этого книга использует скрытый технический лист Trino Schema: он получает из Trino типы колонок через отдельный schema-запрос без строк результата и помогает Excel показывать date, timestamp и timestamp with time zone как даты/дату-время, а не как общий числовой формат.

При первом обращении Excel может спросить credentials/privacy level для Trino host. Обычно нужно выбрать Anonymous, потому что Basic Auth передается M-кодом через HTTP header.

Также Excel может запрещать исполнять неподтвержденные HTTP запросы, из-за чего блокируется загрузка данных в Excel. Необходимо в таком случае перейти в "Данные" -> "Получить данные" -> "Параметры запроса". В открывшемся окне необходимо выбрать уровень настроек (Глобальный/только эта книга), перейти в "Конфиденциальность" и выбрать "Игнорировать все уровни конфиденциальности", таким образом вы разрешите Excel посылать HTTP запросы в Trino.

Клиент настроен так, чтобы не отправлять запросы в Trino при открытии книги или при редактировании SQL. Запрос должен уходить только после пользовательского refresh-действия в Excel.

Advanced .xlsm шаблон

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

1. Откройте .xlsm и разрешите макросы, если Excel покажет предупреждение.
2. Заполните Trino Config.
3. На листе Trino Query введите SQL.
4. В таблице advanced-параметров укажите target_sheet - название листа результата.
5. Нажмите кнопку Выгрузить в лист.

Если лист с таким названием уже есть, таблица результата на нем будет обновлена. Если листа нет, макрос создаст его и загрузит результат туда.

В advanced-шаблоне используйте именно кнопку Выгрузить в лист. Команда Excel Данные -> Обновить все не является основным сценарием для advanced-режима: результаты, созданные кнопкой, настроены так, чтобы не обновляться через общий refresh книги.

Лимиты и BigData

Excel не подходит для прямой загрузки миллионов или миллиардов строк. В шаблоне есть защитные параметры:

Параметр	По умолчанию	Что делает
result_limit_rows	1000000	M-код добавляет внешний LIMIT вокруг SQL и не дает загрузить в Excel больше этого количества строк

По умолчанию SQL отправляется в Trino так:

select *
from (
    <ваш SQL>
) as excel_trino_client_query
limit 1000000

Рекомендации:

• выбирайте только нужные колонки;
• используйте фильтры и агрегаты;
• не запускайте select * по большим таблицам без понимания объема результата;
• для больших выгрузок используйте внешние export pipeline, parquet/csv или BI/ETL-инструменты.

Безопасность

Парольные ячейки визуально скрыты форматом Excel, но это не шифрование. Книга содержит учетные данные, если они были заполнены.

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

Для разработчиков

Требования

Для полноценной сборки шаблона с Power Query:

• Windows
• Desktop Microsoft Excel 2016+ с Power Query
• Python 3.10+
• pywin32

На macOS/Linux можно собрать только UI-preview через openpyxl; Power Query COM-встраивание доступно только в desktop Excel на Windows.

Установка

Из репозитория:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

Windows PowerShell / cmd:

python -m venv .venv
.venv\Scripts\activate
pip install -e ".[test]"

После установки доступна команда:

trino-excel-client --help

Сборка стандартного .xlsx шаблона

На Windows с установленным Excel:

trino-excel-client create --backend com --output templates\Trino_REST_Client.xlsx --overwrite --visible

Без видимого Excel:

trino-excel-client create --backend com --output templates\Trino_REST_Client.xlsx --overwrite

Эта команда:

1. создает стабильный UI через openpyxl;
2. открывает книгу через Excel COM;
3. добавляет Power Query M-код;
4. создает скрытую schema-таблицу для форматирования дат в .xlsx;
5. создает таблицу результата на листе Trino Result;
6. сохраняет готовый шаблон.

После ручной проверки шаблон можно закоммитить:

git add templates\Trino_REST_Client.xlsx
git commit -m "Update Trino Excel template"

Сборка advanced .xlsm шаблона

На Windows с установленным Excel:

trino-excel-client create --backend com --advanced --output templates\Trino_REST_Advanced_Client.xlsm --overwrite --visible

Без видимого Excel:

trino-excel-client create --backend com --advanced --output templates\Trino_REST_Advanced_Client.xlsm --overwrite

Для сборки advanced-шаблона Excel должен разрешать доступ к VBA project object model: File -> Options -> Trust Center -> Trust Center Settings -> Macro Settings -> Trust access to the VBA project object model.

После ручной проверки шаблон можно закоммитить:

git add templates\Trino_REST_Advanced_Client.xlsm
git commit -m "Update advanced Trino Excel template"

Для автоматической сборки полноценного шаблона нужен self-hosted Windows runner с установленным desktop Microsoft Excel. На обычном GitHub-hosted runner можно собрать только UI-only preview, потому что Power Query COM-встраивание требует установленный Excel.

Python API

Собрать полноценный шаблон через Windows Excel COM:

from pathlib import Path

from trino_excel_client import create_workbook

create_workbook(
    output_path=Path("templates/Trino_REST_Client.xlsx"),
    overwrite=True,
    visible=False,
)

Собрать advanced .xlsm через Windows Excel COM:

from pathlib import Path

from trino_excel_client import create_advanced_workbook

create_advanced_workbook(
    output_path=Path("templates/Trino_REST_Advanced_Client.xlsm"),
    overwrite=True,
    visible=False,
)

Собрать UI-only preview без Power Query:

from pathlib import Path

from trino_excel_client import create_workbook_ui

create_workbook_ui(
    output_path=Path("build/Trino_UI_Preview.xlsx"),
    overwrite=True,
)

Встраивание в существующую книгу

Через CLI:

trino-excel-client install --backend com --workbook .\reports\Workbook.xlsx --output .\build\Workbook_With_Trino.xlsx --overwrite

Через Python API:

from pathlib import Path

from trino_excel_client import install_client

install_client(
    workbook_path=Path("reports/Workbook.xlsx"),
    output_path=Path("build/Workbook_With_Trino.xlsx"),
    overwrite=True,
)

Advanced-вариант:

from pathlib import Path

from trino_excel_client import install_advanced_client

install_advanced_client(
    workbook_path=Path("reports/Workbook.xlsm"),
    output_path=Path("build/Workbook_With_Advanced_Trino.xlsm"),
    overwrite=True,
)

Проверки

trino-excel-client validate
pytest

После сборки шаблона откройте templates\Trino_REST_Client.xlsx, заполните тестовый Config, выполните небольшой SQL и нажмите Данные -> Обновить все несколько раз. Лист Trino Query не должен изменяться, результат должен обновляться на Trino Result.

Структура проекта

src/trino_excel_client/openpyxl_backend.py  # UI Excel-шаблона
src/trino_excel_client/excel_com.py         # Power Query через Windows Excel COM
src/trino_excel_client/m_code.py            # M-код запросов
src/trino_excel_client/template.py          # таблицы, подписи, дефолты
src/trino_excel_client/cli.py               # CLI для разработчика
templates/                                  # готовые Excel-шаблоны для пользователей