# Hex Semantic Project

Euno's Hex Semantic Project integration enables you to upload dbt MetricFlow YAML files to create semantic models and metrics that can be used in Hex's semantic layer. This integration specifically targets Hex users who utilize [Hex's Semantic Model Sync with dbt MetricFlow](https://learn.hex.tech/docs/connect-to-data/semantic-models/semantic-model-sync/dbt-metricflow).

{% hint style="info" %}
This integration is designed for Hex users who want to manage their semantic models through dbt MetricFlow and sync them with Euno for comprehensive data lineage and governance.
{% endhint %}

## How It Works

The integration processes dbt MetricFlow YAML files to:

1. **Extract Semantic Models**: Identifies semantic models with Hex-specific configuration
2. **Create Hex Resources**: Generates corresponding Hex workspace, semantic project, semantic model, dimension, and measure resources
3. **Create dbt Resources**: Generates corresponding dbt semantic model, dimension, and metric resources
4. **Establish Lineage**: Creates field-level lineage between Hex and dbt resources
5. **Process Standalone Metrics**: Handles standalone metrics that reference measures from semantic models

## Setting up Euno's Hex Semantic Project Integration

### Step 1: Access the Sources Page

1. Navigate to the **Sources** page in the Euno application.
2. Click on the **Add New Source** button.

### Step 2: General Configuration

1. **Name**: Enter a name for your Hex Semantic Project source (e.g., "Hex Semantic - Customer Analytics").
2. **Configuration Details**:
   * **Workspace ID**: Your Hex workspace ID (required)
   * **Project ID**: Your Hex semantic project ID (required)
   * **Workspace Name**: Your Hex workspace name
   * **Semantic Project Name**: The name for your semantic project in Hex
   * **Semantic Project Type**: Currently supports "dbt Metricflow" (this is the default and only supported type)

Note: to find the semantic project id navigate to the project in the data browser and copy the id from the url. For example, if the sematic project url is `https://app.hex.tech/0197ae57-d3c0-7001-b693-280fbcb78fc4/home/data/semantic-layer/semantic-project/0198ec40-77da-7004-9731-91c06ffc5c96`

The semantic project id is : `0198ec40-77da-7004-9731-91c06ffc5c96` and the workspace id is `0197ae57-d3c0-7001-b693-280fbcb78fc4`

### Step 3: Resource Cleanup Options

To keep your data relevant and free of outdated resources, Euno provides automatic **resource cleanup** options. These settings determine when a resource should be removed if it is no longer detected by a source integration. For a detailed explanation see: [Resource Sponsorship in Euno](/developer-reference/technical-concepts/resource-sponsorship-and-cleanup-in-euno.md).

* **Time-Based Cleanup (default)**: Remove resources that were last detected X days before the most recent successful source integration run (default is 7 days).
* **Immediate Cleanup**: Remove resources not detected in the most recent successful source integration run.
* **No Cleanup**: Keep all resources indefinitely, even if they are no longer detected.

### Step 4: Advanced Settings (Optional)

Click on the '**Advanced**' section to display additional configurations:

| Configuration | Description                                                                                                                                                                               |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Files Pattern | Use regular expressions to include or exclude specific YAML files. Defaults to including `.*\.yml$` and `.*\.yaml$` files. Use this to filter which files from your upload are processed. |

### Step 5: Save Configuration

Click the **Save** button, and Euno will generate a trigger key. Please copy the key and save it somewhere, as the key will disappear after copying.

## **Uploading dbt MetricFlow Files**

### Preparing Your dbt MetricFlow Files

Before uploading, ensure your dbt MetricFlow YAML files include the required Hex configuration. Only semantic models with Hex-specific metadata will be processed.

**Required file structure:**

```yaml
semantic_models:
  - name: customer_metrics
    model: ref('customer_metrics')
    config:
      meta:
        hex:
          table: analytics.prod_core.customers  # Required for Hex integration
    entities:
      - name: customer_id
        type: primary
        description: "Primary customer identifier"
      - name: account_id  
        type: foreign
        description: "Foreign key to account table"
    dimensions:
      - name: customer_name
        type: categorical
    measures:
      - name: total_revenue
        agg: sum
        expr: revenue
        create_metric: true
```

**Key requirements:**

1. **dbt\_project.yml**: Must be included in your upload
2. **Hex Configuration**: Semantic models must include `config.meta.hex.table` specification
3. **Table Reference**: The `hex.table` value should be in format `database.schema.table` or `schema.table`
4. **Entity Types**: Only entities with types `primary`, `unique`, `natural`, or `foreign` will be processed as Hex dimensions

### Upload Methods

#### **Manual Upload via UI**

The easiest way to upload dbt MetricFlow files is through Euno's UI:

1. Navigate to your Hex Semantic Project integration
2. Click "Upload Artifacts"
3. Upload a .zip file containing:
   * `dbt_project.yml` (required)
   * YAML files with semantic models and metrics
   * Any other dbt MetricFlow YAML files

#### **Programmatic Upload (Recommended for Production)**

For production workflows, use the trigger URL to programmatically upload files after dbt builds:

To programmatically upload the files for production workflows, see reference implementations below:

#### **Python Script**

Use a standalone Python script to upload your files [→ View Python Upload Guide](/sources/transformation-etl/dbt-core/python-upload.md)

## Features

### Semantic Model Discovery

The integration automatically discovers and processes:

* **Semantic Models**: With Hex configuration (`config.meta.hex`)
* **Dimensions**: Categorical, time, entity, boolean, and numeric dimensions
* **Entities**: Primary, unique, natural, and foreign key entities (converted to dimensions in Hex)
* **Measures**: Sum, count, count distinct, average, min, max, median, and sum boolean measures
* **Standalone Metrics**: Simple metrics that reference measures from semantic models

### Resource Creation

For each valid semantic model, the integration creates:

**Hex Resources:**

* Hex Workspace (container for all semantic projects)
* Hex Semantic Project (container for semantic models)
* Hex Semantic Model (the main semantic model resource)
* Hex Dimensions (individual dimension resources)
* Hex Measures (individual measure resources, including those from standalone metrics)

**dbt Resources:**

* dbt Semantic Model (corresponding dbt resource)
* dbt Dimensions (individual dimension resources)
* dbt Metrics (for measures with `create_metric: true` and standalone metrics)

### Lineage and Dependencies

The integration establishes comprehensive lineage:

* **Table-level**: Hex semantic models reference corresponding dbt semantic models
* **Field-level**: Hex dimensions and measures reference their corresponding dbt dimensions and metrics
* **Cross-platform Integration**: Integrates with Euno's existing lineage for end-to-end dependency tracking

For detailed information about all discovered resources, see: [Hex Semantic Project Discovered Resources](/sources/analytics-notebooks/hex-semantic-project/hex-semantic-project-discovered-resources.md)

## Related Integrations

* [**Hex Technologies**](/sources/analytics-notebooks/hex-technologies.md): For general Hex project and workspace discovery
* [**dbt Core**](/sources/transformation-etl/dbt-core.md): For comprehensive dbt resource discovery and lineage


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.euno.ai/sources/analytics-notebooks/hex-semantic-project.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.