Skip to main content

Work with data and functions in apps

Connect to data sources and use functions in apps.

Use this guide to learn how to connect resources and write functions in apps. For the full list of resources available in apps, refer to the resources reference.

Connect resources​

As you build, the agent connects resources to your app. You can also prompt the agent to create REST API or PostgreSQL resources. The agent can only create resources if you have Own access to resources, or connect resources for which you have Edit access. Learn more about access rules.

When building an app, you can suggest that the agent uses a particular resource by @-tagging it by name. If you don't know what resource is most appropriate, the agent can view the schemas of available resources and intelligently suggest those to which you can connect. You can always deny or remove these resources.

Admins control who can use, edit, and manage resources at an organization level. They can also create resource environments to further control access to sensitive production data.

Use resource environments​

Organizations on paid plans can use resource environments to run a function against different configurations of the same resource, such as staging and production. Admins create environments and configure resources for them. The mechanism for switching environments is different between the app building experience and the published app experience.

Refer to the Troubleshooting guide for help troubleshooting resource environments.

Switch environments while building​

While editing an app in the app builder, use the environment selector in the status bar to choose an environment. The app preview reloads on each switch to present the new data. A function only runs if its resources are configured in the selected environment and you have permissions to run functions in that environment.

Switch environments for a published app​

Published apps open in production by default. To open an app in another environment, add the _environment URL query parameter to its URL, such as ?_environment=staging.

Published apps do not include a visual environment toggle. This enables you to optionally design how to control environment-specific behavior for your app, such as a picker in the header or a banner, using the useEnvironment hook. Learn more about the structure of this hook. To let users switch environments in a published app, prompt the agent to add the UI element you want.

I want to use this app across resource environments. Add a dropdown in the top right corner.

Switching environments in a published app restarts the app and resets its state.

Manage access to environments​

Users need Use access to a resource in an environment to run functions against it there. Learn more in Resource permissions.

If a resource requires authentication, users must re-authenticate the first time they switch to a different resource environment.

If you use Source Control to protect resources, only the production environment of a protected resource is tracked. Learn more in Protect resources with Source Control.

Write functions​

Code in your app that accesses a resource is called a function. While the agent is building, you will be asked to approve functions before they run. You can also click See details to open the Function playground.

If you cancel the function run, the agent asks you what can be done to improve the function with a pop-up in the Build tab.

Function playground​

Inside the Function playground, you can view and edit the parameters for the function, run the function, and view the function's run history.

You can also choose to view the exact code that the function runs against the resource, or visualize the control flow of the function as connected blocks, similar to a workflow.

Function limits​

Retool imposes certain limitations on functions to ensure that your apps remain performant:

  • 10 MB limit on function inputs.
  • 60 second limit before timeout.
  • 200 MB memory limit.
  • 100 function runs per minute, per user rate limit.
  • Varied limits on maximum concurrent function runs per user:
    • 50 concurrent function runs when triggered from the app builder.
    • 10 concurrent function runs when triggered from the MCP or CLI.
note

Resource queries that run inside a function have a default timeout of 12 minutes. Self-hosted instances can change this timeout with WORKFLOW_DBCONNECTOR_QUERY_TIMEOUT_MS. This timeout only applies if it is lower than 60 seconds, which is the timeout limit for the function as a whole.

Trigger workflows​

To trigger a workflow from your app, open the Chat tab and prompt your agent with the workflow's name.

Update my app so that the Customer Feedback table retrieves data using the Retrieve Survey Feedback workflow.
Create a new app that tracks our quarterly sales KPIs. For the data, use the Calculate Conversion Rate workflow as well as the lifetime_value and quota_attainment tables in @Retool Database.

The triggered workflow is run on behalf of the app's authenticated user.

Return data to the app​

Workflows run from within an app operate in a similar way to a webhook-triggered workflow.

In order to make data from the workflow available to the app, you must include a Response block in the workflow. The data returned from the Response block is sent to the app once the workflow run completes. If you want to trigger a workflow without returning data back to the app, you don't need a Response block.

Access user and account information​

Retool provides a set of custom React hooks (reference) that give your app information about the signed-in user and the apps they can open, and let the app act on the user's Retool account.

note

These hooks enable certain User Actions that are supported in classic apps.

You can use hooks to:

  • Greet the user by name or show content based on their permission groups.
  • Add a button that signs the user out of Retool.
  • Build a custom launcher that lists the apps and folders the user can access.

To use a hook, describe what you want in the Chat tab, and the agent will identify the appropriate hook to use. You can also implement the hook manually.

Show a welcome message with the current user's first name.
Add a sign-out button to the header.
Create a launcher page that shows a tile for each app and folder the current user can access.

For the properties each hook returns, refer to the hooks reference.

Capabilities and limitations​

The following tabs show a summary of the current capabilities of the app builder. Limitations describe functionality that isn't yet supported in apps but may exist in classic apps.

  • Connect to data through Retool resources.
  • Tag a specific resource with @ in the Chat tab to direct the agent.
  • Let the agent investigate resource schemas and suggest the most appropriate resource.
  • Compose multi-step, strongly-typed functions that combine resource queries and JavaScript queries.
  • Run functions serverlessly on Retool's backend.
  • Test functions with sample parameters in the Function playground.
  • Run functions against different resource environments.
  • Trigger workflows from functions.
  • Read the current user, sign users out, and list the apps and folders they can access with hooks.