Model.query()#

relationalai
#Model.query(dynamic: bool = False, format: str = "default") -> Context

Creates a query Context.

Parameters#

NameTypeDescription
dynamicboolWhether or not the query is dynamic. Dynamic queries support Python control flow as macros. See Context for more information.
formatstrOptional format for query responses. Default is "default", which stores results as a pandas DataFrame. Use "snowpark" to get results as a Snowpark DataFrame.

Returns#

A Context object.

Example#

Model.query() is a context manager and should be called in a with statement. Use the as part of the with statement to assign the ContextSelect object created by Model.query() to a variable named select so that you may select query results:

#import relationalai as rai

model = rai.Model("people")
Person = model.Type("Person")

# Add people to the model.
with model.rule():
    alex = Person.add(name="Alex", age=19)
    bob = Person.add(name="Bob", age=47)
    carol = Person.add(name="Carol", age=17)

# A `with model.query() as select` block begins a new query.
# `select` is a `ContextSelect` object used to select query results.
with model.query() as select:
    person = Person()
    response = select(person.name)

# Query results are stored in the `results` attribute of the response.
# The `results` attribute is a pandas DataFrame by default.
print(response.results)
# Output:
#     name
# 0   Alex
# 1    Bob
# 2  Carol

You write queries using RelationalAI’s declarative query builder syntax. See Getting Started with RelationalAI for an introduction to writing queries.

By default, query results are returned as a pandas DataFrame, which downloads to your local machine and can be slow down large datasets. To keep results in Snowflake and avoid downloads, use format="snowpark" when creating the query:

#with model.query(format="snowpark") as select:
    person = Person()
    response = select(person.name)

# The response is a Snowpark DataFrame.
print(response.results)
# Output:
# <snowflake.snowpark.dataframe.DataFrame object at 0x1313d3590>

# To view the contents of the Snowpark DataFrame, use the .show() method.
response.results.show()
# Output:
# ----------
# |"NAME"  |
# ----------
# |Alex    |
# |Bob     |
# |Carol   |
# ----------

# To save results to a table in Snowflake, use the .write() method.
response.results.write.save_as_table("sandbox.public.people")

Alternatively, you may set format="snowpark" when creating the model to return Snowpark DataFrames by default for all queries:

## NOTE: The format parameter must be passed as a keyword argument.
model = rai.Model("people", format="snowpark")

Refer to the Snowflake documentation for details on working with Snowpark DataFrames.

Note that you may pass data from your Python application into a query:

#name_to_find = "Carol"
property_to_find = "age"

with model.query() as select:
    person = Person(name=name_to_find)
    prop = getattr(person, property_to_find)
    response = select(prop)

print(response.results)
# Output:
#    age
# 0   17

Here, the Python variables name_to_find and property_to_find are used directly in the query. Python’s built-in getattr() function gets the person property with the name property_to_find.

By default, queries do not support while and for loops and other flow control tools such as if and match. You can enable flow control by setting the dynamic parameter to True, which lets you use Python flow control as a macro to build up a query dynamically:

## Application is being used by an external user.
IS_INTERNAL_USER = FALSE

with model.query() as select:
    person = Person()
    if not IS_INTERNAL_USER:
        Public(person)
    response = select(person.name, person.age)

In this query, the application user’s state determines whether or not to include a condition. If the user is external, only Public objects are selected.

See Also#