Ref

relationalai.semantics.frontend.base

Ref(concept: Concept, name: str | None = None)

Represents a named reference variable for entities of a concept.

A Ref is a DSL variable that stands in for an (unknown) entity of some Concept. You typically create refs via Concept.ref when you need multiple independent variables of the same concept (for example two endpoints of an edge).

A ref behaves like other variables in the semantics DSL:

• Attribute access (e.g. u.id or u.name) resolves relationships on the underlying concept and returns a Chain.
• Ref.filter_by builds a composable filter expression rooted at this reference.

Parameters

• concept

  (Concept) - The concept this reference ranges over.

• name

  (str, default: None) - Display name for the reference, used in generated readings and debugging output. When omitted, a default name is derived from the concept (numeric concepts default to "number").

Examples

Create two refs and use attribute access in a join:

>>> from relationalai.semantics import Integer, Model, String
>>> m = Model()
>>> Person = m.Concept("Person", identify_by={"id": Integer})
>>> Person.name = m.Property(f"{Person} has name {String}")
>>> m.define(Person.new(id=1, name="Alice"), Person.new(id=2, name="Bob"))
>>> p, q = Person.ref("p"), Person.ref("q")
>>> m.select(p.name, q.name).where(p.id < q.id).to_df()

Notes

Most users should not instantiate this class directly. Prefer Concept.ref.

Methods

.__getattr__()

Ref.__getattr__(item: str) -> Chain

Return a chained relationship reference for attribute access.

A Ref behaves like a variable of its underlying Concept. Accessing p.name (where p = Person.ref()) returns a Chain that can be used in filters and selections.

If the attribute name starts with an underscore, this method defers to normal Python attribute access so internal attributes remain accessible.

Parameters:

• item

  (str) - Relationship/property name to access.

Returns:

• Chain - A chained value representing the relationship reading.

Raises:

• relationalai.util.error.RAIException - Raised in the following cases:
  • A relationship with this name is not declared and the .model.implicit_properties config flag is disabled.
  • Relationships are accessed on a core concept.

Examples:

Access a property through a reference variable:

>>> from relationalai.semantics import Model
>>> m = Model()
>>> Person = m.Concept("Person")
>>> m.define(Person.new(name="Alice"))
>>> p = Person.ref("p")
>>> m.select(p.name).to_df()

.filter_by()

Ref.filter_by(**kwargs: Any) -> FilterBy

Return an expression that constrains this reference by property values.

Ref.filter_by(...) is like Concept.filter_by, but it is rooted at this specific reference variable. This is useful when you want to keep using the same ref elsewhere in a query (for example in a join) while also filtering it.

Keyword names are resolved like attribute access (case-insensitively), and values may be Python literals (e.g., "Alice") or DSL values.

Parameters:

• **kwargs

  (Any, default: {}) - Property/relationship values to match. Keys are treated case-insensitively.

Returns:

• FilterBy - A composable expression that can be used in Model.where.

Raises:

• relationalai.util.error.RAIException - Raised in the following cases:
  • A keyword refers to a relationship/property that is not declared and the model.implicit_properties config flag is disabled.
  • Relationships are accessed on a core concept.
• NotImplementedError - If a Python value cannot be converted to a supported literal.

Examples:

Filter a named reference and keep using it in the query:

>>> from relationalai.semantics import Model
>>> m = Model()
>>> Person = m.Concept("Person")
>>> m.define(Person.new(id=1, name="Alice"), Person.new(id=2, name="Bob"))
>>> p = Person.ref("p")
>>> m.where(p.filter_by(name="Alice")).select(p.id).to_df()

.__format__()

Ref.__format__(format_spec: str) -> str

Return the placeholder used when formatting this reference in readings.

This forwards to Concept.__format__ on the underlying concept so refs can be interpolated into relationship and property reading strings.

Parameters:

• format_spec

  (str) - Optional field name to use for this occurrence (whitespace is stripped).

Returns:

• str - A placeholder string for this concept occurrence.

Inheritance Hierarchy

Used By

 semantics
├──  frontend > base
│   ├──  Chain
│   └──  FilterBy
└──  std > constraints
    ├──  anyof
    ├──  exclusive
    └──  oneof

Returned By

 semantics > frontend > base
└──  Concept
    └──  ref