relationalai.dsl.Instance

class Instance

Instance is a subclass of Producer that produces model objects in rule and query contexts. They are created by calling a Type or the Type.add() method.

Example

Instance objects act as variables representing model objects in rules and queries. Here’s how to create and manipulate an Instance:

import relationalai as rai

# Create a model named "people" with a Person type.
model = rai.Model("people")
Person = model.Type("Person")

# Add a person to the model.
with model.rule():
    # Add a person named "Kermit" to the model.
    # Person.add() returns an Instance.
    kermit = Person.add(name="Kermit")
    # Set Kermit's favorite color to "green" using Instance.set().
    kermit.set(favorite_color="green")

    # Add a person named "Rolf" to the model.
    rolf = Person.add(name="Rowlf")
    # Set Rolf's favorite color to "brown" using Instance.set().
    rolf.set(favorite_color="brown")

with model.query() as select:
    # Get all Person objects.
    # Person() returns an Instance.
    person = Person()
    # Filter objects by name.
    person.name == "Kermit"
    # Select the name and favorite_color properties of the Person objects.
    # Properties are accessed as Instance attributes.
    response = select(person.favorite_color)

print(response.results)
# Output:
#      name favorite_color
# 0  Kermit          green

In the above example’s rule:

1. Person.add(name="Kermit") returns an Instance that produces a Person object with a name property set to the string "Kermit".
2. kermit.set(favorite_color="green") sets Kermit’s favorite_color property to the string "green". Property values may also be numbers, dates, datetime objects, or None. favorite_color is single-valued, meaning setting it a second time overwrites the previous value. See the .set() method docs for more information on single- and multi-valued properties. Note that kermit.set() returns the kermit instance, although it is not used here.

In the query:

3. Person() returns an Instance that produces Person objects.
4. person.name == "Kermit" filters the objects produced by Person(), letting only those with the name "Kermit" pass through. Alternatively, you may combine this line with the first as person = Person(name="Kermit").
5. select(person.favorite_color) selects the favorite_color property of the remaining objects.

person.name and person.favorite_color return InstanceProperty objects, a type of producer that represents object properties. The == operator returns an Expression, yet another type of producer that filters objects based on whether or not the expression evaluates to True.

Methods

In addition to the methods inherited from Producer, Instance supports:

Name	Description	Returns
.set(*args, **kwargs)	Set a Type or a property on an object.	Instance

.set()

Instance.set(*args, **kwargs) -> Instance

Set properties and assign types to an Instance object and return the Instance. Must be used in a rule or query context.

Parameters

Name	Type	Description
*args	Type	Optional types to apply to the object.
*kwargs	Any	Properties to set on the Instance, using <property_name>=<value>. Accepts Producer objects, numbers, strings, dates, and datetime objects.

Returns

Returns the Instance object on which the property or type is set.

Example

Use .set() to set properties and assign types to an object in your model:

import relationalai as rai

# Create a model named "people" with a Person type.
model = rai.Model("people")
Person = model.Type("Person")
Musician = model.Type("Musician")

with model.rule():
    # Add Person named "Kermit" to the model.
    kermit = Person.add(name="Kermit")
    # Set Kermit as a Musician and set his favorite_color property to "green."
    kermit.set(Musician, favorite_color="green")

Both Type.add() and Instance.set() set properties on objects. Person.add() initially adds an object with the name property set to "Kermit" and assigns it to the variable kermit. Subsequently, kermit.set(Musician, favorite_color="green") assigns the Musician type to the kermit object and sets his favorite_color to “green”. Unlike Instance.set(), properties set by Type.add() function like primary keys in a SQL database, uniquely identifying each object.

You can assign multiple types and set several properties simultaneously by passing multiple Type objects as positional arguments and multiple property values as keyword arguments to .set().

Properties created by both Type.add() and Instance.set() are single-valued. Setting a property a second time overwrites the previous value:

# Get Kermit's favorite color.
with model.query() as select:
    person = Person(name="Kermit")
    response = select(person.favorite_color)

# Currently, it is "green."
print(response.results)
# Output:
#   favorite_color
# 0          green

# Change Kermit's favorite color to "blue."
with model.rule():
    kermit = Person(name="Kermit")
    kermit.set(favorite_color="blue")

# Get Kermit's favorite color again.
with model.query() as select:
    person = Person(name="Kermit")
    response = select(person.favorite_color)

print(response.results)
# Output:
#   favorite_color
# 0           blue

Attempting to set a multi-valued property using .set() raises an Exception:

# Add a friends property to Kermit.
# friends is a multi-valued property because it is created with InstanceProperty.extend().
with model.rule():
    kermit = Person(name="Kermit")
    kermit.friends.extend(["Fozzie", "Miss Piggy", "Rowlf"])

# Attempt to set friends to "Gonzo" using .set().
with model.rule():
    kermit = Person(name="Kermit")
    kermit.set(friends="Gonzo")

# Output:
# Exception: Trying to use a property `friends` as both singular and multi-valued

See the InstanceProperty documentation for more information on multi-valued properties.

See Also

• Expression
• InstanceProperty
• Model.query()
• Model.rule()
• Producer
• Type