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) moose
Moose 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-app
moose init my-moose-app python
cd my-moose-app
Install Project Dependencies
npm install
Recommended: Create a virtual environment
We recommend creating a virtual environment to avoid dependency conflicts.
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Start Development Server
Start your local development environment:
moose dev
Understand 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 config
app/
├── 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 config
Test 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.yaml
in 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/Foo
endpoint 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
POST
to the/ingest/Foo
endpoint - Data is validated and written to the
Foo
stream - Moose transformed the data into the
Bar
stream - Transformed data is automatically synced to the
Bar
ClickHouse table
Query Your Data
Test your analytics API:
- Locate the
GET /consumption/bar
endpoint - 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: