> ## Documentation Index
> Fetch the complete documentation index at: https://honeydew.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspaces

A **Workspace** in Honeydew represents a completely separate semantic model.
Each workspace operates independently, providing isolation
between different business contexts or organizational units.

## When to Create New Workspaces

Create separate workspaces when you need **complete semantic separation** between different business contexts.

Key scenarios are:

* **Organizational Separation**: when different departments need completely separate semantic models without any possibility
  of cross-department model or data access. For example, HR analytics workspace vs. Product analytics workspace.

* **Business Unit Separation**: when you have distinct business units within your organization,
  that should never share semantics or data connections.

* **Regulatory or Compliance Requirements**: when legal or compliance requirements mandate
  complete separation of data and semantics.

* **Trial or Evaluation Environments**: when you want to create a completely isolated temporary environment
  for testing or evaluation purposes of a new concept or technology.

<Tip>
  **Workspace vs. Domain**

  While both workspaces and [domains](/domains) provide separation,
  they serve different purposes and operate at different levels:

  | Feature            | Workspace                                  | Domain                                         |
  | ------------------ | ------------------------------------------ | ---------------------------------------------- |
  | **Semantic Model** | Completely separate                        | Shared between domains                         |
  | **Data Sources**   | Possibly independent sources               | Same source, different access roles            |
  | **Access Control** | Separate permissions                       | Shared permissions                             |
  | **Use Case**       | Complete isolation at semantic layer level | Isolation and separation within AI or BI tools |

  **Do not create separate workspaces** if you only need:

  * Exposing different metrics and attributes to different user groups - use [domains](/domains) instead,
    and expose different metrics/attributes in each domain, based on the use case.
  * Different data filters for different user groups - use [domains](/domains) instead with
    different data filters.
  * Different data access control for different user groups, over the same data
    * use [domains](/domains) instead, with different access roles.
  * Different environments - use the [environments](/governance/environments) feature instead.

  Only create separate workspaces when you need **complete semantic separation**.
</Tip>

## Git Repository Structure

Each workspace resides in a separate folder in the Git Repository.
For more details on the Git repository structure,
see [Git Version Control](/governance/git-version-control#git-repository-structure).

## Workspace Level Access Control

Honeydew supports workspace-level access control, allowing you to restrict user access
to specific workspaces within your organization.
With workspace-level access control, you can manage access at a fine-grained level across teams,
projects, or data domains.

### Overview

Workspace-level access control allows you to:

* Restrict users to specific workspaces only
* Use separate Snowflake configuration and credentials per workspace
* Implement semantics and data segregation between different business units
* Control access to sensitive or confidential data domains
* Maintain compliance with data governance policies

### Setup Instructions

<Note>
  To enable workspace-level access control for your organization, please contact Honeydew support at [support@honeydew.ai](mailto:support@honeydew.ai).
</Note>

**Prerequisites**:

1. **Admin Access**: You must have Admin role permissions in Honeydew
2. **Workspace Planning**: Identify which workspaces should be accessible to which users
3. **Access Requirements**: Define the specific access patterns for your organization

**Configuration Steps**:

1. **Contact Support**: Reach out to [support@honeydew.ai](mailto:support@honeydew.ai) to enable workspace-level access control
2. **Snowflake Configuration**: Ensure each workspace has the appropriate Snowflake configuration and credentials
3. **Define Access Rules**: Configure the mapping of users to their allowed workspaces. Do the same also for API keys.

## Managing Workspaces

<Tip>
  Creating, configuring or deleting workspaces requires **Admin** role permissions
</Tip>

### Creating a New Workspace

1. Navigate to your organization settings
2. Select "Create New Workspace"
3. Configure workspace-specific settings:
   * Data source connection
   * [Environment](/governance/environments) configuration
4. Assign access to the workspace to specific users
   (see [workspace-level access control](#workspace-level-access-control) for details)

### Branches and Environments per Workspace

A workspace may have multiple branches.
For example, you can have separate `prod` (production) and a `dev` (development) branch.
Each branch within a workspace is a [Git branch](/governance/git-version-control#branch-based-development).

Branches may be associated with [environments](/governance/environments).
For example, the `prod` and `dev` branches may be mapped to different Snowflake databases or warehouses.

<Warning>
  When making changes to a workspace environments, the changes are always made in the `prod` branch of the workspace,
  and will be applied to all branches based on the branch matching rules.
</Warning>

### Moving Semantics Between Workspaces

If you need to move entities or logic between workspaces, this can be done manually
by modifying the Git repository structure:

1. Checkout the relevant Git repository
2. Move the relevant files and folders between workspace directories
3. Commit and push the changes
4. In Honeydew Studio, click the "Reload all Workspaces for all users" option to refresh the workspaces

<Info>
  If you have a complex migration use case, please feel free to reach out to [support@honeydew.ai](mailto:support@honeydew.ai) for assistance
</Info>

## YAML Schema

Each workspace is defined by a YAML file in Git, which also tracks and preserves the full history of every change.

<Important>
  Workspace name in the YAML file must match the folder name in the Git repository
</Important>

The schema for workspace is:

```yaml theme={null}
type: workpsace
name: <name>
environments:
  - name: <environment name>
    branch_pattern: <branch pattern>
    snowflake:
      database: <[>database>
      schema: <schema>
      warehouse: <warehouse>
      role: <role>
  - ...
```

Fields:

* `name`: Name of workspace - must match the folder name in Git repository
* `environments`: List of environments for the workspace (see [environments](/governance/environments#yaml-schema) for details)