Using peQL#

Use the command line to manage a workspace and run queries, or embed the engine in a Python or Rust application. All three interfaces use the same contracts and query rules.

The commands below continue from the Quickstart. Run them from your peql-demo directory, or select it with peql --root PATH.

Write or append data#

Write a CSV or Parquet file under a registered contract:

peql write sales/orders --input orders.csv

This replaces the existing Parquet data at the contract’s binding. To add records instead:

peql write sales/orders --input orders.csv --append

Append adds every input row; it does not deduplicate records or update rows with matching IDs. In this example, appending the same file twice duplicates the orders.

For CSV fields such as phone numbers or identifiers, override inferred types when needed:

peql write sales/orders --input orders.csv --type order_id=int64

By default a write refuses rows that break a contract’s row rules (its drop and deny asserts): when any input row breaks one, nothing is written, and the refusal names each rule and how many rows broke it. To write the rows that pass and set the others aside:

peql write sales/orders --input orders.csv --on-violation exclude --excluded rejected.parquet

rejected.parquet holds the set-aside rows with a _violations column listing the rules each row broke. --on-violation warn writes every row instead; queries still leave the breaking rows out. The write report lists how many rows broke each rule. Rows that fail an assert with on_fail: report are only counted and never refused.

Queries never return rows that break a row rule. By default they leave them out and note how many per rule; add --on-violation refuse to peql query to refuse a query of data that holds any. See Rows that break a contract.

Register existing data#

To query Parquet you already have, set the contract’s binding.parquet to the file or directory, then register the contract against a representative file:

peql register orders.yaml --schema data/orders/part-0.parquet

Replace the sample path with an actual file from your dataset. Registration checks and stores the contract without rewriting the data. On the first query, peQL creates a validation manifest if one is missing. The manifest stores the dataset’s verdict and statistics.

Use peQL’s write path for subsequent changes. In this version, existing manifests are not automatically refreshed when another program edits the files, and validate validates the whole dataset and saves the manifest it computes.

Share and inspect a contract#

peql publish sales/orders --to globex
peql describe sales/orders --tenant globex --purpose reporting
peql list

Publishing allows a tenant to discover the contract; it does not exempt that tenant from its rules. describe shows the exposed columns after checking visibility and caller-level permission. It does not check whether the dataset currently meets every quality requirement.

To withdraw access:

peql publish sales/orders --to globex --revoke

Use --to public to make a contract discoverable by every tenant. A contract with no owner is already visible to all tenants. The rules still determine which queries are allowed.

Save caller context#

Instead of repeating caller flags, save this as analyst.yaml:

id: globex-analyst
tenant: globex
purpose: reporting
roles: [analyst]

Then run:

peql query 'SELECT SUM(amount) AS total FROM "sales/orders"' --caller analyst.yaml

Explicit flags override values from the file. For example, --purpose marketing changes the purpose for that query.

In an application, supply context from your authentication system. Keep registration, writes, sharing and other management operations under your application’s control; these engine operations do not take a caller argument.

Export and inspect results#

Use --format json for one JSON object per row, or --format arrow or --format parquet for binary output. --out writes the result to a file:

peql query 'SELECT order_id, amount FROM "sales/orders"' --caller analyst.yaml --format parquet --out report.parquet

Add --envelope to print query metadata to standard error while leaving the result on standard output or in its output file. See Reference for the envelope fields and exit codes.

To inspect data quality directly:

peql validate sales/orders

This returns the validation verdict as JSON. It describes the underlying data, including rows excluded from query results.

Update a contract#

Edit the contract, increase its version, and register it again against the data’s schema. peQL keeps registered versions and uses the highest version number for queries. Registering the same name and version replaces that stored version.

If the change affects quality checks, derived values or stored data layout, rewrite the data from the source through the updated contract. This refreshes the validation manifest and stored rule calculations.

Use peQL in an application#

Choose the interface that fits your application: