# <img className="page-icon" src="/img/icons/azure.svg" alt="" /> Azure Blob / ADLS Reference

Authentication options and data type handling for [Azure storage connections](../testing/azure.md).

## Server

```yaml
servers:
  - server: production
    type: azure
    location: abfss://datameshdatabricksdemo.dfs.core.windows.net/inventory_events/*.parquet
    format: parquet
```

## Authentication

Two authentication methods are supported by the DuckDB engine (`datacontract test` on Azure files):

1. **Service Principal (App Registration) with a secret.** Used when all three of `DATACONTRACT_AZURE_TENANT_ID`, `DATACONTRACT_AZURE_CLIENT_ID` and `DATACONTRACT_AZURE_CLIENT_SECRET` are set.
2. **Azure credential chain.** Used as soon as the service principal variables are not all set: Azure CLI (`az login`), environment, managed identity, workload identity, and so on. It uses the `CREDENTIAL_CHAIN` provider of the DuckDB `azure` extension. Contracts posted to `datacontract api` never use the chain, so the API server's own identity is not lent to its callers; send the service principal as `datacontract-azure-*` request headers instead.

| Variable | Example | Description |
|---|---|---|
| `DATACONTRACT_AZURE_TENANT_ID` | `79f5b80f-...` | The Azure Tenant ID (service principal) |
| `DATACONTRACT_AZURE_CLIENT_ID` | `3cf7ce49-...` | The Application/Client ID of the app registration (service principal) |
| `DATACONTRACT_AZURE_CLIENT_SECRET` | `yZK8Q~GWO1M...` | The client secret value (service principal) |
| `DATACONTRACT_AZURE_CREDENTIAL_CHAIN` | `cli;env;managed_identity` | Optional, credential chain only. `;`-separated providers, tried in order. Default: the DuckDB `azure` extension default chain. Delta tables need `cli` to use `az login` |

The storage account is derived from the `location` of the server. The identity (service principal or the one found by the credential chain) needs the **Storage Blob Data Reader** role. The [metadata-check path](../testing/azure.md#metadata-checks) alternatively accepts `DATACONTRACT_AZURE_CONNECTION_STRING` or `DATACONTRACT_AZURE_STORAGE_ACCOUNT_KEY`.

Supported `location` URL formats (in the `servers` block):

- `https://<account>.blob.core.windows.net/<container>/<prefix>`
- `abfss://<container>@<account>.dfs.core.windows.net/<prefix>`
- `azure://<container>@<account>.blob.core.windows.net/<prefix>`
- `wasbs://<container>@<account>.blob.core.windows.net/<prefix>`

## Data types

Files on Azure storage are read with DuckDB. Type handling depends on the `format` in the `servers` block:

| `format` | How types are handled |
|---|---|
| `csv` | The file is read **as the contract's types** — no type checks are generated; a value that can't be coerced surfaces as a read error. |
| `json` | Same as CSV, plus every record is validated against a JSON Schema derived from the contract's `logicalType`s. |
| `parquet` | The file is read **as the contract's types**, like CSV, so checking its types is not supported yet, a value that can't be cast surfaces as a read error. |
| `delta` | Column types come from the Delta table; the contract's `logicalType` is checked by category. |
| `metadata` | No file is read: the schemas are checked against blob properties (size, content type, last modified, …), see [metadata checks](../testing/azure.md#metadata-checks). |

`physicalType` is never checked against file sources.

{/* AUTOGENERATED TYPE MAPPING: do not edit by hand; regenerate with update_reference_types.py */}

### Logical type mapping

When no `physicalType` is declared, the CLI derives the DuckDB column type from the `logicalType` when reading files. This table is generated from the converters in the CLI's code:

| `logicalType` | CSV read type | Parquet read type |
|---|---|---|
| `string` | `VARCHAR` | `VARCHAR` |
| `integer` | `BIGINT` | `INTEGER` |
| `number` | `DOUBLE` | `DECIMAL` |
| `boolean` | `BOOLEAN` | `BOOLEAN` |
| `date` | `DATE` | `DATE` |
| `timestamp` | `TIMESTAMP` | `TIMESTAMP WITH TIME ZONE` |
| `time` | `TIME` | `TIME` |
| `object` | `VARCHAR` | `STRUCT()` |
| `array` | `VARCHAR` | `VARCHAR[]` |
| `map` | `VARCHAR` | `MAP(VARCHAR, VARCHAR)` |
| `vector` | `VARCHAR` | `FLOAT[]` |

{/* END AUTOGENERATED TYPE MAPPING */}
