Local Files Reference

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

Server

servers:
  - server: local
    type: local
    path: ./*.parquet # glob patterns and a {model} placeholder are supported
    format: parquet   # parquet, json, csv, xml, xlsx, or delta

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).
xml	Like CSV: the documents are read as the contract's types, with nested elements as structs and repeated elements as lists.
xlsx	Each cell is read as the contract's type of its column, including Excel dates stored as numbers. A cell that has a value of another type fails the type check of its column.
parquet	The file is read as the contract's types, like CSV, so checking its types is not supported yet, and 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.

Presence. For json and xml, only the required top-level properties are checked for presence: a document may leave out a property that is not required, even in every record. For the other formats, every column of the contract must exist in the file.

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[]
map	VARCHAR	MAP(VARCHAR, VARCHAR)
vector	VARCHAR	FLOAT[]