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

# ADLS | Official Documentation (Hybrid Runner)

> Connect Azure Data Lake Storage to Collate with our comprehensive ADLS connector guide. Setup instructions, configuration, and metadata extraction.

![ADLS](https://docs.getcollate.io/public/images/connectors/adls.webp)

# ADLS

PROD

This page contains the setup guide and reference information for the ADLS connector.
Configure and schedule ADLS metadata workflows from the Collate UI:

* [Requirements](#requirements)
* [Metadata Ingestion](#metadata-ingestion)

## Requirements

Collate needs the following permissions in Azure Data Lake Storage:

### ADLS Permissions

To extract metadata from Azure ADLS (Storage Account - StorageV2), you will need an **App Registration** with the following permissions on the Storage Account:

* Storage Blob Data Contributor
* Storage Queue Data Contributor

### Collate Manifest

In any other connector, extracting metadata happens automatically. In this case, Collate can extract high-level
metadata from buckets, but to understand their internal structure you must provide an `openmetadata.json`
file at the bucket root.
`Supported File Formats: [ "csv",  "tsv", "avro", "parquet", "json", "json.gz", "json.zip" ]`
For more information, see [Storage Connectors](https://docs.getcollate.io/connectors/storage.md). Keep reading for an example on the shape of the manifest file.

## Collate Manifest

Our manifest file is defined as a [JSON Schema](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-spec/src/main/resources/json/schema/metadataIngestion/storage/containerMetadataConfig.json),
and can look like this:

**Entries**

**Entries**: We need to add a list of `entries`. Each inner JSON structure will be ingested as a child container of the top-level one. In this case, we will be ingesting 7 children.

**Simple Container**

**Simple Container**: The simplest container we can have would be structured, but without partitions. Note that we still need to bring information about:

* **dataPath**: Where we can find the data. This should be a path relative to the top-level container.
* **structureFormat**: What is the format of the data we are going to find. This information will be used to read the data.
* **separator**: Optionally, for delimiter-separated formats such as CSV, you can specify the separator to use when reading the file. If you don't, we will use `,` for CSV and `/t` for TSV files.

After ingesting this container, we will bring in the schema of the data in the `dataPath`.

**Partitioned Container**

**Partitioned Container**: We can ingest partitioned data without bringing in any further details.

By informing the `isPartitioned` field as `true`, we'll flag the container as `Partitioned`. We will be reading the source files schemas', but won't add any other information.

**Single-Partition Container**

**Single-Partition Container**: We can bring partition information by specifying the `partitionColumns`. Their definition is based on the [JSON Schema](https://github.com/open-metadata/OpenMetadata/blob/main/openmetadata-spec/src/main/resources/json/schema/entity/data/table.json#L232) definition for table columns. The minimum required information is the `name` and `dataType`.

When passing `partitionColumns`, these values will be added to the schema, on top of the inferred information from the files.

**Multiple-Partition Container**

**Multiple-Partition Container**: We can add multiple columns as partitions.

Note how in the example we even bring our custom `displayName` for the column `dataTypeDisplay` for its type.

Again, this information will be added on top of the inferred schema from the data files.

**Automated Container Ingestion**

**Automated Container Ingestion**: Registering all the data paths one by one can be a time consuming job, to make the automated structure container ingestion you can provide the depth at which all the data is available.

For example, suppose following is the file hierarchy within your bucket:

```
# prefix/depth1/depth2/depth3
athena_service/my_database_a/my_schema_a/table_a/date=01-01-2025/data.parquet
athena_service/my_database_a/my_schema_a/table_a/date=02-01-2025/data.parquet
athena_service/my_database_a/my_schema_a/table_b/date=01-01-2025/data.parquet
athena_service/my_database_a/my_schema_a/table_b/date=02-01-2025/data.parquet

athena_service/my_database_b/my_schema_a/table_a/date=01-01-2025/data.parquet
athena_service/my_database_b/my_schema_a/table_a/date=02-01-2025/data.parquet
athena_service/my_database_b/my_schema_a/table_b/date=01-01-2025/data.parquet
athena_service/my_database_b/my_schema_a/table_b/date=02-01-2025/data.parquet
```

All table folders containing actual data are at depth 3. When you specify `depth: 3` in the manifest entry, all following paths will get registered as containers in OpenMetadata with this single entry:

```
athena_service/my_database_a/my_schema_a/table_a
athena_service/my_database_a/my_schema_a/table_b
athena_service/my_database_b/my_schema_a/table_a
athena_service/my_database_b/my_schema_a/table_b
```

This saves effort - 1 entry instead of 4 individual entries.

**Unstructured Container**

**Unstructured Container**: OpenMetadata supports ingesting unstructured files like images, PDFs, etc. We support fetching the file names, size, and tags associated with such files.

* To ingest a **single unstructured file**: specify the full path of the file in `dataPath`
* To ingest **specific file types** (e.g., `pdf` & `png`): provide the folder name in `dataPath` and list of extensions in `unstructuredFormats`
* To ingest **all unstructured files** regardless of type: provide the folder name in `dataPath` and `["*"]` in `unstructuredFormats`

```json theme={null}
{
  "entries": [
    {
      "dataPath": "transactions/",
      "structureFormat": "csv",
      "separator": ","
    },
    {
      "dataPath": "orders/",
      "structureFormat": "parquet",
      "isPartitioned": true
    },
    {
      "dataPath": "users/",
      "structureFormat": "parquet",
      "isPartitioned": true,
      "partitionColumns": [
        {
          "name": "signup_date",
          "dataType": "DATE"
        }
      ]
    },
    {
      "dataPath": "events/",
      "structureFormat": "parquet",
      "isPartitioned": true,
      "partitionColumns": [
        {
          "name": "event_date",
          "dataType": "DATE"
        },
        {
          "name": "region",
          "dataType": "STRING"
        }
      ]
    },
    {
      "depth": 3,
      "structureFormat": "parquet"
    },
    {
      "dataPath": "reports/report.pdf"
    },
    {
      "dataPath": "documents/",
      "unstructuredFormats": ["pdf", "png", "jpg"]
    }
  ]
}
```

### Global Manifest

You can also manage a **single** manifest file to centralize the ingestion process for any container, named `openmetadata_storage_manifest.json`.

**Existing Fields**

The fields shown above (`dataPath`, `structureFormat`, `isPartitioned`, etc.) are still valid and work the same way in the global manifest.

**Container Name**

**Container Name**: Since we are using a single manifest for all your containers, the field `containerName` will help us identify which container (or Bucket in S3, etc.) contains the presented information.

Each entry in the global manifest must include a `containerName` to specify which bucket or container it belongs to.

```json theme={null}
{
  "entries": [
    {
      "containerName": "my-s3-bucket-1",
      "dataPath": "transactions/",
      "structureFormat": "csv",
      "separator": ","
    },
    {
      "containerName": "my-s3-bucket-1",
      "dataPath": "orders/",
      "structureFormat": "parquet",
      "isPartitioned": true
    },
    {
      "containerName": "my-s3-bucket-2",
      "dataPath": "users/",
      "structureFormat": "parquet",
      "isPartitioned": true,
      "partitionColumns": [
        {
          "name": "signup_date",
          "dataType": "DATE"
        }
      ]
    },
    {
      "containerName": "my-s3-bucket-2",
      "dataPath": "events/",
      "structureFormat": "json"
    }
  ]
}
```

You can also keep local manifests `openmetadata.json` in each container, but if possible, we will always try to pick up the global manifest during the ingestion.

## Metadata Ingestion

To ingest metadata from ADLS, you need to create a service connection. The service connects ADLS with Collate. Once you create a service, Collate automatically starts ingesting metadata.

### Step 1: Add New Service

Open the Services page and start a new service.

1. Navigate to **Settings** > **Services** and select the **Storage** service.

   ![Navigate to Services](https://mintcdn.com/collatedocs/uYKcw5sAfx_Tl0Ed/public/images/connectors/metadata-ingestion/classic/storage/visit-services.png?fit=max\&auto=format\&n=uYKcw5sAfx_Tl0Ed\&q=85\&s=e4f27f12286fdcd6fb6c493d5a145dd3)

2. Click **Add New Service**.

   ![Add New Service](https://mintcdn.com/collatedocs/uYKcw5sAfx_Tl0Ed/public/images/connectors/metadata-ingestion/classic/storage/add-new-service.png?fit=max\&auto=format\&n=uYKcw5sAfx_Tl0Ed\&q=85\&s=df60de57815d6777e0c96b441f440961)

### Step 2: Select a Service and Connector

From the service type dropdown, select **Storage Services**, then click the **ADLS** connector tile.

![Select Service](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/Storage/select-service/adls.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=c24b982c9c21404a36612202715d9209)

### Step 3: Add Service Name and Description

* Enter a unique, descriptive **Service Name**. Collate identifies services by their service name. Enter a name that distinguishes this deployment from other ADLS services you are ingesting metadata from.
* Optional: Enter a **Description** for the service.

![Add New Service Name](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/Storage/service-name/adls.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=67abeb6c91426ae45a738ae72d8630e5)

> [!NOTE]
>
> **Note**: The service name can't be changed after you set it.

### Step 4: Configure Connection Options

Specify where ingestion runs, provide your source credentials, and verify the connection.

#### Select Ingestion Runner

Select an **Ingestion Runner**: the runner where the ingestion pipeline will execute.

![Add Name and Select Ingestion Runner](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/select-ingestion-runner.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=1249f828648614445e8a976ea1933487)

#### Enter Connection Details

Enter the connection details for ADLS. The right-hand panel in the UI displays inline help for each field.

![Configure Service Connection](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/Storage/connection-details/adls.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=a4ac8c8d99af3e1c9d73a84b8301785d)

* **Client ID**: This unique identifier is assigned to your Azure Service Principal App, serving as a key for authentication and authorization.
* **Client Secret**: This confidential password is associated with the Service Principal, safeguarding access to Azure resources and ensuring secure communication.
* **Tenant ID**: Identifying your Azure Subscription, the Tenant ID links your resources to a specific organization or account within the Azure Active Directory.
* **Storage Account Name**: This is the user-defined name for your Azure Storage Account, providing a globally unique namespace for your data.
* **Key Vault Name**: Azure Key Vault serves as a centralized secrets manager, securely storing and managing sensitive information, such as connection strings and cryptographic keys.

> [!TIP]
>
> **Tip**: When using a **Hybrid Ingestion Runner**, any sensitive credential fields, such as passwords, API keys, and private keys, must reference secrets using the following format:
>
> ```
> password: secret:/my/database/password
> ```
>
> This applies **only to fields marked as secrets** in the connection form (these typically mask input and show a visibility toggle icon).
>
> For more information about managing secrets in hybrid setups, see the [Hybrid Ingestion Runner Secret Management Guide](https://docs.getcollate.io/getting-started/hybrid-ingestion-runner.md#manage-secrets).

#### Test Connection

1. Click **Test Connection** to verify the credentials.
2. After the test succeeds, click **Save**.

![Test Connection](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/test-connection.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=3365cff7bb9d82c85a2ff9ab559d6f11)

### Step 5: Configure Ingestion Options

In the **What to Ingest** step, use filter patterns to control which assets Collate ingests from your storage service. Filter rules match container names using the following match types.

#### How Filter Patterns Work

* **Include**: Add one or more comma-separated values. Each value uses one of the following match types. Collate ingests only containers whose names match at least one rule. Leave blank to include all containers.
* **Exclude**: Add one or more comma-separated values. Each value uses one of the following match types. Collate skips any container whose name matches a rule. Leave blank to exclude nothing.

Rules match asset names using one of five match types:

* **contains**: matches any name containing the value. For example, `sales` matches `my_sales_data` and `sales_2024`.
* **starts with**: matches names beginning with the value. For example, `prod_` matches `prod_db` and `prod_schema`.
* **ends with**: matches names ending with the value. For example, `_raw` matches `events_raw` and `logs_raw`.
* **is exactly**: matches the exact name only. For example, `analytics` matches only `analytics`.
* **matches regex**: matches names using a regular expression. For example, `^prod_.*_v\d+$` matches `prod_events_v1`.

When both Include and Exclude are set, Exclude takes priority.

> [!TIP]
>
> **Tip**: Leave the filter pattern empty to ingest all containers (S3 buckets, ADLS containers, GCS buckets) available in the source.

#### Filter Options

The Container section includes the following filter options:

* **Container**: Controls which top-level storage containers (S3 buckets, ADLS containers, or GCS buckets) Collate ingests from the source.

This section provides the following controls:

* **Scan Mode**: Choose between the following scan modes:
  * **Scan all**: Ingests every asset of that type the connector can access. This is the default.
  * **Only specific**: Enables include rules so only assets matching at least one rule are ingested.
* **Exclude system toggle**: Use this toggle to filter out system-reserved names defined by the connector for that asset type.
* **Always exclude**: Add permanent exclusion rules (shown in red). Assets matching these rules are never ingested, regardless of include rules.
* **Preview**: Shows a real-time summary of what will be in scope based on your current rules.
* **Include rules**: In **Only specific** mode, click **+ Add** to define a rule. Added rules appear as chips. An asset is included if it matches any rule.

> [!TIP]
>
> **Tip**: If [AutoPilot](https://docs.getcollate.io/how-to-guides/admin-guide/applications/autopilot.md) is enabled, usage tracking, data lineage, and other downstream workflows start automatically after the first metadata ingestion completes.

### Step 6: Create & Deploy

Click **Create & Deploy** to deploy the agent and start the first metadata ingestion run. Collate saves the service configuration and immediately begins pulling metadata from the source.

To monitor ingestion progress or view the service you just added, go to **Settings** > **Services** and select your service.

## Configure Metadata Agent and Schedule Ingestion

The **Metadata Agent** extracts containers, objects, and other structural metadata from your source and keeps your Collate catalog in sync. It powers discovery, lineage, and governance across your data assets.

When you click **Create & Deploy**, Collate automatically deploys a Metadata Agent for this service and triggers the first ingestion run. View its status and run history from the **Agents** tab on the service detail page.

To configure the additional Metadata Agent and schedule ingestion, follow these steps:

1. Navigate to **Settings** > **Services** and select the **Storage** service.

2. Select your service and click the **Agents** tab.

3. Click **Add Agent** and select **Metadata** from the dropdown.

   ![Add Metadata Agent](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/add-metadata-agent.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=accad7d1c4ddf209781bff851d51d464)

   For some services, the dropdown is not available and clicking **Add Agent** takes you directly to the agent configuration page.

4. On the **Configure Ingestion** page, do the following and click **Next**.

   * **Name this Ingestion**: Enter a unique, recognizable name for this ingestion pipeline.

     ![Name this Ingestion](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/metadata-agent-name.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=d5ec1f0f3742cadab8cd54c602c97239)

   * **Filter Patterns**: Apply include or exclude rules to scope which containers this agent ingests. These follow the same filter options described in **Step 5**.

   * **Scope & Behaviour**: Control how the agent handles metadata during ingestion. Toggle each option on or off based on your needs:

     | Toggle | Default | Description |
     | - | - | - |
     | Mark Deleted Containers | On | Soft-delete containers in Collate when they are removed from the source. |
     | Include Tags | Off | Ingest tags from the source. |
     | Override Metadata | Off | When on, source values overwrite existing descriptions, tags, owners, and display names in Collate. A description or display name that the source doesn't send never replaces an existing value. If the connector supplies custom properties, the values it sends are merged over the existing ones: properties the source sends overwrite, and properties it doesn't send are kept. When off, Collate only updates fields that have no existing value. |
     | Enable Debug Log | Off | Sets the ingestion log level to DEBUG. Useful for troubleshooting. |

5. On the **Schedule Interval** page, set when the agent runs:

   * **Schedule**: Choose a preset interval (Hourly, Daily, Weekly, Monthly) or enter a custom cron expression.
   * **On-Demand**: No automatic schedule. Trigger the agent manually when needed.

   ![Schedule Interval](https://mintcdn.com/collatedocs/bv5oe4uRjuorTJO1/public/images/ai-2.0/connectors/metadata-ingestion/schedule.png?fit=max\&auto=format\&n=bv5oe4uRjuorTJO1\&q=85\&s=25cc1d78f6f2a8bd115830d034d1d8d1)

6. Click **Add** to deploy the agent.

## Troubleshooting

> [card] [ADLS Troubleshooting](https://docs.getcollate.io/connectors/storage/adls/troubleshooting.md)
>
> Learn more about how to troubleshoot common ADLS connector issues and resolve configuration or ingestion errors.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.