Azure Blob / ADLS Reference
Authentication options and data type handling for Azure storage connections.
Authentication
Authentication uses an Azure Service Principal (App Registration) with a secret:
| Variable | Example | Description |
|---|---|---|
DATACONTRACT_AZURE_TENANT_ID |
79f5b80f-... |
The Azure Tenant ID |
DATACONTRACT_AZURE_CLIENT_ID |
3cf7ce49-... |
The Application/Client ID of the app registration |
DATACONTRACT_AZURE_CLIENT_SECRET |
yZK8Q~GWO1M... |
The client secret value |
The service principal needs the Storage Blob Data Reader role. The metadata-check path 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 logicalTypes. |
parquet |
Column types come from the Parquet file; the contract’s logicalType is checked by category. |
delta |
Column types come from the Delta table; the contract’s logicalType is checked by category. |
physicalType is never checked against file sources. Schema objects with logicalType: blob / physicalType: file switch to metadata checks against blob properties instead of reading file contents.
{/* 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[] |
{/* END AUTOGENERATED TYPE MAPPING */}
