InstanceProperty.in_()#
#InstanceProperty.in_(others: Iterable[Any]) -> Expression
Checks if any of the values produced by InstanceProperty
are contained in others
.
Returns an Expression
that filters objects and property values
based on their membership in the others
iterable.
Must be used in a rule or query context.
Parameters#
Name | Type | Description |
---|---|---|
others | Iterable[Any] | Collection of values for checking membership. Supports Producer objects, numbers, strings, dates, and datetime objects. |
Returns#
An Expression
object that filters objects and property values based on their membership in the others
collection.
Example#
Use .in_()
to filter objects in a rule or query context,
checking if their property values exist within a specified collection:
#import relationalai as rai
# Create a model named "books" with a Book type.
model = rai.Model("books")
Book = model.Type("Book")
# Add some books to the model.
with model.rule():
Book.add(title="Foundation", author="Isaac Asimov")
Book.add(title="Cat's Cradle", author="Kurt Vonnegut")
Book.add(title="Dune", author="Frank Herbert")
# Get the titles of books written by Kurt Vonnegut or the author of Foundation.
with model.query() as select:
book = Book() # Get all book objects.
book.author.in_(["Kurt Vonnegut", Book(title="Foundation").author]) # Filter books by author in the collection.
response = select(book.title, book.author) # Select the title and author properties of the books.
print(response.results)
# Output:
# title author
# 0 Cat's Cradle Kurt Vonnegut
# 1 Foundation Isaac Asimov
In the above example, book
is an Instance
that produces Book
objects.
book.author.in_()
returns an Expression
that filters books to include
only those authored by "Kurt Vonnegut"
or the author of "Foundation"
.
If no authors from the collection match, the query yields no results:
#with model.query() as select:
book = Book() # Get all book objects.
book.author.in_(["Ted Chiang", "J.R.R. Tolkien"]) # Filter books by author in the collection.
response = select(book.title, book.author) # Select the title and author properties of the books.
print(response.results)
# Output:
# Empty DataFrame
# Columns: []
# Index: []
.in_()
also works with multi-valued properties,
such as properties created with .add()
or .extend()
:
## Add genres to the books.
# The genre property is multi-valued because it is created with Instance.extend().
with model.rule():
Book(title="Foundation").genres.extend(["Science Fiction", "Space Opera"])
Book(title="Cat's Cradle").genres.extend(["Science Fiction", "Satire"])
Book(title="Dune").genres.extend(["Science Fiction", "Space Opera"])
# Get books with the genre "Satire", "Fantasy", or both.
with model.query() as select:
book = Book() # Get all book objects.
book.genres.in_(["Satire", "Fantasy"]) # Filter books by genre in the collection.
response = select(book.title, book.author, book.genres) # Select the title and genre properties of the books.
print(response.results)
# Output:
# title author genres
# 0 Cat's Cradle Kurt Vonnegut Satire
Note that only the "Satire"
genre appears in the results.
This is because book.genres
produces multiple values, and .in_()
filters both the book
objects and their genres
.
Consequently, only genres that meet the filter criteria are included in the final results.