malloy-model

Files (6)

• SKILL.md
• access-modifiers.md · reference/
• analysis-to-model.md · reference/
• bridge-tables.md · reference/
• normalized-schemas.md · reference/
• query-sources.md · reference/

SKILL.md (first lines)

<!--
Copyright (c) Credible Data Inc.
SPDX-License-Identifier: MIT
-->

# Building Malloy Models

> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.

## Getting Started (New Projects)

If no `.malloy` files exist yet, do discovery and propose a structure first, then return here to build base source and joined source files. Keep proposals and the analysis behind them in the conversation.

**File structure convention** (a flat layout at the package root is the simplest default):

```
<package-name>/
  publisher.json              # Required for publishing (name, version, description)
  customers.malloy            # Base source: one per table
  products.malloy
  orders.malloy
  user_order_facts.malloy     # Computed source
  order_analysis.malloy       # Source: one per analytical domain
  customer_health.malloy
```

Versions for new packages should start at "0.0.1".

**Before creating any files**, check for an existing `publisher.json` in the target directory. If one exists for a different package, create a new subdirectory for your package, don't overwrite another package's config.

In Publisher an environment is a project, and Publisher is single-tenant, so there is no org/tenant layer to model around: one environment holds one set of packages.

## Prior Art Dispatch

If your discovery turned up existing modeling patterns to mirror (a derived table, UNNEST joins, a review or curation pass), read the relevant reference before building.

| Pattern found in prior art        | Reference to read                                          |
| --------------------------------- | ---------------------------------------------------------- |
| Derived table (PDT/NDT)           | `skill:malloy-lookml-review` build-derived-tables guidance |
| UNNEST joins or struct access     | `skill:malloy-lookml-review` build-unnest guidance         |
| Review pass for coverage          | `skill:malloy-lookml-review` review-coverage guidance      |
| Curate pass with visibility seeds | `skill:malloy-lookml-review` curate-visibility guidance    |

## Base Source Templates

### Base Source (Simple Mode)

```malloy
source: customers is my_conn.table('sales.customers')
extend {
  primary_key: customer_id

  dimension:
    // A dimension is the lighter way to give a column a cleaner name
    order_type is `Type`
    full_name is concat(first_name, ' ', last_name)
    segment is lifetime_value ?
      pick 'enterprise' when >= 100000
      pick 'mid-market' when >= 10000
      else 'SMB'

  measure:
    customer_count is count()
}
```

> **Every `dimension:` needs `name is expr`.** A bare column name like `dimension: species` is a parse error (`unexpected '}'`, or `missing 'is' before 'measure:'` when another declaration follows). Raw columns are already usable in `group_by` / `select` without any declaration, so only add a `dimension:` when deriving or renaming a field (e.g. `revenue is price * quantity`).

### Base Source (Curated Mode with Access Modifiers)

```malloy
##! experimental.access_modifiers

source: orders is my_conn.table('sales.orders')
include {
  public:
    #(doc) Order identifier
    order_id

    #(doc) Customer who placed the order
    user_id

    #(doc) Total sale price in USD
    sale_price

    #(doc) Order creation timestamp
    created_at

  internal:
    raw_payload_json  // Verified empty via index query + user confirmation
}
extend {
  primary_key: order_id

  dimension:
    #(doc) Date the order was placed
    order_date is created_at::date

  measure:
    #(doc) Total number of orders
    order_count is count()

    #(doc) Total revenue in USD
    # currency
    revenue is sum(sale_price)
}
```

### Computed Source (from Query)

Wrap the query in parentheses and extend it. `from(...)` was removed from the language and no longer parses (`unexpected 'from'`).

```malloy
import "orders.malloy"

source: user_order_facts is (
  orders -> {
    group_by: customer_id
    aggregate:

From malloydata/publisher, MIT.

More from malloydata/publisher