peql.Engine#

A Python wrapper around one native peQL engine. Construct it with Engine.open or Engine.in_memory; the Engine(native) initializer is an internal wrapper. Management methods do not take a Caller. Authenticate and authorize those operations in your application.

Method

Result

open / in_memory

Create an engine.

register / register_compiled

Register a contract.

write / validate

Write or validate a dataset.

query / query_with_envelope

Execute a read-only SQL query.

describe / contracts

Inspect exposed columns or registered names.

publish / unpublish

Change tenant visibility.

open#

peql.Engine.open(root) -> peql.Engine

root is a filesystem path or path-like object converted to str. Opens or creates a persistent workspace at that path. The returned engine keeps workspace state on disk.

in_memory#

peql.Engine.in_memory(base=".") -> peql.Engine

Keeps engine registration state in memory. base is a path or path-like object, defaulting to the current directory; relative data bindings still resolve beneath it.

register#

engine.register(contract: str, schema: pyarrow.Schema | object_with_schema) -> str

contract is YAML or JSON text, not a filename. schema is a pyarrow.Schema, pyarrow.Table, pyarrow.RecordBatch, or another object with a .schema attribute. peQL compiles the contract against that schema and registers it. Returns the contract name. Compilation or schema errors raise RuntimeError.

register_compiled#

engine.register_compiled(contract: str, compiled: bytes) -> str

contract is the source YAML/JSON text. compiled is the byte sequence produced by parcel compile -o. Registers that compiled artifact as supplied; it does not compile again. Returns the contract name. A malformed document or incompatible artifact raises RuntimeError.

write#

engine.write(
    name: str,
    data: pyarrow.Table | pyarrow.RecordBatch,
    append: bool = False,
    on_violation: str = "refuse",
) -> dict

name is a registered contract name. data supplies an Arrow schema and batches. With append=False, replaces the bound data; append=True adds rows.

on_violation says what to do with rows that break a row rule (a drop or deny assert):

  • "refuse" (default): if any row breaks one, nothing is written and peql.Refused is raised, naming each rule and how many rows broke it.

  • "exclude": only the rows that pass are written; the others are returned in report["excluded"].

  • "warn": every row is written; the verdict is not valid when a deny-level assert fails.

Any other value raises RuntimeError.

Returns a dictionary with rows_written, on_violation, violations (rows that broke each rule), rows_excluded, excluded (a pyarrow.Table with a _violations column under "exclude", else None), files, verdict, table and, for an Iceberg table, snapshot. table holds the dataset’s row_count and per-column null_counts after the write, or None while its manifest is not recorded. files lists the files this write added; verdict is the contract’s row rules over the rows written. See Results and errors. Write failures raise RuntimeError or peql.Refused when the engine classifies them as a refusal.

validate#

engine.validate(name: str) -> dict

Runs the contract’s validation plan over its bound data and returns a verdict dictionary. Validation itself does not save a replacement manifest. A false valid value is a result, not necessarily an exception. name is a registered contract name.

query#

engine.query(sql: str, caller: peql.Caller, on_violation: str = "exclude") -> pyarrow.Table

Executes one read-only SQL query as the supplied caller and returns an Arrow table. The result contains only rows and columns exposed under that caller’s policy, and never a row that breaks a row rule. With on_violation="exclude" (default) such rows are left out and counted in the envelope. With "refuse", a query of data that holds any such row raises peql.Refused, naming each rule and how many rows broke it. Raises peql.Refused for a policy or visibility refusal; malformed SQL and execution failures raise RuntimeError. See query_with_envelope for metadata.

query_with_envelope#

engine.query_with_envelope(
    sql: str, caller: peql.Caller, on_violation: str = "exclude"
) -> tuple[pyarrow.Table, dict]

Takes the same sql, caller and on_violation as query. Returns (table, envelope): the result table and a dictionary of applied contracts, scan statistics, charges, attestation and audit metadata. See Results and errors for the keys. Exceptions follow query.

describe#

engine.describe(name: str, caller: peql.Caller) -> list[tuple[str, str]]

Returns (column_name, Arrow_type_string) pairs visible to the caller for the named contract. It checks visibility and caller-level permission. It does not validate that the underlying dataset currently passes all quality requirements.

contracts#

engine.contracts() -> list[str]

Returns all names registered in this engine. It takes no caller and does not filter by tenant visibility; use it in operator code, not as a caller-facing discovery method.

publish#

engine.publish(name: str, audience: str) -> None

Makes the named contract visible to audience, a tenant name or "public" for all tenants. Visibility does not bypass contract rules. Unknown names and storage failures raise RuntimeError.

unpublish#

engine.unpublish(name: str, audience: str) -> None

Withdraws visibility from the tenant or "public" audience. This is an operator action and takes no caller parameter.