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

Разработка на ClickHouse с Moose OLAP

Community Maintained

Moose OLAP — это основной модуль Moose Stack, открытого набора инструментов для разработчиков, предназначенного для создания аналитических backend-систем реального времени на TypeScript и Python.

Moose OLAP предоставляет удобные для разработчиков абстракции и ORM-подобную функциональность, изначально разработанную для ClickHouse.

Ключевые возможности Moose OLAP​

  • Схемы в виде кода: определяйте таблицы ClickHouse на TypeScript или Python с гарантиями типизации и автодополнением в IDE
  • Типобезопасные запросы: пишите SQL-запросы с проверкой типов и поддержкой автодополнения
  • Локальная разработка: разрабатывайте и тестируйте, используя локальные экземпляры ClickHouse, не затрагивая производственную среду
  • Управление миграциями: управляйте версиями изменений схемы и миграциями в коде
  • Потоковая обработка в реальном времени: встроенная поддержка использования ClickHouse совместно с Kafka или Redpanda для потокового приёма данных
  • REST API: легко генерируйте полностью документированные REST API поверх ваших таблиц и представлений ClickHouse

Начало работы менее чем за 5 минут​

Самые актуальные и подробные руководства по установке и началу работы см. в документации Moose Stack.

Или следуйте этому руководству, чтобы запустить Moose OLAP на уже развернутом ClickHouse или ClickHouse Cloud менее чем за 5 минут.

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

  • Node.js 20+ ИЛИ Python 3.12+ — требуется для разработки на TypeScript или Python
  • Docker Desktop — для локальной среды разработки
  • macOS/Linux — Windows работает через WSL2

Установка Moose​

Установите Moose CLI глобально в вашей системе:

bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose

Настройка проекта​

Вариант A: использовать собственное существующее развертывание ClickHouse​

Важно: ваш продуктивный ClickHouse останется нетронутым. Это только инициализирует новый проект Moose OLAP с моделями данных, построенными на основе ваших таблиц ClickHouse.

# TypeScript \{#typescript}
moose init my-project --from-remote <YOUR_CLICKHOUSE_CONNECTION_STRING> --language typescript

# Python \{#python}
moose init my-project --from-remote <YOUR_CLICKHOUSE_CONNECTION_STRING> --language python

Ваша строка подключения к ClickHouse должна иметь следующий формат:

https://username:password@host:port/?database=database_name

Вариант B: использовать ClickHouse Playground​

У вас ещё не запущен ClickHouse? Используйте ClickHouse Playground, чтобы опробовать Moose OLAP!

# TypeScript \{#typescript}
moose init my-project --from-remote https://explorer:@play.clickhouse.com:443/?database=default --language typescript

# Python \{#python}
moose init my-project --from-remote https://explorer:@play.clickhouse.com:443/?database=default --language python

Установите зависимости​

# TypeScript \{#typescript}
cd my-project
npm install

# Python \{#python}
cd my-project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Должно появиться сообщение: Successfully generated X models from ClickHouse tables

Изучите сгенерированные модели​

Moose CLI автоматически генерирует интерфейсы TypeScript или модели Pydantic на Python из ваших существующих таблиц ClickHouse.

Ознакомьтесь с новыми моделями данных в файле app/index.ts.

Начало разработки​

Запустите dev-сервер, чтобы поднять локальный экземпляр ClickHouse со всеми вашими продуктивными таблицами, автоматически воссозданными из определений в коде:

moose dev

Важно: ваш продуктивный ClickHouse останется нетронутым. Это создаёт локальную среду разработки.

Наполнение локальной базы данных​

Загрузите данные в локальный экземпляр ClickHouse:

Из собственного ClickHouse​

moose seed --connection-string <YOUR_CLICKHOUSE_CONNECTION_STRING> --limit 100

Из ClickHouse Playground​

moose seed --connection-string https://explorer:@play.clickhouse.com:443/?database=default --limit 100

Разработка с Moose OLAP​

Теперь, когда ваши таблицы определены в коде, вы получаете те же преимущества, что и с моделями данных ORM в веб-приложениях, — строгую типизацию и автодополнение при построении API и материализованных представлений поверх ваших аналитических данных. В качестве следующего шага вы можете:

Получите помощь и оставайтесь на связи​

  • Эталонное приложение: Ознакомьтесь с open source эталонным приложением Area Code — стартовым репозиторием со всеми необходимыми строительными блоками для функционально насыщенного, готового к использованию в корпоративной среде приложения, которое требует специализированной инфраструктуры. В него входят два примера приложений: User Facing Analytics и Operational Data Warehouse.
  • Сообщество в Slack: Свяжитесь с мейнтейнерами Moose Stack в Slack, чтобы получить поддержку и оставить отзыв.
  • Смотрите обучающие материалы: Видеоруководства, демо и подробные разборы возможностей Moose Stack на YouTube.
  • Внесите свой вклад: Изучайте код, вносите вклад в Moose Stack и сообщайте о проблемах на GitHub.