> ## 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.

# Lightdash

Lightdash connects to Honeydew via JDBC connection, using the **Trino** protocol.

## Metadata Sync

With Metadata Sync, Honeydew can synchronize metadata such as field definitions and descriptions to Lightdash.
This allows users to see in Lightdash all attributes and metrics that are available in Honeydew.

### Setting up a new dbt project for Lightdash

1. Create a new repository in your git provider, or use an existing repository

2. Create a new dbt project in the repository, or use an existing dbt project
   Here's a sample empty `dbt_project.yml` file, if starting a new dbt project:
   ```yaml theme={null}
   name: 'tpch_demo'

   config-version: 2
   version: '0.1'

   model-paths: ["models"]
   seed-paths: ["seeds"]
   test-paths: ["tests"]
   analysis-paths: ["analysis"]
   macro-paths: ["macros"]

   target-path: "target"
   clean-targets:
       - "target"
       - "dbt_modules"
       - "logs"

   require-dbt-version: [">=1.0.0", "<2.0.0"]
   ```

3. Create a folder named `models` in the repository, in same folder as `dbt_project.yml`

4. Create a new empty model sql file in the `models` folder, matching the domain you're exporting from Honeydew (for example `mydomain.sql`)

5. Create a new empty model yaml file in the `models` folder, matching the domain you're exporting from Honeydew (for example `mydomain.yml`)

6. In Honeydew, go to **Branch integrations** -> **Lightdash** -> **Export to Lightdash** and copy the displayed content

7. Paste the content into the model yaml file (e.g. `mydomain.yml`)

8. Commit and push the changes to the git repository

<Note>
  If no domain is selected, the default domain is called `world`.
</Note>

## Setting up a Warehouse connection in a Lightdash project

Each Lightdash project is mapped to a Honeydew workspace and branch.

<Tip>
  If you would like to use multiple Honeydew domains, you can create them as multiple models in the dbt project.
</Tip>

<Tip>
  It is recommended to use an [API Key](/docs/access-control/api-keys) for setting up the connection.
</Tip>

<Steps>
  <Step title="Create project">
    Create a new project and give it a name
  </Step>

  <Step title="Warehouse connection">
    1. Set **Trino** as **Type**
    2. Set **Host** to `jdbc.honeydew.cloud`
    3. Set **Username** to the API key (or a Honeydew username), and **Password** to the API secret
    4. Set **DB name** to `<workspace>__<branch>` value, based on the Honeydew `workspace` and `branch` you would like to connect to.
       Omit the branch value if connecting to `prod`.
       For example, for workspace `tpch`, branch `prod`, the value would be: `tpch`.
       And for workspace `tpch`,  branch `dev`, it would be `tpch__dev`.
       (or to the user's password in Honeydew).
    5. In **Advanced configuration options**, set **Port** to `443` and **SSL mode** to `https`
    6. Click **Save**

    <Note>
      If your organization uses a custom hostname for the JDBC connection,
      you can locate it in the Honeydew UI, under the **JDBC** section in **Settings**.
    </Note>
  </Step>

  <Step title="dbt connection">
    1. Choose your git provider
    2. Choose the preferred dbt version
    3. Provide the additional details required for the git provider
    4. Provide the repository name - the name of the repository where the dbt project is located
    5. Provide the branch name which contains the version of the dbt project you would like to use
    6. Provide the project directory path of your dbt project in the repository
    7. Target name - can be left empty
    8. Provide the name for the schema - similar to the name of the dbt model generated by Honeydew
  </Step>

  <Step title="Test and deploy">
    Click **Test and deploy project**
  </Step>
</Steps>

### Models selection

If you have multiple models in the dbt project, you will be asked to select the models to use in Lightdash.
Select the model(s) you have imported from Honeydew for this project.

<Tip>
  If you would like to use multiple Honeydew domains, you can create them as multiple models in the dbt project.
</Tip>

### Metadata Sync

Honeydew automatically converts Honeydew metadata properties to Lightdash metadata properties.

Honeydew synchronizes the following metadata to Lightdash:

* Fields - every attribute is defined as a Lightdash dimension, and every metric as a Lightdash measure.
* Field data types.
* Field display names (to `label` Lightdash field property). When no display name is set, Honeydew creates an automatic user friendly name.
* Field folders (to `groups` and `group_details` Lightdash properties). When no folder is set, Honeydew uses the entity name as folder names.
* Measure types (to `type` Lightdash measure property). Note that Honeydew can support any SQL aggregation function as a measure, hence
  the measure type is not always a direct mapping to Lightdash measure types.
* Field hidden property (to `hidden` Lightdash field property).
* Field descriptions (to `description` Lightdash field property).

In addition, the following metadata properties are also synchronized:

#### Lightdash-specific Metadata

**Attributes and Metrics**: You can add Lightdash-specific metadata that specifies
formatting and a url.

For [metrics](/docs/calculations/metrics#yaml-schema) and
[calculated attributes](/docs/calculations/attributes#yaml-schema),
add it to the field's own YAML file:

```yaml theme={null}
...
metadata:
  - name: lightdash
    metadata:
      - name: format
        value: '0.00%'
      - name: url_label
        value: 'Open in CRM'
      - name: url
        value: 'https://example.com/myurl?value=${ value }'
```

For [dataset attributes](/docs/modeling/source-data#yaml-schema), add the metadata under
the attribute entry in the dataset's YAML file:

```yaml theme={null}
...
attributes:
  ...
  - column: <src column name>
    name: <attribute name>
    ...
    metadata:
      - name: lightdash
        metadata:
          - name: format
            value: '0.00%'
```

* For additional information on **formatting**, see Lightdash documentation for [dimensions](https://docs.lightdash.com/references/dimensions#format) and
  [metrics](https://docs.lightdash.com/references/metrics#format) formatting.

  It is recommended to use [https://customformats.com/](https://customformats.com/) to help you building format expressions.

* For additional documentation on **urls**, see the [Lightdash documentation](https://docs.lightdash.com/references/dimensions#urls).

### Using Honeydew semantic model in Lightdash

You can now run queries or create dashboards on top of the Honeydew connection, using the Lightdash user interface.