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.

Domains can also extend one or more parent domains (extends), inheriting and building on their configuration. This lets you compose reusable base domains into specialized, team- or use-case-specific views. See Domain Hierarchy below.

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

Need to create a domain?
    │
    ├─► Does an existing domain already define most of what you need?
    │       ├─► Yes, and you WANT to track it → extend it with `extends:` and override only
    │       │        the differences (see Domain Hierarchy). Note: extending creates a live
    │       │        dependency — future changes to the parent are automatically inherited by
    │       │        your domain. Extend when that shared evolution is desirable; define a
    │       │        standalone domain if you need to be insulated from the parent's changes.
    │       └─► No  → define a standalone domain (and consider whether it should become a reusable base)
    │
    ├─► 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

Domain Hierarchy

A domain can extend one or more parent domains using the extends field, inheriting their configuration and overriding only what differs. This is the recommended way to avoid duplicating entity selections, filters, and governance settings across related domains.

type: domain
name: sales_us
extends:
  - base_sales        # inherit everything from base_sales
filters:
  - name: us_region   # add a child-specific filter
    sql: customers.country = 'US'

What gets inherited

A child inherits from each parent: entities (and their field selections), semantic and source filters, parameters, tags, labels (additive), and all metadata sections.

How items merge

List items are matched by name (tags by key, metadata sections by name):

• Scalar fields (e.g. a filter's sql) defined in the child replace the parent's value.
• Collection fields (e.g. an entity's fields) defined in the child extend the inherited list — child field selectors apply on top of the inherited field list.
• Labels are additive — child labels are appended to parent labels.
• To drop something inherited, add the item with merge: remove (works for entities, filters, source_filters, parameters, and tags).

Multiple inheritance

List several parents under extends. Parents are evaluated left-to-right: if more than one parent defines the same item, the rightmost parent wins, and the child overrides all parents. This enables a mixin pattern — e.g. a base data model plus separate security and performance mixins composed into one domain.

When to use a hierarchy

• When multiple domains share entities, fields, filters, or governance settings, factor the common configuration into a base domain and have the others extend it, rather than duplicating it.
• When a domain is a narrowed or restricted variant of another — adding filters, hiding fields, or removing entities — extend the broader one and override only the differences.
• When you want related domains to stay in sync from a single source of truth, so a change made once in the base propagates to everything that extends it.

Trade-off: extending a domain creates a live dependency on the parent's implementation — any future change to the parent (entities, fields, filters, parameters) is automatically inherited by every domain that extends it. This is exactly what you want when domains should evolve together from a single source of truth, but it means a parent edit can change child behavior unexpectedly. If a domain must stay stable regardless of how others change, define it standalone instead of extending.

See reference.md for the full inheritance rules and examples.md for worked hierarchy examples.

Examples

See examples.md for full worked examples covering: basic entity selection, semantic filters, source filters, field selectors, deep analysis context, domain hierarchy (extends / multiple inheritance), 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 for: full YAML schema, entity selection syntax, field selectors, filter types and syntax, and parameter overrides.

Documentation Lookup

Use the search_docs and query_docs_filesystem tools from the honeydew MCP server 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
• The user asks about domain hierarchy / inheritance (extends), merge precedence, or composing base domains and mixins

Search for topics like: "domains", "domain hierarchy", "governance", "filters", "field selectors", "access control", "source filters". The recipes/domain-hierarchy page has a full worked five-domain hierarchy example.

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).
• Factor shared configuration into a base domain. When several domains share entities, filters, or governance settings, define a reusable base domain and extends it rather than copying YAML. Override only the differences in the child.
• Keep base domains generic and mixins single-purpose. A base holds the common data model; security and performance concerns make good standalone mixins composed via multiple inheritance.
• 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.