​
Creating Business Context

A user in Finance or Marketing on a semantic layer does not want or may not be allowed access to everything. They want to see semantics relevant to them, with their context applied. That concept is called in Honeydew a “Domain”. A Domain is a lightweight governance object that allows to build context for users, as well as maintain access control on data and on metadata. That context includes:
  1. Selection of entities and sub-selection of fields, that are accessible when using the domain
  2. Selection of filters that must be applied on every query on the domain
  3. Selection of parameter overrides that apply in the domain context

​
Selecting entities

Domain allows to select entities that participate. For example, a domain that select a subset of entities from TPCH: 
type: domain
name: orders_domain
description: Orders Tracing Domain

# Entities and fields that participate
entities:
  - name: lineitem
  - name: orders
  - name: partsupp
  - name: part

​
Filters

Domain may control how data is filtered. There are two types of filters: Semantic and Source.
AspectSemantic FiltersSource Filters
ScopeApply to all queries in a domainApply only when source entity is queried
TimingEnforced after semantic resolution, may add JOINsApplied early, directly on source tables
PurposeGovernance & access controlPerformance optimization (e.g., partitions) and removing duplicate data (with conditional filtering)
CaveatsCan slow queries by introducing extra joinsMay alter computed values due to order of filtering
Best UseConsistent rules (e.g., tenant, access filters)Performance with large/partitioned data

​
Semantic Filters

Filters within a domain apply to every query on the domain. Think of them as filters every user must add to every query. For example, 
type: domain
name: orders_domain
description: Domestic Orders Tracing Domain

# Entities and fields that participate
entities:
  - name: lineitem
  - name: orders
  - name: partsupp
  - name: part

# Semantic Filters that always apply to every query on the domain
filters:
  - lineitem.l_shipmode in ('MAIL', 'RAIL', 'TRUCK')
Semantic filters can be ad-hoc expressions (as in the example above) or reference named boolean attributes.
A semantic filter will be always added to a query in a domain context. That means that semantic filters may have a perfomrance impact when they introduce more JOINs.For example, this SQL query on the domain above that asks for part count:
SELECT AGG("part.count") FROM domains.orders_domain
will include a JOIN to lineitems even though it was not directly referenced in the query to make sure only parts that where shipped over ground are included.

​
Semantic Filters using Parameters

A common use case is filtering data based on a parameter that sets user context. For example, if:
  1. Every user operates within a tenant context
  2. Data in Snowflake is partitioned by a tenant column (in the example below in a tenant dimension dim_tenant, though can be a column in every table)
  3. Users are only allowed to see data within their own tenant
Set $TENANT user parameter, and use it as a domain filter: 
type: domain

# Entities that participate ..

filters:
 - dim_tenant.tenant_id = $TENANT
Apply the parameter in the manner appropriate for the user queries (whether it is through BI connection settings or Snowflake SET statements).
If filtering data through a filtering dimension, make sure it is cross filtering the data with a one-to-many filtering direction.

​
Source Filters

Source filters are filters that are applied at the source level (unlike semantic filters that apply to the semantic layer as a whole). The use cases for source filters are:
  1. Improving performance with logically partitioned data by always pushing filters below calculated attributes.
  2. Removing duplicated data using conditional filtering, which is common when dealing with either Multi-Grain Data or Slowly Changing Dimensions with Multiple Versions
Source filters are only supported on attributes that come from an entity source table.
A source filter is only applied if the source is part of the query. 
type: domain
name: orders_domain
description: Domestic Orders Tracing Domain

# Entities and fields that participate
entities:
  - name: lineitem
  - name: orders
  - name: partsupp
  - name: part

source_filters:
  - lineitem.l_shipdate >= '1994-01-01' and lineitem.l_shipdate < '1995-01-01'
Caution: Source filters apply before any other computation is done, which can change the values of calculated attributed. See filtering order for more details.When in doubt, use a semantic filter, not a source filter.

​
Conditional Filtering

In some case, a domain filter is desired unless the user filtered otherwise. The main use cases are:
  • Performance on large datasets - reduce the data by default unless the user has explicitly asked for more data.
  • Correctness with Slowly Changing Dimensions.
  • Correctness with Multi-Grain tables.
See Conditional Filters for more details.
Conditional Filters are usually used to reduce data at the source, thus they are typically used within source filters.

​
Interfaces

​
Domains on SQL interface

Domains are present as a flat table in the domains schema.
  • Attributes that are part of the domain are accessible as SQL columns.
  • Metrics that are part of the domain are accessible as SQL columns that can be aggregated on.
  • All filters of the domain apply (in addition to any filters in the SQL query).
See SQL interface for more details.

​
Domains as a context for dynamic datasets

A dynamic dataset can be associated with a domain. In that case, all domain configuration applies to the dynamic dataset query.

​
Snowflake access control & cost control

Domains can be configured to manage Snowflake session settings, such as by assigning a specific Snowflake role or linking a designated Snowflake warehouse to each domain.
Domain-level configuration allows you to link user access (e.g., via a BI tool, SQL interface, or the Honeydew native application) to specific data and cost governance policies.
This configuration is applied in the following scenarios:
  1. Queries executed through the Honeydew SQL interface, such as those from a BI tool
  2. Queries executed via the Honeydew Native Application
  3. Queries run from the Honeydew web user interface
If a third-party tool uses Honeydew only to compile a SQL query and executes the query independently, the domain’s Snowflake configuration will not apply to that query.
Domain-level settings take precedence over the global Snowflake configuration. Domains without specific Snowflake settings will default to the global Snowflake configuration for your Honeydew account. Set Snowflake role parameter for domain-level access control. To enable domain-level access control, configure the Snowflake role in the domain’s snowflake metadata section. Snowflake role and warehouse are optional and can be set in this section. 
...
metadata:
  - name: snowflake
    metadata:
      - name: role
        value: [role name]
      - name: warehouse
        value: [warehouse name]
Domain-level Snowflake role and warehouse configuration does not apply to any deployment actions of Dynamic Datasets as views or tables in Snowflake. They are used only for data queries executed on the domain or on dynamic datasets associated with the domain.

​
YAML Schema

Every domain is backed by a text file in git that defines it, and keeps history of every change. The schema for a domain is: 
type: domain
name: [name]
display_name: [display name]
owner: [owner]
description: |-
  [description]
labels: [...]
folder: [folder]
hidden: [True/False/Yes/No]
entities:
  - name: [entity name]
    fields:
      - name: [field name]
      - ...
    includes: [field pattern to include]
    excludes: [field pattern to exclude]
  - ...
filters:
  - [filter expression]
  - ...
source_filters:
  - [source filter expression]
  - ...
parameters:
  - name: [parameter name]
    value: [parameter value]
  - ...
short_term_aggregate_cache_ttl_seconds: [the duration for which a query result can be reused as part of the short-term aggregate cache]
metadata:
  [metadata]
Fields:
  • name: Name of domain
  • display_name, owner, description, labels, folder, hidden: Metadata
  • entities: List of entities that participate in the domain
    • name: Name of entity
    • fields: List of fields from the entity that participate in the domain
      • name: Name of field (attribute or metric)
    • includes: Optional field pattern to include
    • excludes: Optional field pattern to exclude
    • alias: Optional alias for entity
  • filters: List of semantic filters
  • source_filters: List of source filters
  • parameters (optional): List of parameters and values (override workspace values if they exist)
  • short_term_aggregate_cache_ttl_seconds (optional): Control short term aggregate caching. See Automatic Aggregate Caching.
  • metadata: Additional metadata for the domain (in addition to the examples above, see examples for AI, Tableau and Power BI)