### Install Dependencies and Start Server

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/docs/development.md

Installs project dependencies and starts the Wren Engine server. Use 'just dev' for development mode with auto-reloading.

```shell
just install
```

```shell
just install-core
```

```shell
just run
```

```shell
just dev
```

--------------------------------

### Install and Develop Python Connector Server

Source: https://github.com/canner/wren-engine/blob/main/README.md

Commands to install dependencies and start the development server for the Python connector. Ensure you are in the 'ibis-server' directory.

```bash
cd ibis-server
just install
just dev
```

--------------------------------

### MCP Server: Get Wren Guide

Source: https://context7.com/canner/wren-engine/llms.txt

Retrieve detailed usage instructions and tips for the Wren Engine, including data source-specific advice.

```python
# MCP Tool: get_wren_guide
guide = await get_wren_guide()
# Returns: Detailed usage instructions including data source-specific tips
```

--------------------------------

### Run Wren Engine Examples with Cargo

Source: https://github.com/canner/wren-engine/blob/main/wren-core/wren-example/README.md

Use `cargo run --example <example_name>` to execute specific examples. Ensure you are in the `wren-core` directory after cloning the repository.

```bash
git clone https://github.com/Canner/wren-engine.git
cd wren-engine/wren-core

# Run the `datafusion-apply` example:
# ... use the equivalent for other examples
cargo run --example datafusion-apply
```

--------------------------------

### Start Doris Docker Compose

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Starts the Apache Doris container using Docker Compose. Ensure you have Docker and Docker Compose installed. This command should be run from the 'tests/routers/v3/connector/doris' directory.

```bash
cd tests/routers/v3/connector/doris
docker compose up -d
```

--------------------------------

### Recommended Prompt for Wren Engine Interaction

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

This prompt instructs the AI agent to use the 'get_wren_guide()' tool to learn about Wren Engine and discover available tools and examples. It's a good starting point for interacting with the engine.

```text
Use the get_wren_guide() tool to learn how to use Wren Engine and discover available tools and examples.
```

--------------------------------

### Setup MCP Server

Source: https://github.com/canner/wren-engine/blob/main/README.md

Instructions for setting up the MCP server. Refer to the module's README for specific uv-based setup details. Navigate to the 'mcp-server' directory.

```bash
cd mcp-server
# see module README for uv-based setup
```

--------------------------------

### Development Installation and Linting

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

Commands for installing development dependencies, performing linting, and auto-formatting code.

```bash
just install-dev
```

```bash
just lint
```

```bash
just format
```

--------------------------------

### Publishing Script Examples

Source: https://github.com/canner/wren-engine/blob/main/wren-core-py/README.md

Examples of using the publish script for building wheels and publishing to PyPI or TestPyPI. Use the --build flag for wheel-only builds, --test for TestPyPI, and no flags for PyPI.

```bash
./scripts/publish.sh --build    # Build wheel only
```

```bash
./scripts/publish.sh --test     # Build + publish to TestPyPI
```

```bash
./scripts/publish.sh            # Build + publish to PyPI
```

--------------------------------

### Install Wren Engine with Interactive Extra

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/memory.md

Install Wren Engine with the `main` extra for recommended features, or specifically with the `interactive` extra if only that functionality is needed.

```bash
pip install "wren-engine[main]"          # recommended
```

```bash
pip install "wren-engine[interactive]"   # interactive only
```

--------------------------------

### Recall Few-Shot Examples (Command Decision Tree)

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-usage/SKILL.md

Recalls few-shot examples based on a query. This is useful for getting examples of how to structure similar queries.

```bash
wren memory recall -q "..."
```

--------------------------------

### Install and Format TOML with Taplo

Source: https://github.com/canner/wren-engine/blob/main/wren-core/README.md

Install the `taplo-cli` tool and use it to format TOML configuration files.

```bash
cargo install taplo-cli --locked
taplo fmt
```

--------------------------------

### Install Wren Engine with Connectors

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

Install the core wren-engine package or with specific connectors for databases like PostgreSQL, MySQL, BigQuery, and more. Use '[all]' to install all connectors and main features.

```bash
pip install wren-engine              # Core (DuckDB included)
pip install wren-engine[postgres]    # PostgreSQL
pip install wren-engine[mysql]       # MySQL
pip install wren-engine[bigquery]    # BigQuery
pip install wren-engine[snowflake]   # Snowflake
pip install wren-engine[clickhouse]  # ClickHouse
pip install wren-engine[trino]       # Trino
pip install wren-engine[mssql]       # SQL Server
pip install wren-engine[databricks]  # Databricks
pip install wren-engine[redshift]    # Redshift
pip install wren-engine[spark]       # Spark
pip install wren-engine[athena]      # Athena
pip install wren-engine[oracle]      # Oracle
pip install 'wren-engine[memory]'    # Schema & query memory (LanceDB)
pip install 'wren-engine[ui]'        # Browser-based profile form (starlette + uvicorn)
pip install 'wren-engine[main]'      # memory + interactive prompts + ui
pip install 'wren-engine[all]'       # All connectors + main
```

--------------------------------

### Install Wren CLI Skills

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Install the necessary Wren CLI skills for effective AI agent usage. These skills guide the AI in gathering context, writing SQL, and managing results.

```bash
npx skills add Canner/wren-engine --skill '*'
# or:
curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash
```

--------------------------------

### Run Ibis Server Locally

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Start the Ibis Server locally using the 'just run' command after installing dependencies and configuring environment variables.

```bash
just run
```

--------------------------------

### Install Wren Engine Skills using Install Script

Source: https://github.com/canner/wren-engine/blob/main/skills/README.md

Execute the install script to install all Wren Engine skills or a specific skill. The --force flag can be used to overwrite existing installations.

```bash
bash skills/install.sh                    # all skills
bash skills/install.sh wren-usage         # specific skill (auto-installs dependencies)
bash skills/install.sh --force wren-usage # overwrite existing
```

--------------------------------

### Install Dependencies for Ibis Server

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Install project dependencies using the 'just' command-line tool. This is a prerequisite for running the Ibis Server locally.

```bash
just install
```

--------------------------------

### Skill Directory Structure Example

Source: https://github.com/canner/wren-engine/blob/main/skills/AUTHORING.md

Illustrates the standard directory layout for a skill, including required and optional files and directories.

```text
skill-name/
├── SKILL.md              # Required — frontmatter + workflow instructions
├── references/           # Optional — detail files loaded on demand
│   ├── some-topic.md
│   └── another-topic.md
└── scripts/              # Optional — executable scripts the agent can run
```

--------------------------------

### Verify Wren Installation

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-usage/SKILL.md

After installation, run this command to verify that the wren CLI is installed and accessible.

```bash
wren --version
```

--------------------------------

### SKILL.md Frontmatter Example

Source: https://github.com/canner/wren-engine/blob/main/skills/AUTHORING.md

Shows the required YAML frontmatter for a SKILL.md file, including name, description, license, and metadata.

```yaml
---
name: skill-name
description: "What this skill does and when to trigger it. Include specific
  trigger keywords. This field is loaded at startup for every conversation."
license: Apache-2.0
metadata:
  author: wren-engine
  version: "1.0"
---
```

--------------------------------

### Install Wren Engine with Datasource Extra

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-usage/SKILL.md

Install the wren-engine package. Use the datasource extra for specific database types. The 'main' extra enables semantic memory, interactive prompts, and web UI.

```bash
pip install "wren-engine"
```

```bash
pip install "wren-engine[<datasource>]"
```

```bash
pip install "wren-engine[<datasource>,main]"
```

```bash
pip install "wren-engine[main]"
```

--------------------------------

### Install Wren Engine CLI

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs the Wren CLI and its core components using pip. This is the primary command for setting up the engine.

```bash
pip install "wren-engine[main]"
```

--------------------------------

### Install Pre-commit Hooks

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/docs/development.md

Installs pre-commit hooks to ensure code quality and consistency before commits.

```shell
just pre-commit-install
```

--------------------------------

### Install Wren Engine Skills via Install Script

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs Wren Engine skills by downloading and executing a shell script. This method is a convenient alternative for users who do not use npm.

```bash
curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash
```

--------------------------------

### Install Wren Engine with Main Extra

Source: https://github.com/canner/wren-engine/blob/main/docs/reference/cli.md

Installs the Wren Engine package with the 'main' extra bundle, which includes capabilities for memory, interactive, and UI features.

```bash
pip install 'wren-engine[main]'
```

--------------------------------

### Install wren-core-py

Source: https://github.com/canner/wren-engine/blob/main/wren-core-py/README.md

Install the wren-core-py package using pip. Requires Python 3.11 or higher.

```bash
pip install wren-core-py
```

--------------------------------

### Remove Example Models and Views

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Before generating new MDL, remove the placeholder example model and view files created by `wren context init`.

```bash
rm -rf models/example_model views/example_view
```

--------------------------------

### Install OpenTelemetry Python Zero-Code Instrumentation

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Installs the necessary OpenTelemetry Python packages and bootstraps the zero-code instrumentation. This enables tracing export to OTLP endpoints.

```bash
pip install opentelemetry-distro opentelemetry-exporter-otlp
opentelemetry-bootstrap -a install
```

--------------------------------

### Install Development and UI Dependencies

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

Synchronize development and UI dependencies using `uv` and then run pytest for profile web tests.

```bash
uv sync --extra dev --extra ui --find-links ../wren-core-py/target/wheels/
```

```bash
uv run pytest tests/test_profile_web.py -v
```

--------------------------------

### Install Wren Engine Skills via Claude Code Plugin

Source: https://github.com/canner/wren-engine/blob/main/skills/README.md

Add the marketplace and install the Wren Engine skills. This is one method for setting up the skills for AI agents.

```bash
/plugin marketplace add Canner/wren-engine --path skills
/plugin install wren@wren
```

--------------------------------

### Querying a View

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/view.md

Demonstrates how to query a defined view as if it were a regular table. This example shows selecting all columns from `completed_orders`.

```sql
SELECT * FROM completed_orders;
```

--------------------------------

### Wren Usage Skill Workflow Example

Source: https://github.com/canner/wren-engine/blob/main/docs/reference/skills.md

Illustrates the typical query workflow using the 'wren-usage' skill, from gathering context to storing results.

```text
User asks a question
  │
  ├── 1. Gather context
  │     wren memory fetch -q "..."
  │     wren context instructions      (first query only)
  │
  ├── 2. Recall past queries
  │     wren memory recall -q "..." --limit 3
  │
  ├── 3. Assess complexity
  │     Simple → write SQL directly
  │     Complex → decompose into sub-questions
  │
  ├── 4. Write and execute SQL
  │     Simple: wren --sql "..."
  │     Complex: wren dry-plan first, then execute
  │
  └── 5. Store result
        wren memory store --nl "..." --sql "..."
```

--------------------------------

### Install dlt with DuckDB support

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-dlt-connector/SKILL.md

Install the dlt library with the necessary dependencies for DuckDB integration. Use `--break-system-packages` if running in an environment where pip is managed by the system.

```bash
pip install "dlt[duckdb]" --break-system-packages
```

--------------------------------

### Install Wren Engine with Multiple Data Source Extras

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs the Wren Engine with support for multiple data sources, including PostgreSQL and BigQuery. This is useful for environments with diverse database needs.

```bash
pip install "wren-engine[postgres,bigquery,main]"
```

--------------------------------

### Start Wren Engine with Docker Compose

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

Command to start the Wren Engine using Docker Compose. This is necessary if you do not have a running Wren Engine instance.

```sh
cd docker
docker compose up
```

--------------------------------

### Dry Run Output Example

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/wren_project.md

This output shows a preview of file creation, deletion, and modification during a dry run of the `wren context upgrade` command.

```text
Dry run — no files will be changed.

Would create:
  models/orders/metadata.yml
  models/orders/ref_sql.sql
  views/summary/metadata.yml

Would delete:
  models/orders.yml
  views.yml

Would modify:
  wren_project.yml (schema_version 1 -> 3)
```

--------------------------------

### Run Docker Compose

Source: https://github.com/canner/wren-engine/blob/main/example/duckdb-tpch-example/README.md

Use this command to start the Wren Engine platform with the DuckDB data source. Ensure your .env file is configured.

```bash
docker compose --env-file .env up
```

--------------------------------

### Local Build Prerequisites for Rust

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Install Zig and Rust targets required for local single-platform builds of the Ibis Server Docker image.

```bash
brew install zig
rustup target add aarch64-unknown-linux-gnu  # Apple Silicon
rustup target add x86_64-unknown-linux-gnu   # Intel Mac
```

--------------------------------

### Connection URL Format

Source: https://context7.com/canner/wren-engine/llms.txt

Example of using a connection URL string for supported databases like PostgreSQL, MySQL, ClickHouse, and Trino.

```json
{
  "connectionUrl": "postgresql://user:pass@localhost:5432/mydb"
}
```

--------------------------------

### Connection file formats for profile import

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/profiles.md

Examples of accepted connection file formats: flat and envelope. The envelope format is automatically unwrapped.

```json
// Flat format
{"datasource": "postgres", "host": "localhost", "port": 5432, "database": "mydb", "user": "root", "password": "secret"}
```

```json
// Envelope format (auto-unwrapped)
{"datasource": "duckdb", "properties": {"url": "/data", "format": "duckdb"}}
```

--------------------------------

### Markdown Business Rules Example

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Customize `instructions.md` to define business rules, naming conventions, and query guidelines. Use `##` headings for organization.

```markdown
## Naming Conventions
- "revenue" always means order total, not supply cost
- "active customers" means customers with at least one order in the last 90 days

## Query Rules
- Always use order_date for time-based filtering, not created_at
```

--------------------------------

### Initialize Wren Project

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/connect.md

Initialize a new Wren project by creating a directory and running the 'wren context init' command. This scaffolds the basic project structure.

```bash
mkdir ~/my-project && cd ~/my-project
```

```bash
wren context init
```

--------------------------------

### Initialize Project from MDL JSON

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

If you already have an MDL JSON file, you can initialize your project directly using the '--from-mdl' flag with the 'wren context init' command.

```bash
wren context init --from-mdl path/to/mdl.json
```

--------------------------------

### Seed jaffle_shop Dataset and Build DuckDB

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Clone the dbt jaffle_shop project, install necessary packages, and build the DuckDB database. Note the absolute path to this directory for profile setup.

```bash
git clone https://github.com/dbt-labs/jaffle_shop_duckdb.git
cd jaffle_shop_duckdb
pip install dbt-core dbt-duckdb
dbt build
```

--------------------------------

### Initialize Wren Project

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Create a new directory for your Wren project and scaffold the project structure, including configuration files and directories for models, views, and relationships.

```bash
mkdir -p ~/jaffle-wren && cd ~/jaffle-wren
wren context init
```

--------------------------------

### Install Wren Engine Skills

Source: https://github.com/canner/wren-engine/blob/main/docs/reference/skills.md

Installs all Wren Engine skills for the 'claude-code' agent. Alternatively, use the install script for a non-interactive installation.

```bash
npx skills add Canner/wren-engine --skill '*' --agent claude-code
```

```bash
curl -fsSL https://raw.githubusercontent.com/Canner/wren-engine/main/skills/install.sh | bash
```

--------------------------------

### Minimal MDL Structure Example

Source: https://github.com/canner/wren-engine/blob/main/wren-core-wasm/AGENT_GUIDE.md

Defines the data model for the WrenEngine. It includes catalog, schema, models with table references and column definitions, and relationships.

```javascript
const mdl = {
  catalog: 'wren',
  schema: 'public',
  models: [
    {
      name: 'Orders',              // query as: SELECT ... FROM "Orders"
      tableReference: { table: 'orders' },  // physical table name (bare, no URL)
      columns: [
        { name: 'id', type: 'INTEGER' },
        { name: 'customer', type: 'VARCHAR' },
        { name: 'amount', type: 'DOUBLE' },
        { name: 'order_date', type: 'DATE' },
      ],
      primaryKey: 'id',
    },
  ],
  relationships: [],
  metrics: [],
  views: [],
};
```

--------------------------------

### Create and Configure config.properties

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Steps to create the 'etc' directory and the 'config.properties' file with essential configurations for the Ibis Server.

```bash
mkdir etc
cd etc
vim config.properties
```

```properties
node.environment=production
```

--------------------------------

### Install Wren Engine Skills

Source: https://github.com/canner/wren-engine/blob/main/skills/SKILLS.md

Use this script to install Wren Engine skills. It can install a specific skill or all available skills. Dependencies are auto-installed.

```bash
bash skills/install.sh wren-usage
```

```bash
bash skills/install.sh
```

--------------------------------

### Initialize Project with Empty Queries.yml

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/memory.md

The `wren context init` command scaffolds a new project, creating an empty `queries.yml` file to store curated NL-SQL pairs.

```yaml
# Curated NL-SQL pairs for this project.
# These are auto-loaded into memory on `wren memory index`.
# Use `wren memory dump` to export pairs from memory to this file.
# Format: same as `wren memory dump` output.
version: 1
pairs: []
```

--------------------------------

### dlt Init Shortcut Command

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-dlt-connector/references/dlt_sources.md

Use this bash command to quickly scaffold a new pipeline for a verified source. Replace <source_name> with the desired source.

```bash
dlt init <source_name> duckdb
```

--------------------------------

### Install Wren Engine with Memory Extra

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/memory.md

Install Wren Engine with the 'memory' extra for full memory system functionality, including interactive and UI components. Alternatively, install 'memory' only.

```bash
pip install "wren-engine[main]"
```

```bash
pip install "wren-engine[memory]"
```

--------------------------------

### Create and Activate a Virtual Environment

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Sets up a Python virtual environment named 'wren' in the user's home directory and activates it. This isolates Wren Engine dependencies.

```bash
python3 -m venv ~/.venvs/wren
source ~/.venvs/wren/bin/activate
```

--------------------------------

### Install wren-core-wasm via npm

Source: https://github.com/canner/wren-engine/blob/main/wren-core-wasm/README.md

Install the wren-core-wasm package using npm for use in your project.

```bash
npm install wren-core-wasm
```

--------------------------------

### SQL Planning Pipeline

Source: https://github.com/canner/wren-engine/blob/main/docs/concept/architecture.md

This diagram illustrates the step-by-step process of transforming user SQL into executable database SQL. It highlights the roles of sqlglot, ManifestExtractor, Policy check, CTE Rewriter, and wren-core-py in expanding semantic model references.

```text
User SQL (e.g. SELECT * FROM orders WHERE status = 'pending')
  │
  ├── sqlglot: parse → qualify tables → normalize identifiers
  ├── Extract referenced table names → ["orders"]
  ├── ManifestExtractor: filter MDL to only referenced models
  ├── Policy check (strict mode, denied functions)
  ├── CTE Rewriter:
  │     ├── For each model: wren-core transform_sql() → expanded CTE
  │     └── Inject CTEs into original query
  └── sqlglot: transpile to target dialect (postgres, bigquery, etc.)
        │
        ▼
  WITH "orders" AS (
    SELECT o_orderkey, o_custkey, o_totalprice
    FROM "public"."orders"
  )
  SELECT * FROM "orders" WHERE status = 'pending'

```

--------------------------------

### Wren Engine Connection and MDL Setup

Source: https://github.com/canner/wren-engine/blob/main/docs/reference/skills.md

Outlines workflows for connecting new data sources and updating the MDL after changes, using Wren CLI commands.

```bash
wren profile add → wren context init → build → index
```

```bash
wren context validate → wren context build → wren memory index
```

--------------------------------

### Verify Wren Engine Installation

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Confirms that the Wren Engine CLI has been installed successfully by checking its version.

```bash
wren version
```

--------------------------------

### Add jaffle-shop Profile from YAML File

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

Create a YAML file containing the database connection details and import it to add the jaffle-shop profile. Ensure the 'url' points to the jaffle_shop_duckdb directory.

```bash
wren profile add jaffle-shop --from-file jaffle-profile.yml
```

--------------------------------

### Example YAML Output for Dump

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/memory.md

This is an example of the YAML format used when exporting NL-SQL pairs with `wren memory dump`.

```yaml
version: 1
exported_at: "2026-04-08T10:30:00+00:00"
pairs:
  - nl: "monthly revenue by product category"
    sql: |
      SELECT category, SUM(revenue)
      FROM orders
      GROUP BY category
    source: user
    datasource: postgres-prod
    created_at: "2026-04-01T08:15:00+00:00"
```

--------------------------------

### Initialize a Wren Engine Project

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

Scaffold a new YAML-based MDL project by creating a project directory and running the 'wren context init' command. This sets up the necessary configuration files and directories.

```bash
mkdir my-project && cd my-project
wren context init
```

--------------------------------

### Define Business Rules in instructions.md

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/connect.md

Use the 'instructions.md' file to define business rules and query guidelines for the AI agent. These rules are loaded at session start.

```markdown
## Naming conventions
- "revenue" always means net_total, not gross_total
- "active customers" = customers with at least one order in the last 90 days

## Query rules
- Always filter by status = 'completed' unless explicitly asked for all statuses
- Use order_date for time-based filtering, not created_at
```

--------------------------------

### Install Wren Engine with PostgreSQL Support

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs the Wren Engine with additional support for PostgreSQL. Use this command when you need to connect to a PostgreSQL database.

```bash
pip install "wren-engine[postgres,main]"
```

--------------------------------

### Jaffle Shop Relationships Example (YAML)

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/relation.md

An example of defining multiple relationships across different model layers in the jaffle_shop workspace using YAML.

```yaml
relationships:
  # mart layer
  - name: orders_customers
    models: [orders, customers]
    join_type: MANY_TO_ONE
    condition: orders.customer_id = customers.customer_id

  # raw layer
  - name: raw_orders_raw_customers
    models: [raw_orders, raw_customers]
    join_type: MANY_TO_ONE
    condition: raw_orders.user_id = raw_customers.id

  - name: raw_payments_raw_orders
    models: [raw_payments, raw_orders]
    join_type: MANY_TO_ONE
    condition: raw_payments.order_id = raw_orders.id

  # staging layer
  - name: stg_orders_stg_customers
    models: [stg_orders, stg_customers]
    join_type: MANY_TO_ONE
    condition: stg_orders.customer_id = stg_customers.customer_id

  - name: stg_payments_stg_orders
    models: [stg_payments, stg_orders]
    join_type: MANY_TO_ONE
    condition: stg_payments.order_id = stg_orders.order_id
```

--------------------------------

### MDL Validation and Deployment Parameters

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

These code examples show the parameters used for validating and deploying an MDL manifest. They include catalog, schema, data source, and the models themselves. The 'wren-generate-mdl' skill uses these to create and apply the manifest.

```json
mdl_validate_manifest({"catalog":"wren","schema":"public",
           "dataSource":"POSTGRES","models":[]})
```

```json
deploy_manifest({"catalog":"wren","schema":"public","dataSource":"POSTGRES","models":[]})
```

--------------------------------

### Validate and Build Project

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/wren_project.md

After initializing or upgrading a project, validate its configuration and then build it. These commands ensure the project is correctly set up and ready for use.

```bash
wren context validate --path my_project
```

```bash
wren context build --path my_project
```

--------------------------------

### Start Server on Custom Port

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/docs/development.md

Starts the Wren Engine server on a specified port. Change the default port by prefixing the run command with 'port=PORT_NUMBER'.

```shell
just port=8001 run
```

```shell
just port=8001 dev
```

--------------------------------

### Initialize Salesforce Pipeline

Source: https://github.com/canner/wren-engine/blob/main/skills/wren-dlt-connector/references/dlt_sources.md

Python script to set up a dlt pipeline for Salesforce data. Ensure Salesforce credentials are configured in dlt secrets.

```python
import dlt
from salesforce import salesforce_source

pipeline = dlt.pipeline(
    pipeline_name="salesforce",
    destination="duckdb",
    dataset_name="salesforce_data",
)

source = salesforce_source()
info = pipeline.run(source)
print(info)
```

--------------------------------

### Add Database Profile from File

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/connect.md

Create a new database connection profile named 'my-db' by importing connection details from a JSON or YAML file named 'connection.json'.

```bash
wren profile add my-db --from-file connection.json
```

--------------------------------

### Start Java Engine for Rewriting Queries

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Starts the Java engine using Docker Compose, which is necessary for the rewriting-queries feature when running the Ibis Server locally.

```bash
cd example
docker compose --env-file .env up
```

--------------------------------

### Useful Commands Reference

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/quickstart.md

A reference table of common Wren commands for running SQL, previewing plans, validating, managing context, and interacting with memory.

```bash
wren --sql "SELECT ..." -o table
```

```bash
wren dry-plan --sql "SELECT ..."
```

```bash
wren dry-run --sql "SELECT ..."
```

```bash
wren context show
```

```bash
wren context instructions
```

```bash
wren context build
```

```bash
wren memory fetch --query "..."
```

```bash
wren memory recall --query "..."
```

```bash
wren memory store --nl "..." --sql "..."
```

```bash
wren memory status
```

```bash
wren memory index
```

```bash
wren profile switch <name>
```

```bash
wren profile list
```

--------------------------------

### Run Tests with Development Dependencies

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/docs/development.md

Installs dependencies including development tools and runs the test suite. Use 'just test <marker>' to run specific tests.

```shell
just install --with dev
```

```shell
just test
```

```shell
just test postgres
```

--------------------------------

### Start Spark Cluster for Local Testing

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Starts a local Spark cluster using Docker Compose, required for running Spark-related tests. Ensure Spark Connect is enabled.

```bash
cd tests/routers/v3/connector/spark
docker compose up -d --build
```

--------------------------------

### Project Structure after Initialization

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/wren_project.md

This is the typical directory and file structure created after initializing a project from an MDL JSON file.

```text
my_project/
├── wren_project.yml          # catalog, schema, data_source from the manifest
├── models/
│   ├── orders/
│   │   └── metadata.yml      # one directory per model
│   └── customers/
│       └── metadata.yml
├── views/
│   └── top_customers/
│       └── metadata.yml      # one directory per view
├── relationships.yml
└── instructions.md
```

--------------------------------

### Deploy an MDL file using MCP tool

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

Example of how to deploy an existing MDL JSON file using the MCP tool. The `mdl_file_path` should point to the file within the mounted workspace.

```python
deploy(mdl_file_path="/workspace/my_mdl.json")
```

--------------------------------

### Get Available SQL Functions for Postgres

Source: https://context7.com/canner/wren-engine/llms.txt

Retrieve a list of available SQL functions for a PostgreSQL data source via the ibis-server REST API. This is a simple GET request.

```bash
curl -X GET "http://localhost:8000/v3/connector/postgres/functions"
```

--------------------------------

### WrenEngine.init

Source: https://github.com/canner/wren-engine/blob/main/wren-core-wasm/README.md

Initializes the Wren Engine and loads the WASM binary. This is the first step before using any other engine methods.

```APIDOC
## WrenEngine.init(options?)

### Description
Initialize the engine and load the WASM binary.

### Method
`static async init(options?: WrenEngineOptions): Promise<WrenEngine>`

### Parameters
#### Query Parameters
- **options** (WrenEngineOptions) - Optional - Configuration options for initialization.
  - **wasmUrl** (string | URL | BufferSource) - WASM binary source. Defaults to sibling `wren_core_wasm_bg.wasm` via `import.meta.url`.

### Response
#### Success Response (200)
- **WrenEngine** - An instance of the initialized WrenEngine.
```

--------------------------------

### Install and Activate Virtual Environment with uv

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

Commands to create a Python virtual environment using uv and activate it. This is the first step in setting up the Python environment for the Wren MCP Server.

```bash
> uv venv
Using CPython 3.11.11
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
> source .venv/bin/activate   
> uv run app/wren.py
Loaded MDL etc/mdl.json
Loaded connection info etc/pg_conneciton.json
```

--------------------------------

### Install Wren Engine Skills for a Specific Agent

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs Wren Engine skills and targets a specific AI agent, such as Claude Code. Use this to ensure compatibility with your chosen AI coding assistant.

```bash
npx skills add Canner/wren-engine --skill '*' --agent claude-code
```

--------------------------------

### Install Wren Engine Skills via npx

Source: https://github.com/canner/wren-engine/blob/main/docs/get_started/installation.md

Installs all available Wren Engine skills for AI coding agents using npm. This command is recommended for users who prefer managing Node.js packages.

```bash
npx skills add Canner/wren-engine --skill '*'
```

--------------------------------

### Wren Python Interactive Session Example

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/README.md

Demonstrates how to interact with the Wren session in Python after launching the interactive mode. Shows executing a SQL query and printing results.

```python
task = wren.sql('SELECT * FROM your_table').execute()
print(task.results)
print(task.formatted_result())
```

--------------------------------

### Get Specific Function Details for Postgres

Source: https://context7.com/canner/wren-engine/llms.txt

Retrieve details for a specific SQL function, such as 'date_trunc', from a PostgreSQL data source using the ibis-server REST API. This is a GET request specifying the function name.

```bash
curl -X GET "http://localhost:8000/v3/connector/postgres/function/date_trunc"
```

--------------------------------

### Get Planned SQL for Specific Data Source Dialect

Source: https://context7.com/canner/wren-engine/llms.txt

Send a SQL query and manifest string to the ibis-server to get the planned SQL for a specific data source dialect, such as Snowflake. Ensure the 'manifestStr' is correctly formatted.

```bash
curl -X POST "http://localhost:8000/v3/connector/snowflake/dry-plan" \
  -H "Content-Type: application/json" \
  -d '{
    "sql": "SELECT DATE_TRUNC(month, order_date) as month, SUM(amount) FROM orders GROUP BY 1",
    "manifestStr": "..."
  }'
```

--------------------------------

### SQL for ref_sql Model

Source: https://github.com/canner/wren-engine/blob/main/docs/guide/modeling/wren_project.md

Example of a separate SQL file used for `ref_sql` in a model definition.

```sql
-- models/revenue_summary/ref_sql.sql
SELECT DATE_TRUNC('month', order_date) AS month,
       SUM(total) AS total_revenue
FROM orders
GROUP BY 1
```

--------------------------------

### Switch and Use a Profile

Source: https://github.com/canner/wren-engine/blob/main/wren/README.md

Switch to a specific profile and then use it for subsequent commands. The `--sql` flag allows direct SQL queries.

```bash
wren profile switch prod
```

```bash
wren --sql 'SELECT COUNT(*) FROM "orders"'
```

--------------------------------

### Configure Wren MCP Server

Source: https://github.com/canner/wren-engine/blob/main/mcp-server/README.md

This JSON configuration sets up the MCP server for the Wren engine. Ensure the 'command' points to the 'uv' executable and 'args' specify the correct directory and script. Environment variables like WREN_URL, CONNECTION_INFO_FILE, and MDL_PATH should be set appropriately.

```json
{
    "mcpServers": {
        "wren": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/wren-engine/mcp-server",
                "run",
                "app/wren.py"
            ],
            "env": {
                "WREN_URL": "localhost:8000",
                "CONNECTION_INFO_FILE": "/path-to-connection-info/connection.json",
                "MDL_PATH": "/path-to-mdl/mdl.json"
            },
            "autoApprove": [],
            "disabled": false
        }
    }
}
```

--------------------------------

### Define One-to-Many Relationship in MDL

Source: https://context7.com/canner/wren-engine/llms.txt

Example of defining a ONE_TO_MANY relationship between 'customers' and 'addresses' in an MDL file.

```yaml
  - name: customers_addresses
    models:
      - customers
      - addresses
    join_type: ONE_TO_MANY
    condition: customers.customer_id = addresses.customer_id
```

--------------------------------

### Postgres Testcontainer Fixture

Source: https://github.com/canner/wren-engine/blob/main/ibis-server/docs/how-to-add-data-source.md

Use testcontainers-python to create a fixture for a PostgreSQL container, simplifying test setup.

```python
import pytest
from testcontainers.postgres import PostgresContainer

@pytest.fixture(scope="module")
def postgres(request) -> PostgresContainer:
    pg = PostgresContainer("postgres:16-alpine").start()
    request.addfinalizer(pg.stop)
    return pg
```

--------------------------------

### Invoke Wren Engine Skills

Source: https://github.com/canner/wren-engine/blob/main/skills/SKILLS.md

After installation, skills can be invoked directly in your AI client using their respective commands.

```bash
/wren-usage
```

```bash
/wren-generate-mdl
```