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. Keys are Snowflake identifiers, so several keys can fold to the same stored column (for example "a" and "A", or "a" and "a "); such collisions collapse to a single column when they agree on type, and raise a [Conflicting column type] error when they do not.

• 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, unsafe: bool = False, **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.

• unsafe

  (bool, default: False) - 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
        └──  Use advanced reasoning > Predictive reasoning
            └──  Solve a classification problem
                └──  Define concepts and load data

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
│   │   └──  Use advanced reasoning > Predictive reasoning
│   │       └──  Solve a classification problem
│   │           └──  Define concepts and load data
│   └──  Follow a Tutorial
│       └──  Get started with a coding agent
│           └──  Start building with /rai-ontology
└──  Release Notes
    └──  Python API Release Notes
        ├──  What’s New in Version 1.19.1
        │   └──  Bug Fixes
        └──  What’s New in Version 1.19.3
            └──  Bug Fixes