Moose Quickstart Guide
Viewing typescript
switch to python
Prerequisites
- Node.js: version 20+ (LTS recommended)
- Python: version 3.12+
- OS: macOS or Linux (WSL supported for Windows)
- Docker Desktop/Engine: 24.0.0+
Install Moose
The easiest way to install Moose is to use the one-liner below:
bash -i <(curl -fsSL https://fiveonefour.com/install.sh) mooseMoose CLI Version Manager
The Moose CLI has a built in version manager that will automatically install the correct version of Moose for your project.
Create Your Project
Initialize Project
First, create a new Moose project:
moose init my-moose-app typescript
cd my-moose-appmoose init my-moose-app python
cd my-moose-appInstall Project Dependencies
npm installRecommended: Create a virtual environment
We recommend creating a virtual environment to avoid dependency conflicts.
python3 -m venv .venv
source .venv/bin/activatepip install -r requirements.txtStart Development Server
Start your local development environment:
moose devUnderstand Project Structure
Your project contains:
app/
├── main.py # Entrypoint for your Moose app
├── ingest/ # Raw data ingestion and streaming
│ ├── models.py
│ └── transform.py
├── views/ # Materialized views and aggregations
│ └── bar_aggregated.py
├── apis/ # Analytics APIs
│ └── bar.py
├── scripts/
│ └── generator/ # Random data generator for testing
└── moose.config.toml # Project configapp/
├── index.ts # Entrypoint for your Moose app
├── ingest/ # Raw data ingestion and streaming
│ ├── models.ts
│ └── transform.ts
│
├── views/ # Materialized views and aggregations
│ └── barAggregated.ts
│
└── apis/ # Analytics APIs
└── bar.ts
├── scripts/
│ └── generator/ # Random data generator for testing
│
└── moose.config.toml # Project configTest Your Pipeline
How Data Flows
Data Ingestion
Raw data enters through HTTP endpoints into your Foo stream
Stream Processing
Data is transformed on the fly into your Bar stream before landing in ClickHouse
Live Aggregations
Materialized views continuously update aggregated data tables in real-time
Analytics APIs
Query your aggregated data through type-safe REST endpoints with filtering and sorting
Setting up the OpenAPI UI
Moose auto-generates an OpenAPI spec for your APIs, enabling direct testing from your editor. To set up:
- Install the OpenAPI (Swagger) Viewer extension in your IDE
- Open
.moose/openapi.yamlin your IDE - Click the “Preview” icon (magnifying glass) in the top-right corner to launch the OpenAPI UI
Send Test Data
- Navigate to the
POST /ingest/Fooendpoint in the OpenAPI UI - Click “Try it out”
- Use the sample request body provided or modify it
- Click “Execute” to send the request
You should see output like this in your terminal:
POST ingest/Foo
[POST] Data received at ingest API sink for Foo
Received Foo_0_0 -> Bar_0_0 1 message(s)
[DB] 1 row(s) successfully written to DB table (Bar)Data landed in ClickHouse!
- You sent raw data via HTTP
POSTto the/ingest/Fooendpoint - Data is validated and written to the
Foostream - Moose transformed the data into the
Barstream - Transformed data is automatically synced to the
BarClickHouse table
Query Your Data
Test your analytics API:
- Locate the
GET /consumption/barendpoint - Click “Try it out”
- Experiment with query parameters:
orderBy: Try “rowsWithText”startDay: Enter a number (e.g., 1)endDay: Enter a number (e.g., 10)
order_by: Try “rows_with_text”start_day: Enter a number (e.g., 1)end_day: Enter a number (e.g., 10)
- Click “Execute” to see the results
The UI will show both the request URL and the response data in a formatted view.
Next Steps
Take a deeper dive into core Moose concepts: