Domain Creation

## Prerequisites

Before creating domains, 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 **domain** is a lightweight governance object that defines a scoped business context over the semantic model.

Domains control:

- **Which entities** are visible (and optionally which fields within them via field selectors)
- **Semantic filters** (`filters`) — applied to every query in the domain, for governance and access control
- **Source filters** (`source_filters`) — applied early at the source level, for performance optimization

Domains are the primary mechanism for creating focused, governed views of the model for specific teams, use cases, or analysis contexts.

> This skill focuses on domain creation and management.
> Use `entity-creation` to create entities and `attribute-creation` / `metric-creation` to add fields before scoping them into a domain.
> To expose a domain for AI analysis, create an agent referencing it using `create_agent` (MCP agent tools) or the Honeydew Studio agent builder.

---

## Creation Method

### create_object with YAML

Domains are created using `create_object` with domain YAML. There is no specialized `create_domain` tool.

Parameters:

- `yaml_text` — YAML defining the domain

Required permission: Editor or higher.

### Update: update_object

1. Use `search_model` (with `search_mode: EXACT`) to find the domain's `object_key`.
2. Call `update_object` with the full updated YAML (`yaml_text`) and the `object_key`.

> **Minimal diff rule:** When updating, preserve the existing field order and formatting from the current YAML. Only change the fields you need to modify.

### Delete: delete_object

1. Use `search_model` (with `search_mode: EXACT`) to find the domain's `object_key`.
2. Call `delete_object` with that `object_key`.

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

After a successful `create_object` or `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.

---

## Decision Flow

```text
Need to create a domain?
    │
    ├─► Which entities should be included?
    │       └─► Use list_entities / search_model (OR mode) to discover available entities
    │
    ├─► Should all fields be visible, or only a subset?
    │       ├─► All fields → omit fields for that entity
    │       └─► Subset → use field selectors (supports wildcards and exclusions)
    │
    ├─► Are governance/access filters needed (apply to ALL queries)?
    │       └─► Use filters (semantic) with name + sql
    │
    └─► Are performance/source-level filters needed (apply only when entity is queried)?
            └─► Use source_filters with name + sql
```

---

## Examples

See [examples.md](examples.md) for full worked examples covering: basic entity selection, semantic filters, source filters, field selectors, deep analysis context and update/delete.

---

## Discovery Helpers

Use these MCP tools before creating domains:

- `list_entities` — List all entities in the model to decide which to include
- `get_entity` — Get detailed info for a specific entity (attributes, metrics, relations)
- `list_domains` — List all existing domains in the model
- `get_domain` — Get detailed info for a specific domain (entities, filters, parameters)
- `search_model` — Search for entities, fields, domains, or other objects by name (use `search_mode: EXACT` for known names, `OR` for broad discovery)
- `get_field` — Get detailed info about a specific field (attribute or metric)

---

See [reference.md](reference.md) for: full YAML schema, entity selection syntax, field selectors, filter types and syntax, and parameter overrides.

---

## Documentation Lookup

Use the `honeydew-docs` MCP tools to search the Honeydew documentation when:

- You need to understand governance concepts, domain design patterns, or access control strategies
- The user asks about the difference between semantic filters and source filters, or when to use each
- You need guidance on advanced modeling configurations like parameter overrides or complex field selectors
- The user asks about how domains interact with BI tools, queries, or the deep analysis API
- The user needs advanced modeling patterns for governance or multi-tenant access control

Search for topics like: "domains", "governance", "filters", "field selectors", "access control", "source filters".

---

## Best Practices

- **Name domains after the business context**, not technical details. `sales_analytics` is better than `filtered_orders_v2`.
- **Start broad, then narrow.** Include all relevant entities first, then add filters and field selectors as governance requirements emerge.
- **Always set `owner`** to identify the responsible team or person for governance and accountability.
- **Prefer semantic filters (`filters`) over source filters** for governance rules. Source filters apply before computation and can change calculated values.
- **Use source filters for performance** — they're ideal for partition pruning on large datasets.
- **Use `description`** to document the domain's purpose and intended audience clearly.
- **Keep domains focused.** A domain for "Sales Team" should only include entities and fields relevant to sales analysis.
- **Use field selectors sparingly.** Only restrict fields when there's a clear governance need (e.g. hiding PII from certain teams).
- **All filter `sql` references must be fully qualified.** Always use `entity.field` notation — unqualified references fail validation.

---

## MANDATORY: Validate After Creating

**After creating ANY domain, you MUST invoke the `validation` skill to test and validate that it works correctly.**

See `validation` skill for the full domain validation workflow.

### Validation steps:

1. **Verify domain exists** using `search_model` (with `search_mode: EXACT`) to find the new domain by name.

2. **Test with a query** — use `get_data_from_fields` with the `domain` parameter:

- `metrics`: `["<entity>.count"]`
- `domain`: `"<domain_name>"`

This verifies that the domain settings (e.g. filter) apply.