Azure Blob / ADLS Reference

Authentication options and data type handling for Azure storage connections.

Server

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

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

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.

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[]