migrate-from-cube

Files (1)

• SKILL.md

SKILL.md (first lines)

# Migrate from Cube.js

You are converting Cube.js schema files into airlayer `.view.yml` files. Each Cube.js cube becomes one `.view.yml` file.

## Step 1: Identify the schema files

Cube.js schemas can be in two formats. Read all the cube files and identify which format they use:

**JavaScript format** (`.js` files in `schema/` or `model/cubes/`):

```js
cube(`orders`, {
  sql_table: `public.orders`,
  dimensions: { ... },
  measures: { ... },
  joins: { ... },
})
```

**YAML format** (`.yml` files in `model/cubes/`):

```yaml
cubes:
  - name: orders
    sql_table: public.orders
    dimensions: ...
    measures: ...
    joins: ...
```

> **YAML vs JS naming:** Cube.js YAML uses camelCase measure types (`countDistinct`, `countDistinctApprox`, `avg`) while JS uses snake_case (`count_distinct`, `avg`). Both mean the same thing — map them identically.

Read ALL cube files before starting to write any `.view.yml` — you need the full picture to correctly translate joins into entity pairs.

## Step 2: Plan entity translations

Joins are the most important thing to get right. airlayer uses **entities** on both sides of a join — the entity `name` must match on both views for airlayer to auto-generate the JOIN.

For each join in the Cube.js schema, parse the join SQL to find the FK and PK columns:

**Cube.js join (declared on the FK side / "owning" cube):**

```js
joins: {
  customers: {
    relationship: `many_to_one`,
    sql: `${CUBE}.customer_id = ${customers}.id`,
  },
},
```

**Translation:**

- The LHS column (`customer_id`) → `foreign` entity on `orders`
- The RHS column (`id`) → `primary` entity on `customers`
- Pick a shared entity name based on the concept: use the joined cube name (`customer`)

```yaml
# orders.view.yml
entities:
  - name: customer
    type: foreign
    key: customer_id

# customers.view.yml
entities:
  - name: customer
    type: primary
    key: id
```

**Entity naming rules:**

- Use the joined cube name as the entity name (e.g., join to `customers` → entity name `customer`)
- For `one_to_many` joins (the owning side has the PK): entity is `primary` on the owning cube, `foreign` on the target
- For `many_to_one` joins (the owning side has the FK): entity is `foreign` on the owning cube, `primary` on the target
- Entity names MUST match exactly across views — `customer` ≠ `Customer`
- A cube can have multiple entity declarations (one per relationship)

**Critical: `key`/`keys` must reference dimension names, not column names.**

airlayer validates that entity keys match the `name:` of a dimension in the same view — NOT the raw column name in `expr:`. If your dimension is named `store_id` with `expr: Store`, the entity key must be `store_id`, not `Store`.

```yaml
# WRONG — 'Store' is a column name, not a dimension name
entities:
  - name: store
    type: primary
    keys: ["Store", "Date"]       # ✗ validator error

# CORRECT — use the dimension names defined in the same view
entities:
  - name: store
    type: primary
    keys: ["store_id", "week_date"]   # ✓ matches dimension name fields

# For single-column keys, use key: (not keys:)
entities:
  - name: store
    type: primary
    key: store_id                 # ✓
```

Build a table mapping `(cube_name, entity_name) → (type, key)` for all joins before writing any files.

## Step 3: Translate each cube

For each cube, create a `.view.yml` file in the project directory.

### Table name

```js
sql_table: `public.orders`   →   table: public.orders
sql: `SELECT * FROM orders WHERE active = true`  →  table: "(SELECT * FROM orders WHERE active = true)"
```

For cubes using `sql:` (a subquery), wrap the value in quotes as the `table:` value.

### Dimensions

From oxy-hq/airlayer, Apache-2.0.

More from oxy-hq/airlayer