Set up the Rel app
The Rel app is a browser-based workspace where your organization explores semantic models deployed to Snowflake. RelationalAI provisions and hosts each Rel app instance on RelationalAI-managed AWS and connects it to your Snowflake account over a standard connection or AWS PrivateLink. This guide walks an administrator through requesting an instance, connecting it to Snowflake, and opening a deployed model.
- Hands-on time
- 20 minutes
- Prerequisites
- A semantic model deployed to Snowflake with PyRel 2.0 or later. See Deploy a model.
- The RelationalAI Native App installed and activated in the same Snowflake account. See Set up RelationalAI in Snowflake.
- The
ACCOUNTADMINrole, or a role that can create roles, users, warehouses, network rules, and network policies and has theMANAGE GRANTSprivilege. - For PrivateLink only: an AWS account with a VPC in the same region as your Snowflake account, and a Snowflake account on Business Critical edition.
Request your Rel app instance
Section titled “Request your Rel app instance”RelationalAI creates your instance from a few details you provide. First, choose how the Rel app connects to your Snowflake account:
- Standard connection: The Rel app reaches Snowflake over the internet from a fixed RelationalAI IP address, and a network policy lets only that address use the Rel app’s Snowflake user. Users sign in at the instance URL.
- PrivateLink: The Rel app reaches Snowflake through AWS PrivateLink instead of the internet, and users open the Rel app from a network that can reach your VPC.
Your choice changes some steps in this guide. Select your connection in the following tabs, and every later section shows the matching steps.
-
Send your instance details
Send your RelationalAI account team the following:
- Your organization name. Choose it carefully, because the instance URL is derived from it.
- The AWS region for the instance, either
us-west-2orus-east-1. Choose the region closest to your Snowflake account.
Also send the people who can sign in:
- The email addresses of the Rel app’s administrators.
- The email domains, such as
example.com, and individual email addresses that can sign in.
-
Save the connection details you get back
After RelationalAI provisions your instance, you receive the following:
- The instance URL, in the form
https://<customer-id>.app.relational.ai. - The instance’s fixed outbound IP address. You need it to create a network policy later in this guide, so ask for it if it’s missing.
- The instance URL, in the form
-
Send your instance details
Send your RelationalAI account team the following:
- Your organization name. Choose it carefully, because the instance hostname is derived from it.
- Your 12-digit AWS account ID.
- Your VPC region, such as
us-west-2orus-east-1. It must be the same region as your Snowflake account.
Also send the people who can sign in:
- The email addresses of the Rel app’s administrators.
- The email domains, such as
example.com, and individual email addresses that can sign in.
-
Connect your VPC to the Rel app
RelationalAI sends you a VPC endpoint service name, a private hostname, and an availability zone (AZ) ID. In your AWS account, do the following:
- Create an interface VPC endpoint in your VPC to the service name.
- Set up internal DNS so the hostname resolves inside your VPC.
-
Run the Snowflake authorization script
RelationalAI sends you a SQL script that lets your Snowflake account confirm that RelationalAI owns the AWS account connecting to it. The script grants no permissions. Have a Snowflake
ACCOUNTADMINreview and run it. -
Send your PrivateLink configuration
Run the following SQL as
ACCOUNTADMIN:SELECT SYSTEM$GET_PRIVATELINK_CONFIG();Send RelationalAI the complete JSON result as text, not a screenshot. RelationalAI uses it to create a private endpoint to your Snowflake account.
-
Save the connection details you get back
RelationalAI sends you its VPC endpoint ID, which starts with
vpce-, and your account’s private account name, which ends in.privatelink. You need both later in this guide.
Create the Rel app’s Snowflake user
Section titled “Create the Rel app’s Snowflake user”The Rel app connects to Snowflake as a dedicated service user with its own role, warehouse, network policy, and access token.
Create the user and its access in a Snowsight SQL worksheet:
-
Create a role, warehouse, and service user
Run the following SQL:
USE ROLE ACCOUNTADMIN;CREATE ROLE IF NOT EXISTS REL_APP_ROLE;CREATE WAREHOUSE IF NOT EXISTS REL_APP_WHWAREHOUSE_SIZE = XSMALLAUTO_SUSPEND = 60AUTO_RESUME = TRUEINITIALLY_SUSPENDED = TRUE;CREATE USER IF NOT EXISTS REL_APP_USERTYPE = SERVICEDEFAULT_ROLE = REL_APP_ROLEDEFAULT_WAREHOUSE = REL_APP_WHCOMMENT = 'Rel app connection';GRANT ROLE REL_APP_ROLE TO USER REL_APP_USER;A dedicated warehouse keeps Rel app usage separate so you can track its cost. It suspends after 60 seconds without activity.
-
Allow only the Rel app to use the service user
Snowflake requires a network policy before a service user can use an access token. A user-level policy applies only to
REL_APP_USERand doesn’t change your account’s network policy. Create the network rule in a database and schema your administrators manage, not in the database that holds your deployed models.Allow the outbound IP address RelationalAI sent you:
CREATE NETWORK RULE <admin_database>.<admin_schema>.REL_APP_NETWORK_RULEMODE = INGRESSTYPE = IPV4VALUE_LIST = ('<rel_app_egress_ip>');Then create the policy and apply it to the service user:
CREATE NETWORK POLICY REL_APP_NETWORK_POLICYALLOWED_NETWORK_RULE_LIST = ('<admin_database>.<admin_schema>.REL_APP_NETWORK_RULE')COMMENT = 'Allow only the Rel app to connect as REL_APP_USER';ALTER USER REL_APP_USER SET NETWORK_POLICY = REL_APP_NETWORK_POLICY;If your organization manages network policies as code, make this change there instead.
-
Generate an access token
Run the following SQL to create a programmatic access token, or PAT, restricted to
REL_APP_ROLE:ALTER USER REL_APP_USER ADD PROGRAMMATIC ACCESS TOKEN REL_APP_PATROLE_RESTRICTION = 'REL_APP_ROLE'DAYS_TO_EXPIRY = 90COMMENT = 'Rel app connection';Copy the
token_secretvalue from the result into your password manager now. Snowflake shows the secret only when you create the token. You can setDAYS_TO_EXPIRYfrom 1 up to your account’s maximum, which is 365 days by default.Check your authentication policy
If your account uses an authentication policy, confirm that the effective policy for
REL_APP_USERallowsPROGRAMMATIC_ACCESS_TOKEN. Ask your Snowflake administrator to inspect or update the policy if needed.Rotate the token before it expires
The Rel app stops connecting to Snowflake when the token expires. Record the expiry date, and before then, run the following SQL:
ALTER USER REL_APP_USER ROTATE PROGRAMMATIC ACCESS TOKEN REL_APP_PAT;Then paste the new
token_secretinto Settings → Snowflake PAT in the Rel app and choose Save settings. If the LLM provider is Snowflake Cortex and you use the same token for LLM calls, also update the separate Cortex PAT under LLM. The Rel app stores these tokens separately, so rotating one doesn’t update the other. See Using programmatic access tokens in the Snowflake documentation for details.
-
Create a role, warehouse, and service user
Run the following SQL:
USE ROLE ACCOUNTADMIN;CREATE ROLE IF NOT EXISTS REL_APP_ROLE;CREATE WAREHOUSE IF NOT EXISTS REL_APP_WHWAREHOUSE_SIZE = XSMALLAUTO_SUSPEND = 60AUTO_RESUME = TRUEINITIALLY_SUSPENDED = TRUE;CREATE USER IF NOT EXISTS REL_APP_USERTYPE = SERVICEDEFAULT_ROLE = REL_APP_ROLEDEFAULT_WAREHOUSE = REL_APP_WHCOMMENT = 'Rel app connection';GRANT ROLE REL_APP_ROLE TO USER REL_APP_USER;A dedicated warehouse keeps Rel app usage separate so you can track its cost. It suspends after 60 seconds without activity.
-
Allow only the Rel app to use the service user
Snowflake requires a network policy before a service user can use an access token. A user-level policy applies only to
REL_APP_USERand doesn’t change your account’s network policy. Create the network rule in a database and schema your administrators manage, not in the database that holds your deployed models.Allow the
vpce-endpoint ID RelationalAI sent you:CREATE NETWORK RULE <admin_database>.<admin_schema>.REL_APP_NETWORK_RULEMODE = INGRESSTYPE = AWSVPCEIDVALUE_LIST = ('<relationalai_vpce_id>');Then create the policy and apply it to the service user:
CREATE NETWORK POLICY REL_APP_NETWORK_POLICYALLOWED_NETWORK_RULE_LIST = ('<admin_database>.<admin_schema>.REL_APP_NETWORK_RULE')COMMENT = 'Allow only the Rel app to connect as REL_APP_USER';ALTER USER REL_APP_USER SET NETWORK_POLICY = REL_APP_NETWORK_POLICY;If your organization manages network policies as code, make this change there instead.
Then tell your RelationalAI contact that you allowed their endpoint.
-
Generate an access token
Run the following SQL to create a programmatic access token, or PAT, restricted to
REL_APP_ROLE:ALTER USER REL_APP_USER ADD PROGRAMMATIC ACCESS TOKEN REL_APP_PATROLE_RESTRICTION = 'REL_APP_ROLE'DAYS_TO_EXPIRY = 90COMMENT = 'Rel app connection';Copy the
token_secretvalue from the result into your password manager now. Snowflake shows the secret only when you create the token. You can setDAYS_TO_EXPIRYfrom 1 up to your account’s maximum, which is 365 days by default.Check your authentication policy
If your account uses an authentication policy, confirm that the effective policy for
REL_APP_USERallowsPROGRAMMATIC_ACCESS_TOKEN. Ask your Snowflake administrator to inspect or update the policy if needed.Rotate the token before it expires
The Rel app stops connecting to Snowflake when the token expires. Record the expiry date, and before then, run the following SQL:
ALTER USER REL_APP_USER ROTATE PROGRAMMATIC ACCESS TOKEN REL_APP_PAT;Then paste the new
token_secretinto Settings → Snowflake PAT in the Rel app and choose Save settings. If the LLM provider is Snowflake Cortex and you use the same token for LLM calls, also update the separate Cortex PAT under LLM. The Rel app stores these tokens separately, so rotating one doesn’t update the other. See Using programmatic access tokens in the Snowflake documentation for details.
Grant Snowflake access
Section titled “Grant Snowflake access”Grant the Rel app’s role access to the database that holds your deployed models and to the data those models read:
-
Grant access to the persistence database
The persistence database is the database your models deploy into. It’s the database part of
deployment.public_schemain your model’sraiconfigfile, which has the form<DATABASE>.<SCHEMA>. See Configure deployment for details. The model’sdeployment.identity.internal_schemamust be in the same database.The Rel app lists every model in this database, so deploy future models there too.
Run the following SQL, replacing
<persistence_database>with your database name:-- Run as an administrator with MANAGE GRANTS. Running it again is safe.GRANT USAGE ON WAREHOUSE REL_APP_WH TO ROLE REL_APP_ROLE;GRANT USAGE ON DATABASE <persistence_database> TO ROLE REL_APP_ROLE;-- New models: the service role creates and owns its own model schemas.GRANT CREATE SCHEMA ON DATABASE <persistence_database> TO ROLE REL_APP_ROLE;-- Deploys run their refresh tasks once (run_on_deploy).GRANT EXECUTE TASK ON ACCOUNT TO ROLE REL_APP_ROLE;-- Discover and read every model, including ones other roles deploy. PyRel 2.0-- publishes outputs as views and may store _META data as views or dynamic-- tables; Snowflake grants each object type separately.GRANT USAGE ON ALL SCHEMAS IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT USAGE ON FUTURE SCHEMAS IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON ALL TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON FUTURE TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON ALL VIEWS IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON FUTURE VIEWS IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON ALL DYNAMIC TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT SELECT ON FUTURE DYNAMIC TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;-- Write-back inserts into _INTERNAL_OPLOG and updates _INTERNAL_OPLOG_HEAD.-- Snowflake can't limit an ALL or FUTURE grant to those names, so this covers-- every table in the database; keep the database for models only.GRANT INSERT, UPDATE ON ALL TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;GRANT INSERT, UPDATE ON FUTURE TABLES IN DATABASE <persistence_database> TO ROLE REL_APP_ROLE;Models deployed by another role can be opened and edited when
REL_APP_ROLEhas the grants above, but the Rel app can’t redeploy them. Redeploying requires ownership of the deployed objects. -
Grant access to source data and RelationalAI
The Rel app reads your model’s source tables and calls RelationalAI reasoners through the RAI Native App. Run the first four statements once for each database and schema your model reads from:
GRANT USAGE ON DATABASE <source_database> TO ROLE REL_APP_ROLE;GRANT USAGE ON SCHEMA <source_database>.<source_schema> TO ROLE REL_APP_ROLE;GRANT SELECT ON ALL TABLES IN SCHEMA <source_database>.<source_schema> TO ROLE REL_APP_ROLE;GRANT SELECT ON ALL VIEWS IN SCHEMA <source_database>.<source_schema> TO ROLE REL_APP_ROLE;GRANT APPLICATION ROLE RELATIONALAI.RAI_USER TO ROLE REL_APP_ROLE;If you installed the RAI Native App under a name other than
RELATIONALAI, use that name in the last statement.Optional: grant access to future source tables and views
If your model will read tables or views created later in a source schema, you can grant access to them with:
GRANT SELECT ON FUTURE TABLES IN SCHEMA <source_database>.<source_schema> TO ROLE REL_APP_ROLE;GRANT SELECT ON FUTURE VIEWS IN SCHEMA <source_database>.<source_schema> TO ROLE REL_APP_ROLE;Review the schema’s existing future grants before running these statements. Snowflake applies schema-level future grants instead of database-level future grants for the same object type in that schema, even when they target different roles. See Snowflake future-grant precedence.
Connect the Rel app to Snowflake
Section titled “Connect the Rel app to Snowflake”Enter the service user’s details in the Rel app’s settings:
-
Sign in
Open your instance URL. Enter your administrator email address and select the sign-in link sent to your inbox.
-
Open Settings
Select your avatar to open the profile menu, then choose Settings. Only administrators see Settings.
-
Set model storage
In Model storage, choose Snowflake deployed mode. Then enter your persistence database in Persistence database.
-
Enter the Snowflake connection
In Snowflake, enter your account identifier,
<orgname>-<account_name>, in Account.Then fill in the remaining fields:
- Warehouse:
REL_APP_WH. - User:
REL_APP_USER. Enter the service user’s name, even though the field’s placeholder shows an email address. - Role:
REL_APP_ROLE. - Snowflake PAT: the
token_secretvalue you copied.
- Warehouse:
-
Save and check the connection
With Snowflake deployed mode selected, choose Save settings. The Rel app validates the Snowflake connection and confirms that its service role can discover and read models in the persistence database. The check doesn’t create Snowflake objects or prove that the service role can write to every existing model or create new ones. When you change Model storage, the page reloads after saving. Saved settings take effect without redeploying anything.
If saving reports missing grants, choose View grant SQL in Model storage. Have a Snowflake administrator review and run the additive grant statements. Run the final read-only verification block as yourself. It checks the configured service role without switching to it. If it reports
Nothing missing., the check found no missing privileges on the sample persistence objects it checked. It doesn’t prove access to every object or that the role can create or redeploy models. Then choose Save settings again.
-
Sign in
From a computer that can reach your VPC, open the private hostname RelationalAI sent you. Enter your administrator email address and select the sign-in link sent to your inbox.
If the private hostname doesn’t load, check your VPC endpoint and internal DNS, then contact your RelationalAI representative.
-
Open Settings
Select your avatar to open the profile menu, then choose Settings. Only administrators see Settings.
-
Set model storage
In Model storage, choose Snowflake deployed mode. Then enter your persistence database in Persistence database.
-
Enter the Snowflake connection
In Snowflake, enter the private account name RelationalAI sent you,
<orgname>-<account_name>.privatelink, in Account. The Rel app connects over PrivateLink only when the account name ends in.privatelink.Then fill in the remaining fields:
- Warehouse:
REL_APP_WH. - User:
REL_APP_USER. Enter the service user’s name, even though the field’s placeholder shows an email address. - Role:
REL_APP_ROLE. - Snowflake PAT: the
token_secretvalue you copied.
- Warehouse:
-
Save and check the connection
With Snowflake deployed mode selected, choose Save settings. The Rel app validates the Snowflake connection and confirms that its service role can discover and read models in the persistence database. The check doesn’t create Snowflake objects or prove that the service role can write to every existing model or create new ones. When you change Model storage, the page reloads after saving. Saved settings take effect without redeploying anything.
If saving reports missing grants, choose View grant SQL in Model storage. Have a Snowflake administrator review and run the additive grant statements. Run the final read-only verification block as yourself. It checks the configured service role without switching to it. If it reports
Nothing missing., the check found no missing privileges on the sample persistence objects it checked. It doesn’t prove access to every object or that the role can create or redeploy models. Then choose Save settings again.
Give users access
Section titled “Give users access”Choose who can sign in, then share the Rel app’s address.
Give users access:
-
Choose who can sign in
In Settings, go to the Access section and edit these fields:
- Administrator emails: people who can change settings.
- Allowed domains: email domains whose users can sign in, such as
example.com. - Allowed emails: individual email addresses outside those domains.
Separate values with commas, then choose Save settings.
-
Share the instance URL
Share the instance URL with allowed users.
The Rel app doesn’t send invitations. Allowed users open the address you share and request a sign-in link.
-
Choose who can sign in
In Settings, go to the Access section and edit these fields:
- Administrator emails: people who can change settings.
- Allowed domains: email domains whose users can sign in, such as
example.com. - Allowed emails: individual email addresses outside those domains.
Separate values with commas, then choose Save settings.
-
Share the private hostname
Share the private hostname with allowed users. They must open it from a network that can reach your VPC.
The Rel app doesn’t send invitations. Allowed users open the address you share and request a sign-in link.
Open a deployed model
Section titled “Open a deployed model”Open and edit a model to confirm that the Rel app can read its deployed objects and save a model change:
-
In the model sidebar, open the menu next to the logo, labeled Switch ontologies.
-
Choose Browse ontologies, or press Shift + M.
-
Select your model, then choose Open model. You can also double-click the model or press Enter. When Loading ontology finishes, your model’s name appears at the top of the model sidebar.
-
Make a small, reversible edit to a model you’re authorized to change, then save it. Confirm that the change appears in the model after saving. If it isn’t saved, ask an administrator to check Model storage and review View grant SQL for missing persistence grants. If no grants are missing, confirm the selected persistence database and Snowflake connection in Settings.
If no model is in the URL, the Rel app opens the first model automatically. It checks the persistence database for new models every 30 seconds.
If your model isn’t listed
Section titled “If your model isn’t listed”Check the following:
- Make sure the model deployed to the persistence database. That’s the database in the model’s
deployment.public_schema, and itsdeployment.identity.internal_schemamust be in the same database. - Wait 30 seconds for the next check, then open Browse ontologies again.
- If the Rel app shows Model persistence needs attention, open Settings and check the persistence database. If View grant SQL reports missing grants, have an administrator review and run the additive statements.
- If the Rel app shows Snowflake needs a quick fix, check the token’s expiry date and the network policy.
- If your account uses an authentication policy, confirm that the effective policy for the service user allows
PROGRAMMATIC_ACCESS_TOKEN. Ask a Snowflake administrator to update it if needed, then update Settings. - If the Rel app says a newer RelationalAI version deployed the model, redeploy it with the PyRel version the message names.
- If the Rel app says an older RelationalAI version deployed the model, follow the message. You must tear down the model and deploy it again with the current version, which deletes its deployed data.
If a model query can’t read a source object
Section titled “If a model query can’t read a source object”A query can report Snowflake role REL_APP_ROLE can't read an object this query uses.
Confirm that the named object exists, then check that REL_APP_ROLE has USAGE on its database and schema and SELECT on the object.
The error can indicate a missing object or insufficient privileges.
If the object is missing, correct the source reference or restore the object.
If the role needs access, run the source-data grants in Grant Snowflake access.
Where to go next
Section titled “Where to go next”After setup, use these guides to work with the models in your Rel app: