Skip to content

Glossary

  • Adapter: A backend implementation of BaseAdapter that executes PlanFrame plans.
  • AdapterCapabilities: Capability flags on BaseAdapter.capabilities (plan nodes, IO surfaces, and advisory native_async_materialize for async materialization UX). See Creating an adapter.
  • Plan / PlanNode: The lazy IR PlanFrame builds when you chain Frame operations.
  • Expression / Expr: The backend-agnostic expression IR compiled by adapters.
  • ExecutionOptions: Optional hints (streaming, engine_streaming, …) passed at materialization boundaries (collect, to_dicts, to_dict, and async equivalents).
  • JoinOptions: Optional execution hints for Frame.join (not relational semantics). Fields unset (None) should be omitted when calling the backend.
  • ColumnSelector: Schema-only selection protocol (planframe.selector); @runtime_checkable so isinstance works for built-ins and structural matches.
  • PlanCompileContext: Internal helper (planframe.compile_context) that holds (adapter, schema) and compiles expression IR, join keys, aggregations, and related structures—shared by Frame and execute_plan so compilation stays consistent.
  • execute_plan: The supported interpreter that evaluates a PlanNode tree by dispatching to BaseAdapter methods; Frame uses it at materialization boundaries.
  • execute_plan_async: Async wrapper around execute_plan that runs the same synchronous interpreter in a worker thread (asyncio.to_thread) so callers can await without blocking the event loop; lazy plan building remains sync. Async engine I/O still uses BaseAdapter async materializers (acollect, ato_dict, …). See Migrating since v1.1.0 and Creating an adapter — Async execution.
  • CompileExprContext: Holds the active Schema for an expression compile step, plus an optional resolve_backend_dtype callback populated by execute_plan when native column metadata should augment a partial step schema; passed to BaseAdapter.compile_expr and BaseAdapter.resolve_dtype (re-exported from planframe). Adapters may implement resolve_backend_dtype_from_frame to supply dtypes from the live backend frame. Shipped adapters compile Col permissively when a name is missing from the step schema (resolve_dtype may return None); see Creating an adapter — Unknown columns. Different from PlanCompileContext (planframe.compile_context), which pairs an adapter with a schema for plan-level compilation helpers used by Frame and execute_plan.
  • materialize_columns / materialize_into (planframe.materialize): Thin, adapter-agnostic helpers for Frame → dict[str, list[object]] and an optional post-processing callable; forward ExecutionOptions like Frame.to_dict / Frame.ato_dict. See Creating an adapter — Columnar boundary. Optional AdapterColumnarStreamer (planframe.backend.io) is a spike for chunked columnar batches — design.
  • API skin: An optional mixin on Frame (e.g. planframe.spark.SparkFrame, planframe.pandas.PandasLikeFrame) that adds familiar method names while preserving PlanFrame’s lazy plan and typing story.
  • Hint (plan node): A PlanNode carrying opaque execution hints (SparkFrame.hint(...)). execute_plan calls BaseAdapter.hint (default no-op) so backends can optionally honor hint strings or metadata.