Local Files Reference

Data type handling for local file connections. No environment variables are needed.

Data types

Importing

datacontract import csv samples the file with DuckDB and infers per column:

Inferred DuckDB type	logicalType
BOOLEAN	boolean
INTEGER, BIGINT	integer
DOUBLE	number
VARCHAR	string

It also profiles the data: required (no nulls), unique (all distinct), examples, and minimum/maximum for numeric columns. Values that all match an email or UUID pattern get logicalTypeOptions.format.

datacontract import json inspects the first 20 records: booleans, integers, and floats map to boolean/integer/number; strings map to string (with a detected format of date, date-time, email, or uuid in logicalTypeOptions); objects and arrays map to object/array with nested properties. When records disagree, the wider type wins (integer + float → number; anything + string → string).

datacontract import parquet reads types from the Parquet metadata.

Testing

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 (with format options like date-time, uuid).
parquet	Column types come from the Parquet file; the contract's logicalType is checked by category (Check that field x has type y).
delta	Column types come from the Delta table; the contract's logicalType is checked by category.

physicalType is never checked against file sources — declare logicalType (and logicalTypeOptions for value constraints). The path supports glob patterns and a {model} placeholder.

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