|
| 1 | +--- |
| 2 | +description: 'Get started with the Moose Stack - a code-first approach to building on top of ClickHouse with type-safe schemas and local development' |
| 3 | +sidebar_label: 'Moose OLAP (TypeScript / Python)' |
| 4 | +sidebar_position: 25 |
| 5 | +slug: /interfaces/third-party/moose-olap |
| 6 | +title: 'Developing on ClickHouse with Moose OLAP' |
| 7 | +keywords: ['Moose'] |
| 8 | +--- |
| 9 | + |
| 10 | +import CommunityMaintainedBadge from '@theme/badges/CommunityMaintained'; |
| 11 | + |
| 12 | +# Developing on ClickHouse with Moose OLAP |
| 13 | + |
| 14 | +<CommunityMaintainedBadge/> |
| 15 | + |
| 16 | +[Moose OLAP](https://docs.fiveonefour.com/moose/olap) is a core module of the [Moose Stack](https://docs.fiveonefour.com/moose), an open source developer toolkit for building real-time analytical backends in Typescript and Python. |
| 17 | + |
| 18 | +Moose OLAP offers developer-friendly abstractions and ORM-like functionality, built natively for ClickHouse. |
| 19 | + |
| 20 | +## Key features of Moose OLAP {#key-features} |
| 21 | + |
| 22 | +- **Schemas as code**: Define your ClickHouse tables in TypeScript or Python with type safety and IDE autocompletion |
| 23 | +- **Type-safe queries**: Write SQL queries with type checking and autocompletion support |
| 24 | +- **Local development**: Develop and test against local ClickHouse instances without affecting production |
| 25 | +- **Migration management**: Version control your schema changes and manage migrations through code |
| 26 | +- **Real-time streaming**: Built-in support for pairing ClickHouse with Kafka or Redpanda for streaming ingest |
| 27 | +- **REST APIs**: Easily generate fully documented REST APIs on top of your ClickHouse tables and views |
| 28 | + |
| 29 | +## Getting started in under 5 minutes {#getting-started} |
| 30 | + |
| 31 | +For the latest and greatest Installation and Getting Started guides, see the [Moose Stack documentation](https://docs.fiveonefour.com/moose/getting-started/from-clickhouse). |
| 32 | + |
| 33 | +Or follow this guide to get up and running with Moose OLAP on an existing ClickHouse or ClickHouse Cloud deployment in under 5 minutes. |
| 34 | + |
| 35 | +### Prerequisites {#prerequisites} |
| 36 | + |
| 37 | +- **Node.js 20+** OR **Python 3.12+** - Required for TypeScript or Python development |
| 38 | +- **Docker Desktop** - For local development environment |
| 39 | +- **macOS/Linux** - Windows works via WSL2 |
| 40 | + |
| 41 | +<VerticalStepper headerLevel="h3"> |
| 42 | + |
| 43 | +### Install Moose {#step-1-install-moose} |
| 44 | + |
| 45 | +Install the Moose CLI globally to your system: |
| 46 | + |
| 47 | +```bash |
| 48 | +bash -i <(curl -fsSL https://fiveonefour.com/install.sh) moose |
| 49 | +``` |
| 50 | + |
| 51 | +### Set up your project {#step-2-set-up-project} |
| 52 | + |
| 53 | +#### Option A: Use your own existing ClickHouse deployment {#option-a-use-own-clickhouse} |
| 54 | + |
| 55 | +**Important**: Your production ClickHouse will remain untouched. This will just initialize a new Moose OLAP project with data models derived from your ClickHouse tables. |
| 56 | + |
| 57 | +```bash |
| 58 | +# TypeScript |
| 59 | +moose init my-project --from-remote <YOUR_CLICKHOUSE_CONNECTION_STRING> --language typescript |
| 60 | + |
| 61 | +# Python |
| 62 | +moose init my-project --from-remote <YOUR_CLICKHOUSE_CONNECTION_STRING> --language python |
| 63 | +``` |
| 64 | + |
| 65 | +Your ClickHouse connection string should be in this format: |
| 66 | + |
| 67 | +```bash |
| 68 | +https://username:password@host:port/?database=database_name |
| 69 | +``` |
| 70 | + |
| 71 | +#### Option B: use ClickHouse playground {#option-b-use-clickhouse-playground} |
| 72 | + |
| 73 | +Don't have ClickHouse up and running yet? Use the ClickHouse Playground to try out Moose OLAP! |
| 74 | + |
| 75 | +```bash |
| 76 | +# TypeScript |
| 77 | +moose init my-project --from-remote https://explorer:@play.clickhouse.com:443/?database=default --language typescript |
| 78 | + |
| 79 | +# Python |
| 80 | +moose init my-project --from-remote https://explorer:@play.clickhouse.com:443/?database=default --language python |
| 81 | +``` |
| 82 | + |
| 83 | +### Install dependencies {#step-3-install-dependencies} |
| 84 | + |
| 85 | +```bash |
| 86 | +# TypeScript |
| 87 | +cd my-project |
| 88 | +npm install |
| 89 | + |
| 90 | +# Python |
| 91 | +cd my-project |
| 92 | +python3 -m venv .venv |
| 93 | +source .venv/bin/activate |
| 94 | +pip install -r requirements.txt |
| 95 | +``` |
| 96 | + |
| 97 | +You should see: `Successfully generated X models from ClickHouse tables` |
| 98 | + |
| 99 | +### Explore your generated models {#step-4-explore-models} |
| 100 | + |
| 101 | +The Moose CLI automatically generates TypeScript interfaces or Python Pydantic models from your existing ClickHouse tables. |
| 102 | + |
| 103 | +Check out your new data models in the `app/index.ts` file. |
| 104 | + |
| 105 | +### Start development {#step-5-start-development} |
| 106 | + |
| 107 | +Start your dev server to spin up a local ClickHouse instance with all your production tables automatically reproduced from your code definitions: |
| 108 | + |
| 109 | +```bash |
| 110 | +moose dev |
| 111 | +``` |
| 112 | + |
| 113 | +**Important**: Your production ClickHouse will remain untouched. This creates a local development environment. |
| 114 | + |
| 115 | +### Seed your local database {#step-6-seed-database} |
| 116 | + |
| 117 | +Seed your data into your local ClickHouse instance: |
| 118 | + |
| 119 | +#### From your own ClickHouse {#from-own-clickhouse} |
| 120 | + |
| 121 | +```bash |
| 122 | +moose seed --connection-string <YOUR_CLICKHOUSE_CONNECTION_STRING> --limit 100 |
| 123 | +``` |
| 124 | + |
| 125 | +#### From ClickHouse playground {#from-clickhouse-playground} |
| 126 | + |
| 127 | +```bash |
| 128 | +moose seed --connection-string https://explorer:@play.clickhouse.com:443/?database=default --limit 100 |
| 129 | +``` |
| 130 | + |
| 131 | +### Building with Moose OLAP {#step-7-building-with-moose-olap} |
| 132 | + |
| 133 | +Now that you have your Tables defined in code, you get the same benefits as ORM data models in web apps - type safety and autocomplete when building APIs and Materialized Views on top of your analytical data. As a next step, you could try: |
| 134 | +* Building a REST API with [Moose API](https://docs.fiveonefour.com/moose/apis) |
| 135 | +* Ingesting or transforming data with [Moose Workflows](https://docs.fiveonefour.com/moose/workflows) or [Moose Streaming](https://docs.fiveonefour.com/moose/workflows) |
| 136 | +* Explore going to production with [Moose Build](https://docs.fiveonefour.com/moose/deploying/summary) and [Moose Migrate](https://docs.fiveonefour.com/moose/migrate) |
| 137 | + |
| 138 | +</VerticalStepper> |
| 139 | + |
| 140 | +## Get help and stay connected {#get-help-stay-connected} |
| 141 | +- **Reference Application**: Check out the open source reference application, [Area Code](https://github.com/514-labs/area-code): a starter repo with all the necessary building blocks for a feature-rich, enterprise-ready application that requires specialized infrastructure. There are two sample applications: User Facing Analytics and Operational Data Warehouse. |
| 142 | +- **Slack Community**: Connect with the Moose Stack maintainers [on Slack](https://join.slack.com/t/moose-community/shared_invite/zt-2fjh5n3wz-cnOmM9Xe9DYAgQrNu8xKxg) for support and feedback |
| 143 | +- **Watch Tutorials**: Video tutorials, demos, and deep-dives into Moose Stack features [on Youtube](https://www.youtube.com/channel/UCmIj6NoAAP7kOSNYk77u4Zw) |
| 144 | +- **Contribute**: Check out the code, contribute to the Moose Stack, and report issues [on GitHub](https://github.com/514-labs/moose) |
0 commit comments