extend()#
#InstanceProperty.extend(others: Iterable[Any]) -> None
Extends a multi-valued property of an Instance
with values
from an iterable and creates the property if it doesn’t exist.
Must be used in a rule or query context.
Parameters#
Name | Type | Description |
---|---|---|
others | Iterable[Any] | The values to add to the property. Acceptable value types include Producer objects, as well as numbers, strings, dates, and datetime objects. |
Returns#
None
Example#
#import relationalai as rai
# Create a model named "books" with Author and Book types.
model = rai.Model("books")
Author = model.Type("Author")
Book = model.Type("Book")
# Add multiple books to an author using extend.
with model.rule():
herbert = Author.add(name="Frank Herbert")
herbert.books.extend([
Book.add(title="Dune"),
Book.add(title="Dune Messiah"),
Book.add(title="Children of Dune")
])
# Get the titles of books written by Frank Herbert.
with model.query() as select:
# Get all books by Frank Herbert.
book = Author(name="Frank Herbert").books
# Select the title property of the book.
response = select(book.title)
print(response.results)
# Output:
# title
# 0 Children of Dune
# 1 Dune
# 2 Dune Messiah
In the example above, herbert.books.extend()
creates the multi-valued property books
for the herbert
object.
In contrast, the Author.name
property is single-valued as it is defined through Type.add()
.
Single-valued properties can also be established using Instance.set()
.
Calling InstanceProperty.extend()
on a single-valued property raises an Exception
:
## Attempting to extend the author name property with multiple values fails.
# The author property is single-valued because it was created with Type.add().
with model.rule():
Author(name="Isaac Asimov").name.extend(
["Franklin Herbert", "Franklin Patrick Herbert, Jr."]
)
# Output:
# Exception: Trying to use a property `name` as both singular and multi-valued
Single values can be added to a multi-valued property by passing an iterable containing one value,
or directly using the InstanceProperty.add()
method.
You can extend multi-valued properties across multiple rules.
For instance, the next rule adds two more books to Frank Herbert’s books
property:
#with model.rule():
author = Author(name="Frank Herbert")
author.books.extend([
Book.add(title="God Emperor of Dune"),
Book.add(title="Heretics of Dune")
])