Model#

relationalai
class Model(
    name: str,
    *,
    format: str = "default",
    profile: str | None = None,
    connection: SnowflakeConnection | None = None
)

A RelationalAI model is made up of objects, which represent real-world entities and are categorized by type, and rules that describe objects and the relationships between them. The Model class is used to create, manage, and query models.

Parameters#

NameTypeDescription
namestrThe name of the model. Must be at least three characters. May only contain letters, numbers, and underscores.
formatstrOptional format for query responses. Default is "default", which stores results as a pandas DataFrame. Use "snowpark" to get results as a Snowpark DataFrame.
profilestr or NoneOptional name of the configuration profile to use when creating the model. If None, the currently active profile is used.
connectionSession or NoneOptional Snowpark Session object to use when creating the model. If None, connection details in the configuration profile set by the profile parameter are used. Ignored in Azure-based projects.

Attributes#

NameTypeDescription
.namestrThe name of the model.

Methods#

NameDescriptionReturns
.Type()Creates a Type for categorizing objects in the model.Type
.rule()Adds a rule to the model.Context
.query()Queries the model.Context
.export()Exports a Python function as a Snowflake stores procedure. Used as a decorator.Callable

.rule() and .query() are Python context managers and must be used in a with statement. The with block defines the scope of the rule or query and is where you define the rule or query logic using the RelationalAI query-builder syntax.

The following methods create contexts for expressing conditional logic in rules and queries and must be called from inside a .rule() or .query() context’s with block:

NameDescriptionReturns
.found()Checks that a subquery has at least one result.Context
.not_found()Checks that a subquery has no results.Context
.match()Matches objects to one or more subqueries. Similar to a Python match or a SQL CASE statment.Context
.case()Creates a subquery inside of a .match() context.Context

Example#

import relationalai as rai

# Create a new model named "people."
model = rai.Model("people")

# Get the Person table from the 'sandbox.public' schema in Snowflake.
Person = model.Type("Person", source="sandbox.public.person")

# Create an Adult type in the model.
Adult = model.Type("Adult")

# The model.rule() context manager is used to define rules in the model.
# This rule adds all people over 18 to the Adult type.
with model.rule():
    person = Person()
    person.age >= 18
    person.set(Adult)

# The model.query() context manager is used to query the model.
# This query returns the names of all adults in the model.
with model.query() as select:
    adult = Adult()
    response = select(adult.name)

print(response.results)
# Output:
#     name
# 0  Alice
# 1    Bob
IMPORTANT

Before you can access a Snowflake table in a model, such as the sandbox.public.person table in the preceding example, you must import the table using the rai imports:stream CLI command or the RelationalAI SQL Library. Your Snowflake user must have the correct privileges to create a stream on the table. Contact your Snowflake administrator if you need help importing a Snowflake table.

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 model:

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

# ...

with model.query() as select:
    adult = Adult()
    response = select(adult.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"  |
# ----------
# |Bob     |
# |Alice   |
# ----------

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

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

You may also export a Python function as a Snowflake stored procedure using the .export() method, allowing Snowflake SQL users to interact with the model:

# Export a function to the `sandbox.public` schema in Snowflake.
# The stored procedure is named "get_adults_by_age".
# NOTE: Type hints are required for the function parameters and return values.

from typing import Tuple

@model.export("sandbox.public")
def get_adults_by_age(age: int) -> Tuple[str, int]:
    adult = Adult(age=age)
    return adult.name, adult.age

# The stored procedure can be called in Snowflake SQL:
# CALL sandbox.public.get_adults_by_age(21);

Anything you can do in a query context can be done in an exported function, including advanced logic and graph analytics. See .export() for more details.

To use a configuration profile other than the active profile, pass the profile name to the profile parameter when creating the model:

# NOTE: The profile name must be passed as a keyword argument.
model = rai.Model("people", profile="my_profile")

To use a Snowpark Session other than the one specified in the configuration profile, pass a Session object to the connection parameter when creating the model:

from snowflake.snowpark import Session

connection_parameters = {
    "user": <USER>,
    "password": <PASSWORD>,
    "account": <ACCOUNT>,
    "warehouse": <WAREHOUSE>,
    "database": <DATABASE>,
    "schema": <SCHEMA>
)

conn = Session.builder.configs(connection_parameters).create()

# NOTE: The connection object must be passed as a keyword argument.
model = rai.Model("people", connection=conn)

See the Snowflake docs for more details on creating Snowpark Session objects.

See Also#