relation-creation

Files (3)

• SKILL.md
• examples.md
• reference.md

SKILL.md (first lines)

## Prerequisites

Before creating relations, ensure you are on the correct workspace and branch. Use `get_session_workspace_and_branch` to check the current session context. For development work, create a branch with `create_workspace_branch` (the session switches automatically). See the `workspace-branch` skill for the full workspace/branch tool reference.

---

## Overview

A Honeydew **relation** defines how two entities join together.
Relations are not standalone objects — they live inside the **source entity's YAML** as a `relations:` block.
Every relation connects the "many" side to the "one" side: for example, `orders` (many) → `customers` (one).

Relations enable:

- Metrics on one entity to reference attributes from another
- Cross-entity calculated attributes (Multi-Entity type)
- Filter propagation between entities in BI queries

> Relations are defined on the source entity. To add a relation, use `update_object` on the entity that holds the foreign key (the "many" side).

---

## Creation Methods

### Primary: update_object on the Source Entity

There is no `create_relation` tool. Adding a relation means updating the source entity's YAML to include the `relations:` block.

Call `update_object` with:

- `yaml_text` — the full updated entity YAML with the `relations:` block
- `object_key` — the entity's object key (find via `list_entities` or `get_entity`)

Required permission: Editor or higher.

### After Creation/Update: Display the UI Link

After a successful `update_object` call, the response includes a `ui_url` field. **Always display this URL to the user** so they can quickly open the object in the Honeydew application.

### Remove a Relation: update_object

There is no `delete_object` for relations. To remove a relation, update the source entity's YAML with the relation removed from the `relations:` block.

1. **Find which entity defines the relation.** The relation lives in only one entity's YAML, but it could be on either side. Use `get_entity` on both entities and check which one has the relation in its `relations:` block.
2. Remove the target relation from that entity's `relations:` list (keep all other relations intact).
3. Call `update_object` with the updated YAML and the entity's `object_key`.

---

## Decision Flow

```
Need to define a relation?
    │
    ├─► Simple FK join (equality on one or more columns)?
    │       └─► Use field-based connection
    │               connection:
    │                 - src_field: <fk_column>
    │                   target_field: <pk_column>
    │
    ├─► Complex join (range, filter, SCD Type 2, multi-entity)?
    │       └─► Use expression-based connection
    │               connection_expr:
    │                 sql: |-
    │                   <custom SQL>
    │
    └─► Removing an existing relation?
            └─► Use update_object — remove relation from entity YAML
```

---

## Examples

See [examples.md](examples.md) for full worked examples covering: field-based join, composite key, expression-based (SCD Type 2), multiple relations, many-to-many through a bridge table, and removing a relation.

For any shape these do not cover, search the Honeydew documentation with `search_docs` and `query_docs_filesystem` before improvising — it carries more relationship-modeling detail than this skill does. See [Documentation Lookup](#documentation-lookup) for what to search for.

---

## Discovery Helpers

Use these MCP tools before defining relations:

- `get_entity` — Get entity details including existing relations, attributes, and YAML definition
- `list_entities` — List all entities (to identify source and target)
- `search_model` — Search for entities or fields by name (use `search_mode: EXACT` for known names, `OR` for broad discovery)

---

See [reference.md](reference.md) for: YAML schema, relation direction (rel_type), join types, cross-filtering options, and connection methods.

---

## Finding Candidate Relations

When you arrive from the `entity-creation` skill with a freshly validated entity, or a batch of them from `import_tables`, nothing is connected yet and there is no list of joins to work from. Build one:

- **The new entity is the many side** — an FK column among its attributes points at an existing entity's key.
- **The new entity is the one side** — an existing entity holds an FK matching the new entity's key. This is the usual shape when a dimension is imported into a model that already has facts, and it is invisible if you only scan the new entity.
- **Between new entities** — when several tables arrive together, check the batch against itself.
- **Through a bridge table** — a junction table holding an FK to each side connects two entities that share no FK, so check whether a third entity points at both before calling them unrelated. If the junction table is not an entity yet, create it with the `entity-creation` skill and validate it first.
- **With no key pair at all** — a missing FK is not proof of independence. Weigh the entity's grain and its date columns; if you find an effective-dated dimension, a range join or a similar shape, it may need an expression-based connection.

Confirm the one side actually has a key — an `import_tables` entity may arrive with none, and validation checks key uniqueness, not key presence. Set the key before relating to it.

Search for the FK with `search_model` in `OR` mode, since an attribute is often renamed from the column it maps to and `EXACT` matches the attribute name only; narrow a large model with `entity.field` syntax (`orders.` returns every field of matching entities). If an entity yields no candidate at all, `get_table_info` on its source table will show whether the FK exists in the warehouse but was never mapped as an attribute.

### Role Playing vs Conformed Dimension

One entity often connects to a fact more than once in different roles — a `users` entity that is the salesperson on one relation, the support agent on another. Those roles are not the same thing, and a single shared entity makes them look like one.

- **Conformed dimension** — the same business concept meaning the same thing everywhere (one `customers` entity used by orders and by tickets). Relate all of them to the one entity.
- **Role playing** — the same table standing in for different concepts, distinguished only by which FK reaches it. Create a copy of the entity per role with the `entity-creation` skill (`sales_reps`, `support_agents`) and give each its own relation, so each role carries its own name, filters and metrics.

The tell is whether the two paths would ever be filtered or reported on together as one population. If not, it is role playing.

---

From honeydew-ai/honeydew-ai-coding-agents-plugins, Apache-2.0.

More from honeydew-ai/honeydew-ai-coding-agents-plugins