add()#

relationalai.ContextSelect
#ContextSelect.add(item: Any, **kwargs: Any) -> None

Assigns a value to a ContextSelect object. May only be called from ContextSelect objects created in a Model.match() block.

Parameters#

NameTypeDescription
itemAnyThe value to assign to the ContextSelect.
**kwargsAny(Optional) Keyword arguments that set context-specific properties on assigned values.

Returns#

None

Example#

Use .add() to assign values to a ContextSelect object in a Model.match() block:

#import relationalai as rai
from relationalai.std import alias


# =====
# SETUP
# =====

model = rai.Model("MyModel")
Item = model.Type("Item")

with model.rule():
    Item.add(id=1).set(name="A", price=10.00)
    Item.add(id=2).set(name="B", price=10.00)
    Item.add(id=3).set(name="C", price=20.00)


# =======
# EXAMPLE
# =======

# Compute an item's discount based on its price.
with model.query() as select:
    item = Item()
    with model.match() as discount: # discount is a ContextSelect object
        # Items with a price greater than 15 get a 25% discount.
        with item.price > 15:
            discount.add(0.25)  #  Assign 0.25 to discount.
        # All other items get a 10% discount.
        with model.case():
            discount.add(0.1)

    # Compute the discounted price.
    discounted_price = item.price * (1 - discount)

    response = select(
        item.id,
        item.name,
        item.price,
        alias(discount, "discount"),
        alias(discounted_price, "discounted_price"),
    )

print(response.results)
#    id name  price  discount  discounted_price
# 0   1    A   10.0      0.10               9.0
# 1   2    B   10.0      0.10               9.0
# 2   3    C   20.0      0.25              15.0

Besides Python strings, numbers, dates, datetimes, and Booleans, expressions involving objects and their properties may also be assigned to a ContextSelect object:

## Declare a Discount type and define some Discount objects.
Discount = model.Type("Discount")
with model.rule():
    Discount.add(rate=0.25).set(code="25OFF")
    Discount.add(rate=0.10).set(code="10OFF")


# Compute an item's discount based on its price.
with model.query() as select:
    item = Item()
    with model.match() as discount:
        # Items with a price greater than 15 get a 25% discount.
        with item.price > 15:
            discount.add(Discount(rate=0.25))
        # All other items get a 10% discount.
        with model.case():
            discount.add(Discount(rate=0.10))

    # Compute the discounted price. Properties of the Discount object can be
    # accessed directly from the discount variable.
    discounted_price = item.price * (1 - discount.rate)

    response = select(
        item.name,
        item.price,
        alias(discount.code, "discount_code"),
        alias(discounted_price, "discounted_price"),
    )

print(response.results)
#   name  price discount_code  discounted_price
# 0    A   10.0         10OFF               9.0
# 1    B   10.0         10OFF               9.0
# 2    C   20.0         25OFF              15.0

Optional keyword arguments may be passed to .add() to set properties on assigned values. These properties can only be accessed from the ContextSelect object:

#with model.query() as select:
    item = Item()
    with model.match() as discount:
        with item.price > 15:
            # Assign the Discount object with rate 0.25 to discount and set
            # the reason to property to provide context for the discount.
            discount.add(Discount(rate=0.25), reason="Over $15")
        with model.case():
            discount.add(Discount(rate=0.25), reason="$15 or less")

    discounted_price = item.price * (1 - discount.rate)

    response = select(
        item.name,
        item.price,
        alias(discount.code, "discount_code"),
        alias(discounted_price, "discounted_price"),
        alias(discount.reason, "reason"),  # Access the reason property set by discount.add().
    )

print(response.results)
#   name  price discount_code  discounted_price       reason
# 0    A   10.0         10OFF               9.0  $15 or less
# 1    B   10.0         10OFF               9.0  $15 or less
# 2    C   20.0         25OFF              15.0     Over $15

The same keyword argument keys must be provided each time you call .add() in one of the .match() block’s branches. Otherwise, an error will be raised.

Properties set in .add() take precedence over properties set elsewhere with the same name:

#with model.query() as select:
    item = Item()
    with model.match() as discount:
        with item.price > 15:
            # The code property set here takes precedence over the code property
            # set on the Discount object.
            discount.add(Discount(rate=0.25), code="SUMMER25")
        with model.case():
            discount.add(Discount(rate=0.10), code="SUMMER10")

    discounted_price = item.price * (1 - discount.rate)

    response = select(
        item.name,
        item.price,
        alias(discount.code, "discount_code"),
        alias(discounted_price, "discounted_price"),
    )

print(response.results)
#   name  price discount_code  discounted_price
# 0    A   10.0      SUMMER10               9.0
# 1    B   10.0      SUMMER10               9.0
# 2    C   20.0      SUMMER25              15.0

See Model.match() for more information on .match() contexts.

See Also#