Table

relationalai.semantics.frontend.base

Table(name: str, schema: dict[str, Concept], model: Model)

Represents an external table reference in a semantic model.

A Table is a lightweight handle for an external table name (for example, a SQL table or view) that can be used in two common ways:

• As a source of rows when defining entities via Table.to_schema.
• As a target for query exports via Fragment.into.

Tables behave like concepts with column relationships: you can access a column by index (table[0]) or by name (table["col"]), and iterate over columns.

Parameters

• name

  (str) - Table name or path used by the backend.

• schema

  (dict[str, Concept]) - Optional mapping of column names to their types. When provided, column relationships are created immediately. When omitted, column metadata is resolved lazily the first time columns are accessed.

• model

  (Model) - The model this table reference belongs to.

Examples

Use a table as an input when defining entities:

>>> from relationalai.semantics import Model, Integer, String
>>> m = Model()
>>> source = m.Table("DB.SCHEMA.CUSTOMERS", schema={"id": Integer, "name": String})
>>> Customer = m.Concept("Customer", identify_by={"id": Integer})
>>> m.define(Customer.new(source.to_schema()))

Create a table reference as an export target:

>>> from relationalai.semantics import Integer, Model
>>> m = Model()
>>> Person = m.Concept("Person", identify_by={"id": Integer})
>>> m.define(Person.new(id=1, name="Alice"), Person.new(id=2, name="Bob"))
>>> out = m.Table("DB.SCHEMA.PERSONS_EXPORT")
>>> m.select(Person.id, Person.name).into(out).exec()

Notes

Users typically create table references via Model.Table rather than instantiating this class directly.

Methods

.__getitem__()

Table.__getitem__(index: int | str) -> Chain

Return a chained reference to a table column.

Indexing a Table returns a Chain for the selected column relationship. You can select a column either by 0-based integer position (table[0]) or by column name (table["col"]).

If the table was created without an explicit schema=, the first column access triggers lazy schema discovery.

Parameters:

• index

  (int | str) - Column selector: a 0-based index or a column name.

Returns:

• Chain - A chained value representing the column.

Raises:

• IndexError - If index is an integer index that is out of range.
• KeyError - If index is a name that is not present.

Examples:

Select columns by name and by index:

>>> from relationalai.semantics import Integer, Model, String
>>> m = Model()
>>> t = m.Table("DB.SCHEMA.CUSTOMERS", schema={"id": Integer, "name": String})
>>> m.select(t["name"], t[0]).to_df()

.__iter__()

Table.__iter__() -> Iterator[Relationship]

Return an iterator over this table’s column relationships.

Iterating over a Table yields each column as a Relationship. This is useful when you want to select all columns (for example m.select(*t)) or inspect available columns.

If the table was created without an explicit schema=, the first iteration triggers lazy schema discovery.

Returns:

• Iterator[Relationship] - Iterator over the table’s column relationships.

Examples:

Select all columns from a table:

>>> from relationalai.semantics import Integer, Model, String
>>> m = Model()
>>> t = m.Table("DB.SCHEMA.CUSTOMERS")
>>> m.select(*t).to_df()

.new()

Table.new(*args: StatementAndSchema, **kwargs: Any) -> NoReturn

Raise an error because tables cannot construct new entities.

A Table is an external table reference used as a row source (via Table.to_schema) or as a query export target (via Fragment.into). It is not an entity type, so table.new is always invalid.

Parameters:

• *args

  (StatementAndSchema, default: ()) - Unused. Present for API compatibility with Concept.new.

• **kwargs

  (Any, default: {}) - Unused. Present for API compatibility.

Raises:

• relationalai.util.error.RAIException - Always raised.

.to_identity()

Table.to_identity(*args: Any, **kwargs: Any) -> NoReturn

Raise an error because tables cannot be referenced by identity.

A Table is an external table handle, not an entity concept. If you need an identity-only entity reference, use Concept.to_identity on a Concept.

Parameters:

• *args

  (Any, default: ()) - Unused. Present for API compatibility.

• **kwargs

  (Any, default: {}) - Unused. Present for API compatibility.

Raises:

• relationalai.util.error.RAIException - Always raised.

.to_schema()

Table.to_schema(*, exclude: list[str] = []) -> TableSchema

Return a schema object for using this table as an entity row source.

The returned TableSchema is typically passed to Concept.new, e.g. Customer.new(source.to_schema()). Column names in exclude are matched case-insensitively.

Parameters:

• exclude

  (list[str], default: []) - Column names to omit from the schema.

Returns:

• TableSchema - A schema projection of this table’s columns.

Examples:

Define one entity per source row:

>>> from relationalai.semantics import Integer, Model, String
>>> m = Model()
>>> source = m.Table("DB.SCHEMA.CUSTOMERS")
>>> Customer = m.Concept("Customer")
>>> m.define(Customer.new(source.to_schema()))

Exclude a foreign key column and map it to a concept reference:

>>> Order = m.Concept("Order")
>>> Order.customer = m.Property(f"{Order} placed by {Customer}")
>>> orders_table = m.Table("DB.SCHEMA.ORDERS")
>>> m.define(
...     Order.new(
...         orders_table.to_schema(exclude=["customer_id"]),
...         customer=Customer.new(id=orders_table.customer_id),
...     )
... )

Referenced By:

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Build a semantic model
        └──  Define base facts

Inheritance Hierarchy

Subclassed By

 semantics > frontend > base
└──  Data

Used By

 semantics > frontend > base
├──  Chain
├──  Fragment
│   └──  into
└──  TableSchema

Returned By

 semantics > frontend > base
└──  Model
    └──  Table

Referenced By

RelationalAI Documentation
└──  Build With RelationalAI
    └──  Understand how PyRel works > Build a semantic model
        ├──  Declare data sources
        │   └──  Use a Snowflake table with Model.Table
        └──  Define base facts