Projects and emolysis.yml

An Emolysis project is a plain folder that you own. It holds your models, your pipelines, their tests and one project file. It lives in your own Git repository, next to the rest of your code. Nothing in it is locked to the desktop app: the same folder works from the app, the emo command line and an editor or coding agent that supports MCP.

Creating a project #

emo init <name> creates the folder, or choose New project in the app. You can also run it inside an existing repository to add a project there.

emo init orders

Layout #

orders/
  emolysis.yml        project file: name and target platform
  models/             transformations, one per file
  pipelines/          pipelines built from templates, tagged with their platform
  tests/              golden test fixtures and expected outputs
  .emolysis/          local state, not meant to be committed
    lake/             the project's local lakehouse: samples and test tables

The project file #

emolysis.yml names the project and its target platform. The example shows only the fields that are decided.

# emolysis.yml (illustrative; the format may change before release)
name: orders
platform: databricks

platform takes one of databricks, snowflake or fabric. It decides which platform profile the agent loads and which templates it offers. A project targets one platform at a time. Moving to another is an explicit step; see Deploying.

Models and pipelines #

A model is a single transformation, usually one SQL select that produces one table. A pipeline is a filled template for one of the ten shapes, plus the models it uses.

-- models/orders_by_month.sql (illustrative)
select
  date_trunc('month', order_date) as month,
  region,
  sum(amount) as revenue,
  count(*) as orders
from orders_clean
group by 1, 2

Every generated file is tagged with the platform and the profile version it was written for, so it cannot be deployed to a different platform by accident. The tag travels with the file, so a pull request reviewer can see at a glance what a change targets.

Tests #

tests/ holds the golden test fixtures for your pipelines: input data and the output you expect, usually small Parquet files. They are committed with the code, so the same tests run on your machine and in pull request checks. Keep fixtures synthetic. See Golden tests on DuckDB.

The local lakehouse #

.emolysis/lake/ holds the samples you pull from your platform and the tables DuckDB writes during tests. It is a development copy, not a replacement for your platform's catalog, and it is not meant to be committed. Keep .emolysis/ in .gitignore.

# .gitignore
.emolysis/

What is never in a project #

Credentials. Platform tokens and model keys are kept in your machine's credential store, never in emolysis.yml or any other project file. Fixtures and models are your files and contain whatever you put in them, so keep real data and secrets out of them.

Working with Git #

emo sync and emo pr, which commit and push or open a pull request, are planned conveniences; your own Git workflow works just as well. If your team reviews pipeline changes in pull requests, emo check in your CI lints, tests and prices each change before it merges; see GitHub checks.

Status #

The layout and the project file can change before the first release. The folder names above, the platform field and the rule that credentials stay out of the project are fixed.