DataSource

DataSource(
    backend,
    tables,
    table_ids=dict(),
    pending=None,
    dictionary=None,
    relations=None,
    manifest=None,
    session=None,
    definition_bindings=None,
)

Tables an agent can query, and the dictionary that describes them.

Methods

Name	Description
dialect	A hint for the system prompt, not a contract.
ensure_loaded	Read every pin this source has not read yet.
from_board	Expose a pins board’s pins as tables, each read on first use.
from_engine	Query a caller’s database directly. Nothing is copied.
from_frames	Load named data frames into a locked-down in-process DuckDB.
query	Run one read-only statement, rejecting anything else first.

dialect

DataSource.dialect()

A hint for the system prompt, not a contract.

ensure_loaded

DataSource.ensure_loaded()

Read every pin this source has not read yet.

A board source loads a pin when a query names it, and that recovery lives on query(). A measure is handed the connection itself and never goes through query(), so nothing there would trigger the read and the measure would fail on a relation that does not exist yet. source_ensure_all() in pkg-r/R/data-source.R is the same step for the same reason. A source with nothing pending, which is every source that is not board-backed, does nothing.

from_board

DataSource.from_board(board, tables, dictionary=None)

Expose a pins board’s pins as tables, each read on first use.

dictionary is taken here so that the argument survives the dispatcher; a board has no catalog listing to fold into it. Its governed definitions are lowered at the end of construction, once the dialect and the final table set are known.

from_engine

DataSource.from_engine(engine, tables=None, exclude=None, dictionary=None)

Query a caller’s database directly. Nothing is copied.

A Snowflake or Databricks engine imports its catalog: the selection is resolved against the warehouse, access to it is verified for the current principal, and what it reports is folded into dictionary.

With tables unset on any other backend, its own listing is taken as given: it reports what exists, so there is nothing to check and no round trip worth paying for.

exclude takes unqualified object-name globs to drop from a warehouse catalog listing, such as "TMP_*". Only a warehouse has a listing to drop from, so any other engine refuses it.

On a warehouse dictionary is taken here because the catalog listing is folded into it during construction; on any other engine it is simply attached. Its governed definitions are lowered once the dialect and the final table set are known, at the end of construction.

from_frames

DataSource.from_frames(**frames)

Load named data frames into a locked-down in-process DuckDB.

query

DataSource.query(sql)

Run one read-only statement, rejecting anything else first.

On a warehouse source the connection identity is checked before the statement is read: access to these tables was decided for one principal, role, and namespace, so a query raises rather than runs once any of those has moved.