# Example Usage

### Calling simple, static commands

Any command supplied to a Shell Script query will be executed on the remote host. A simple application might allow a user to click a button to get the uptime of that machine. To do this, we need a query that calls "uptime", a button to trigger this query, and a place to display the result.

![Uptime query](https://d3399nw8s4ngfo.cloudfront.net/docs/rd/8716af3-Screen_Shot_2021-07-23_at_5.01.31_PM.png)

The result of a Shell Script query is an object with three keys:

- `exitCode`: the exit code from the process
- `stdErr`: standard error from the process
- `stdOut`: the standard out from the process

![A text component displaying the results of `getUptime.data.stdOut`](https://d3399nw8s4ngfo.cloudfront.net/docs/rd/53dc785-Screen_Shot_2021-07-23_at_5.05.09_PM.png)

### Calling commands with dynamic arguments

In real applications, we need to trigger commands with dynamic arguments. The Shell Script resource can take arguments from a Retool application via the `{{ }}`. For example, if we had a dropdown with two different commands, we could run one of them by consuming `{{ dropdown1.value }}` as Shell Script arguments.

![Calling a command with dynamic arguments.](https://d3399nw8s4ngfo.cloudfront.net/docs/rd/1cdb3df-Screen_Shot_2021-07-23_at_5.11.18_PM.png)

---

## Troubleshoot resource connections

Retool can connect to many databases and APIs. Certain data sources may have specific setup requirements, such as allowed IPs or required keys. Where necessary, we document these requirements. Refer to the integration's documentation when configuring your resource and use the following information as you troubleshoot any connection issues. If you need to make changes with your data source, refer to their documentation for more information and guidance.

Some resources include testing options that you can use to troubleshoot connection issues. These options are displayed when you create or edit a resource, and include a [debugging console](../../apps/concepts/debug-tools.mdx#resource-configuration-page) that displays detailed error information.

## Allow Retool IP addresses to access your data source

Certain resources use an allowlist of IP addresses to prevent unauthorized connections. [Add Retool's IP addresses to your allowlist](../reference/ip-allowlist-cloud-orgs.mdx) if necessary.

Each data source can use a different method for allowing remote connections. Refer to the data source's documentation to learn how you add allow IP addresses.

:::info Connect without allowlist

Retool is building support for querying firewalled resources without allowlisting Retool’s IP address. To learn more or be considered for early access, contact cloud-connect@retool.com.
:::

## Verify your credentials or connection string is correct

For databases like [PostgreSQL](integrations/database/postgresql.mdx) and [MongoDB](integrations/database/mongodb.mdx), Retool allows you to connect using traditional credentials (username, database, password, port) and a _connection string_.

Verify that your credentials are correct and that you're referencing the correct database.

The final part of a connection string (`/mydb`) references the database name. Ensure that your connection string references the correct database. If you copy a connection string from a console (like MongoDB Atlas), this may default to another database name.

## Database or provider credentials

You must provide a database username and password when connecting using traditional credentials or with a connection string. These credentials are often not the same as those used to access your data source's web console.

Create a new database user specifically for connecting with Retool and use these credentials to create the resource.

## SSL and certificates

Certain integrations support SSL encryption, such as [MongoDB](https://docs.mongodb.com/manual/tutorial/configure-ssl/). This additional layer of security keeps your data safe and prevents threats like [man-in-the-middle](https://en.wikipedia.org/wiki/Man-in-the-middle_attack) (MITM) attacks.

If SSL is available for a resource, Retool displays **SSL** on the resource connection page.

If your database uses a self-signed certificate instead of a publicly signed certificate, you must configure Retool to trust the custom certificate. Check **Connect using SSL** and then check **Use a self-signed certificate**.

## Connect via SSH tunneling

If you cannot allow Retool's IP address or need to use data on a private network, you can [create an SSH tunnel](connections/ssh-tunnels.mdx). SSH tunneling is not supported by all integrations.

## Common error messages

Retool reports on any errors when connecting to a data source. The following errors occur if any provided information is invalid (e.g., username and password are incorrect) or if Retool is unable to connect to the data source (e.g., Retool IP addresses not added to an allowlist).

| Error                                     | Description                                                                                                                                                               |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getaddrinfo ENOTFOUND`                   | The hostname is not reachable. Verify the hostname details are correct, Retool is allowed to access it, or if it is behind a private network that requires SSH tunneling. |
| `password authentication failed for user` | The credentials are incorrect. Verify the credentials and try again.                                                                                                      |
| `database "" does not exist`              | The database does not exist. Verify the database details and try again.                                                                                                   |
| `connect ECONNREFUSED`                    | The port is incorrect or Retool is not allowed to access the data source.                                                                                                 |

---

## Manage embeddings in Retool-managed Vectors

You can use [Retool-managed Vectors](../../quickstarts/retool-vectors.mdx) to store plain text or extracted text from PDF documents, or text from publicly accessible web pages.

:::note

If your deployment is self-hosted, follow the [Enable Retool-managed Vectors on self-hosted deployments](../../../self-hosted/guides/vectors.mdx) guide before you get started.

:::

## Create a vector

Within the scope of Retool-managed Vectors, a vector is a collection of unstructured text (known as _embeddings_). You create a vector to define the overall relationship and then add text or URLs to it. For example, if you wanted to build an AI-powered chat tool and want it to use context from your support site, you would create a vector (such as **Documentation**) and add URLs from your documentation site.

To create a Vector:

1. Navigate to the Resources landing page and click **Retool Vectors**.
2. Click **Create new** and select **Vector** from the dropdown list.
3. Specify a **Vector name**.
4. The **Default embedding model** is ```text-embedding-ada-002```, but you can select the [OpenAI embedding model](https://platform.openai.com/docs/guides/embeddings#embedding-models) of your choice from the dropdown. 
5. Add **Filter labels** to filter vectors with Retool AI queries. Refer to [Use Retool AI to query vectors with filters and metadata](./filters.mdx) for more information.
    :::info
    To use filters and metadata in Retool AI queries, you must define them when creating a vector. If no filter labels are provided, all vectors are searched during a query.
    ::: 
6. Add metadata to the **Default metadata** field in key-value pairs. 
7. Choose whether the **Vector type** is a **Document** or a **Site URL**. 
    :::info Vector contents
    Each vector you create can contain either document text or URLs, not both.
    :::
8. Click **Create**.

export function ArcadeEmbed_createnew() {
  return (
    
      
    
  )
}

## Edit a vector

You can edit the **Vector name**, **Description**, **Filter labels**, and **Default metadata** of a Retool-managed Vector. 

:::note
You cannot change the embedding model of a vector once it has been created.
:::

Select the vector to edit, click `•••`, then select **Edit vector details**.

If necessary, click **Delete Vector** to remove it. All vector data will be removed and cannot be recovered—you would need to recreate the vector.

export function ArcadeEmbed_edit() {
  return (
    
      
    
  )
}

## Remove documents and URLs

Toggle the checkbox next to the document or URL in a vector to select it, then click **Delete**.

You can add documents or plain text to a vector manually or query the **Retool Vectors** resource in apps or workflows.

## List Vectors

You can query the **Retool Vectors** resource in apps or workflows to list all available Vectors. This enables you to build apps that allows users to select a Vector and perform further actions, such as adding documents or URLs to it.

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **List all Vectors**.

---

## Use Retool AI to query vectors with filters and metadata

You can use AI actions in Retool to reference the embeddings stored in Retool Vectors. Retool Vectors can be queried from [Retool Apps](../../../apps/index.mdx) or [Retool Workflows](../../../workflows/index.mdx) using [AI Actions](../../../workflows/guides/blocks/ai-action.mdx). 

* *Metadata* allows you to provide additional context about your data with a key-value pair and can help you organize and manage your vectors. 
* *Filter labels* help you select and retrieve the vectors that are relevant to a query. 

:::note
Before you can use Retool AI to query a vector with filters or metadata, they must first be added to a Retool Vector. See [Manage embeddings in Retool-managed Vectors](./embeddings.mdx) for more information.
:::

## Generate text with Retool AI

Use the **Generate text** AI action with the filter labels applied to your vectors to generate a text response based on specific embeddings. 

1. Open the **Code** panel.
2. Click the **+** sign and select **AI Action**, or add a **Resource query** and change the **Resource** field to **Retool AI**.  
3. Select **Generate text** as the **Action**. Refer to [Generate text](../../../queries/guides/ai/text.mdx#generate-text) for more information.
4. Toggle the checkbox on to **Use Retool Vectors to provide more context to your query**. 
5. Select the vector(s) you want to query in the **Select Vector** field. 
6. In the **Filters** field, select the vector document or URL that you want to use for your query. 
7. Add a prompt to the **Input** field.
8. Click **Save**. 
9. Click **Run** to display the generated text in the **Output** message. 

export function ArcadeEmbed_generate_text() {
  return (
    
      
    
  )
}

## Generate chat response with Retool AI

Use the **Generate chat response** AI action with the filter labels applied to your vectors to generate a chat response based on specific embeddings. 

1. Open the **Components** panel.
2. Search for the **LLM Chat** component and drag it to the canvas.
3. A chat query is automatically created with the **Generate chat response** AI action selected. Refer to [Retool AI chat actions](../../../queries/guides/ai/chat.mdx) for more information.
4. Toggle the checkbox on to **Use Retool Vectors to provide more context to your query**. 
5. Select the vector(s) you want to query in the **Select Vector** field. 
6. In the **Filters** field, select the vector document or URL that you want to use for your query. 
7. Click **Save**. 
8. Type a message in the chat component to generate a response.

export function ArcadeEmbed_chat() {
  return (
    
      
    
  )
}

---

## Store vector embeddings for AI actions



---

## Store documents and text in Retool-managed Vectors

You can use [Retool-managed Vectors](../../quickstarts/retool-vectors.mdx) to store and generate AI-related vector data for plain text or extracted text from PDF documents. Retool can then provide AI models with related information when performing [AI actions](../../../queries/concepts/actions.mdx).

## Add a document

:::info Workflows only accept plain text

You cannot use the **Convert document to text** AI action in a workflow. You need to extract the text first and make it available for the workflow to use.

:::

You can add documents or plain text to a vector manually or query the **Retool Vectors** resource in apps or workflows.

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

1. Navigate to the **Resources** page and select **Retool Vectors**.
2. Select the vector in which to add.
3. Click **Add document**, then select either **Upload file** or **Add plain text**.
4. **Filter labels** and **Metadata** are inherited from the parent vector.

:::tip Extract text from PDFs in apps

Use the [Convert document to text AI](../../../queries/guides/ai/document.mdx#convert-document-to-text) action in web or mobile apps to first extract text from a PDF document. You can then reference the extracted text using `{{ }}` notation, such as `{{ convertDocument.data }}`.

:::

1. Create an app or a workflow, open the **Code panel**, and click the plus sign **+** to add a new **Resource query**. 
2. Set the **Resource** to **Retool Vectors**.
2. Set **Vector action** to **Insert document**.
3. Select the **Vector** in which to store the document. 
4. Set **Document content** to the desired text.
5. **Filter labels** and **Metadata** are inherited from the parent vector.
6. Specify a name for the document in the **Document name** field.
7. **Save** and **Run** the query. 

export function ArcadeEmbed() {
  return (
    
      
    
  )
}

When run, the query adds a new document to the vector. If a document with the same name already exists, the query returns an error.

## Update or upsert a document

Use the **Update document** action to update an existing document. You can also use the **Upsert document** action to update an existing document or create one if it doesn't exist.

Combine this with the [List documents](#list-documents) action in apps to enable users to select from a list of documents in a vector.

From a **Resource query**: 

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **Update document** or **Upsert document**.
3. Set **Document content** to the desired text.
4. Make updates to **Filter labels** and **Metadata** as needed.
5. Specify a name for the document in the **Document name** field.

export function ArcadeEmbed_upsert() {
  return (
    
      
    
  )
}

When run, the query adds a new document to the vector. If a document with the same name already exists, the contents are updated.

## Delete an existing document

Use the **Delete an existing document** action to remove a specified document from a vector.

:::danger Destructive action

Any documents you delete from a Vector are unrecoverable. Enable **Show a confirmation modal before running** in the **Advanced** tab to display a confirmation message and prevent accidental deletion.

:::

From a **Resource query**: 

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **Delete document**.
3. Select the vector in the **Vector** field.
4. Specify the name of the document in the **Document name** field.

## List documents

Use the **List documents** action to retrieve a list of all documents in an existing vector.

From a **Resource query**: 

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **List document**.
3. Set **Document content** to the desired text.
4. Specify a name for the document in the **Document name** field.

## Get document chunks

Use the **Get document chunks** action to retrieve the text for a specified document. When run, the query returns a list of text strings.

From a **Resource query**: 

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **Get document chunks**.
3. Select the vector in the **Vector** field.
4. Specify the name of the document in the **Document name** field.

## Clear Vector documents

Use the **Clear Vector documents** action to delete all documents in the specified vector.

:::danger Destructive action

Any documents you delete from a Vector are unrecoverable. Enable **Show a confirmation modal before running** in the **Advanced** tab to display a confirmation message and prevent accidental deletion.

:::
From a **Resource query**: 

1. Set **Resource** to **Retool Vectors**.
2. Set **Vector action** to **Clear Vector documents**.
3. Select the vector in the **Vector** field.

---

## Store web page text in Retool-managed Vectors

You can use [Retool-managed Vectors](../../quickstarts/retool-vectors.mdx) to store and generate AI-related vector data for text from publicly accessible web pages. Retool then crawls the specified URLs and fetches the text content. Retool can then provide AI models with related information when performing AI actions.

:::note
URL crawling is not supported for [Self-hosted Retool](../../../self-hosted/index.mdx) instances.
:::

## Create URL Vector

You can create a URL Vector and add URLs for publicly accessible web pages manually or query the **Retool Vectors** resource in apps or workflows. You only need to specify a base URL, such as `https://docs.retool.com`—Retool crawls the URL and fetches text for any pages at this location.

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

1. Navigate to the **Resources** settings and click **Retool Vectors**.
2. Click **Create new**.
3. Select **Vector**.
4. Specify the **Vector name**, the **Default embedding model**, **Filter labels** and **Default metadata** in the appropriate fields.
5. Choose **Site URLs** for the **Vector type**.
6. Click **Create**.
7. Click **Add URLs**.
8. Specify the web pages in the **Links to crawl** field.
9. Add links to exclude from the vector in the **Link prefix to exclude** field as necessary. 
10. The **Filter labels** and **Default metadata** are prepopulated based on what you specified during vector creation in step 4. 
11. Click **Fetch**. 

Retool crawls the specified URLs and automatically fetches the text content and creates embeddings for each.

export function ArcadeEmbed_website() {
  return (
    
      
    
  )
}

1. Open the **Code** panel. 
2. Click the **+** sign to add a new **Resource query**. 
3. Set **Resource** to **Retool Vectors**.
4. Set **Vector action** to **Create URL Vector**.
5. Specify the **Vector name**, the **Default embedding model**, **Filter labels** and **Default metadata** in the appropriate fields.
6. Specify the URL in the **Links to crawl** field.
7. Click **Save**.
8. Click **Run**.

export function ArcadeEmbed_fromApp() {
  return (
    
      
    
  )
}

## Refresh a URL vector

If the content of crawled web pages has changed, use the **Refresh URL Vector** action to crawl the URLs again. Retool updates existing embeddings with any new content and calculates new vector data automatically.

1. Set **Vector action** to **Refresh URL Vector**.
2. Specify the vector to refresh in the **Vector** field.

## List all URLs in a vector

Use the **List URLs** action to retrieve a list of all crawled URLs within the specified vector.

1. Set **Vector action** to **List URLs**.
2. Specify the vector to refresh in the **Vector** field.

## Get URL chunks

:::tip Combine with the List URLs action

Use the **List URLs** action to get a list of URLs within a vector in a separate query. You can then reference a specific URL using `{{ }}` notation, such as `{{ listUrls.data[2] }}`.

:::

Use the **Get URL chunks** action to retrieve the chunked text for a specified URL in a vector.

1. Set **Vector action** to **Get URL chunks**.
2. Specify the vector to use in the **Vector** field.
3. Specify the URL for which to get chunks in the **url name** field.

---

## Resources how-to guides

import Howto from '/docs/_partials/_doctypes/_howto.mdx';

:::tip Get started

If you want to connect your data to Retool:

- Read the [quickstart](./quickstart) to learn about the fundamental concepts.
- Follow a [tutorial](./tutorial/) to connect your data sources or use Retool's built-in solutions.

:::

---

## Data sources documentation

You can connect almost any API or database to Retool and build software using your data. Retool includes a wide range of API and database integrations, such as Salesforce and PostgreSQL, and you can connect to any REST or GraphQL API.

Retool also offers a number of built-in solutions that you can use instead of, or alongside, other data sources.

Built-in [integrations](guides/integrations/index.mdx) enable you to connect almost any API and database with Retool.

[Retool Database](quickstarts/retool-database.mdx) is a managed PostgreSQL database with a spreadsheet-like interface to manage your data.

export function ArcadeIntro() {
  return (
    
      
    
  );
}

[Retool Email](quickstarts/retool-email.mdx) is a hosted email resource for cloud-hosted organizations to send emails without needing to configure an email provider.

[Retool Storage](quickstarts/retool-storage.mdx) is a Retool-hosted file store for cloud-hosted organizations. Using Retool Storage, you can upload and download files and use them in your apps and workflows.

Upload documents and URLs to use as text embeddings to inform AI models.

---

## Resources quickstart

This guide serves as an introduction to resources, data sources, and integrations. It covers many of the concepts and terminology you can expect to use as you connect data sources to use with apps and workflows. After reading this page, you should have a good understanding of the fundamentals for connecting APIs and databases.

## Introduction

You can connect almost any [data source](#data-sources) and make it available for use in your Retool organization as a [resource](#resources). Retool includes a wide range of [integrations](#integrations) and [authentication methods](#authentication-methods) so you can connect to almost any database or API.

Retool also offers a range of [built-in solutions](#built-in-solutions) that you can use instead of external data sources.

## Data sources

A data source is somewhere you store and perform operations with data. This could be a [PostgreSQL database](https://www.postgresql.org/), the [Twilio REST API](https://www.twilio.com/docs/usage/api), an [Amazon S3 bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/UsingBucket.html), etc. You can add as many data sources as you need to Retool and make them available for users to query.

## Resources 

A [resource](resources.mdx) is a saved set of user-configured properties that determine how Retool interacts with a data source. You create a resource for each data source you want to use with Retool. You can then select the resource when writing a query so you can interact with the data.

Each resource has its own configuration options that Retool uses when interacting with a data source. This configuration can include:

- Authentication credentials and flow (username and password, API key, OAuth, etc.)
- Database connection settings (host, port, database name, etc.)
- API settings (base URL, default headers, cookies, etc.)

### Retool access to resources

import Allow from '../reference/ip-allowlist-cloud-orgs.mdx';

### Lifecycle

import Lifecycle from '../../_partials/_resource-lifecycle.mdx';

### Authentication methods

Retool supports wide range of [authentication methods](../guides/authentication/api.mdx), including:

- API keys and tokens
- Auth0
- AWS IAM
- Basic HTTP authentication
- Bearer authentication
- Digest authentication
- Google service account
- Oauth 1.0
- Oauth 2.0
- OAuth 2.0 custom applications
- Session-based

You can also [configure custom authentication](../guides/authentication/custom.mdx) to perform complex or bespoke resource authorization that require multiple steps.

## Integrations

_Integrations_ are the available data source types for which you can create a resource. Retool includes [built-in integrations](https://retool.com/integrations/) for many popular data sources that require minimal configuration, such as [SQL databases](../guides/integrations/index.mdx), [Twilio](https://retool.com/integrations/twilio), and [Stripe](https://retool.com/integrations/stripe). 

If Retool doesn't have a built-in integration for a particular type of data source, you can connect to almost any API using [REST](../guides/integrations/api/rest.mdx), [GraphQL](../guides/integrations/api/graphql.mdx), or [SOAP](../guides/integrations/api/soap.mdx) integrations.

## Built-in solutions

Retool has a number of built-in resources with which you can store and use data.

### Retool Database

[Retool Database](./retool-database.mdx) is a fast, secure solution for saving and editing data to use in Retool apps. It combines a PostgreSQL database with a spreadsheet-like interface to manage your data. On Retool Cloud, the underlying database is managed by Retool. On [Self-hosted deployments](../../self-hosted/guides/retool-database.mdx), you host your own PostgreSQL database.

### Retool Email

[Retool Email](./retool-email.mdx) is a hosted email resource for cloud-hosted organizations to send emails without needing to configure an email provider. You can build apps and workflows that send emails using the **Retool Email** resource. 

### Retool RPC

[Retool RPC](./retool-rpc.mdx) (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.

### Retool Storage

[Retool Storage](./retool-storage.mdx) is a Retool-hosted file store for cloud-hosted organizations. Using Retool Storage, you can upload and download files and use them in your apps and workflows. Retool Storage includes up to 5 GB of storage per organization. Files can be up to 40 MB each, although your browser may have settings that restrict this limit further.

Some file input components, such as [Image](https://retool.com/components/image) and [PDF](https://retool.com/components/pdf), have built-in support for files on Retool Storage; automatically uploading files without the need for separate queries.

### Retool Vectors

[Retool-managed Vectors](./retool-vectors.mdx) is a hosted vector database that enables you to store unstructured text from documents and web pages for use with AI models through Retool. Retool abstracts away the complexities of preparing text and automatically generates the required data for AI models to make decisions using your data.

## Helper resources

_Helper resources_ don't interact with data sources. Instead, they provide you with additional functionality to transform or manipulate data. These resources include:

| Resource                                                                | Description                                                       |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
| [Query JSON with SQL](../../queries/guides/sql/query-json.mdx)               | Write SQL statements to query JSON data.                          |
| [PDF Exporter](../../queries/guides/generate-pdfs.mdx)     | Export data as a PDF file.                                        |
| [ParentWindow](../../apps/guides/app-management/embed-apps.mdx)                 | Receive data from the parent page when using an embedded web app. |
| [Run JS Code](../../queries/guides/javascript/index.mdx)     | Write JavaScript code to transform data or control app behavior.  |
| [Mobile Push Notifications](../../mobile/guides/app-management/push-notifications.mdx) | Send push notifications to Retool Mobile app users.               |
| [Retool Workflow](../../queries/guides/workflows.mdx)               | Run a workflow using provided data and receive the output.        |
| User Action                                                             | Perform actions for external users.                               |
| [Import from Query Library](../../queries/guides/query-library.mdx) | Import a query from the shared Query Library.                     |

---

## Retool Database quickstart

This guide serves as an introduction to Retool Database. It covers many of the concepts and terminology you would come across when working with data in Retool Database. After reading this page, you should have a good understanding of the fundamentals for Retool Database.

## Introduction

Retool Database is a fast, secure solution for saving and editing data to use in Retool apps. It combines a PostgreSQL database with a spreadsheet-like interface to manage your data. On Retool Cloud, the underlying database is managed by Retool. On [Self-hosted deployments](../../self-hosted/guides/retool-database.mdx), you host your own PostgreSQL database.

export function ArcadeIntro() {
  return (
    
      
    
  )
}

## Features

With Retool Database, you can:

- [Store tables of data](../guides/retool-database/manage-fields.mdx) in a securely hosted PostgreSQL database that's only available as a resource within your Retool organization.
- [Visually interact with data](../guides/retool-database/manage-data.mdx) using a spreadsheet-like interface to edit, search, filter, and sort records.
- Import or [export](../guides/retool-database/export-data.mdx) data in CSV format.
- [Build apps and write queries](../quickstarts/resources.mdx) to interact with Retool Database like any other resource.
- Make use of [multiple environments](../guides/retool-database/multiple-environments.mdx), such as staging and production.
- [Configure resource permissions](../../permissions/guides.mdx) to control access to Retool Database within your organization.
- [Capture form submissions](../../forms/index.mdx) for forms created in Retool.

Retool Database is available to all cloud-hosted organizations. Self-hosted organizations can follow the [configuration guide](../../self-hosted/guides/retool-database.mdx) to configure Retool Database, backed by your own PostgreSQL database. Once configured, the Retool Database editor is available to use.

Retool Database for cloud-hosted organizations are connected to the internet and can be accessed using the provided [connection string](../guides/retool-database/external-access.mdx#connection-strings). Retool's [security guide](https://docs.retool.com/page/security) provides detailed information about data storage and security for provisioned databases hosted by Retool. Within your Retool organization, you can control who has access by configuring [user permissions](../../permissions/guides.mdx).

:::info
Retool Database is designed to be a convenient way to store data to use within or outside of Retool. It is not designed to be a highly-available, scalable database service, and you should use a separate managed database provider if your use case requires these guarantees.
:::

## Usage and limits 

Cloud-hosted organizations can store the equivalent of 5GB of PostgreSQL data, with unlimited tables and rows. The amount of storage space your data uses is dependent on how many records, fields, and tables you use, and the size of values. Retool customers on a Business or an Enterprise plan that exceed their storage limits can reach out to Retool to request a limit increase. Retool customers on the Free plan would need to upgrade to a Business or an Enterprise plan prior to requesting a storage limit increase.  

## Data redundancy

Retool Database uses multiple levels of redundancy, which include daily backups of all data in a PostgreSQL cluster managed by our cloud provider. Retool retains each of these backups for 7 days. Retool recommends implementing a secondary backup process that stores and retains data for a longer period of time as an additional guardrail.

If you have any questions or would like to know more, [contact Retool Support](/support).

## Staging data

Any changes you make with data in Retool Database cannot be reverted. Retool recommends using [multiple environments](../../org-users/guides/configuration/environments.mdx) with staging data to avoid accidental loss of data.

---

## Retool Email quickstart

Retool Email is a hosted email resource for cloud-hosted organizations to send emails without needing to configure an email provider.

## Features

With Retool Email, you can:

- Send emails from apps and workflows using queries.
- Write messages using plain text, HTML, or Markdown.
- Include attachments with sent messages.
- Set a **Reply-To** address and add **CC/Bcc** recipients.
  
## Availability and limits

Cloud-hosted organizations on paid plans can send up to 120 emails per hour. Organizations on the **Free** plan can send up to 50 emails per day.

## Customization

Retool does not allow users to modify the sender email address. However, you can set a **Reply-To** address so that replies are sent to the email of the your choice. 

Retool sends emails from one of the following addresses:

- `mail@.retool-email.com` when a **Reply-To** address is set. 
- `noreply@.retool-email.com` when no **Reply-To** address is set.

:::note

Messages from Retool Email always include a `Sent via Retool Email (https://retool.com)` line at the bottom. If it is critical to remove this line of branding, Retool recommends using an [SMTP server](../guides/integrations/messaging/smtp.mdx).

:::

---

## Retool RPC quickstart

Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.

## Features

With Retool RPC, you can:

- [Register functions from your codebase](../tutorials/retool-rpc.mdx#2-define-server-side-functions) and use them in Retool apps.
- [Configure function permissions](../tutorials/retool-rpc.mdx#4-configure-function-permissions) to control access to exposed functions within your organization.
- [Use schema versioning](../tutorials/retool-rpc.mdx#5-schema-versioning) to ensure your exposed functions are always up-to-date.
- [Ensure customer safety](#architecture-and-security) with its outbound-only architecture.

## Architecture and security

Retool RPC is an _outbound-only_ architecture, which means the registered server only makes outbound requests to Retool and never receives inbound requests.

On every start up, the RPC server registers itself and the functions it exposes to Retool. After that completes, the RPC server continuously polls for new requests from Retool in the following flow:

Retool stores query requests and responses in a messaging queue. The direction of the arrows represents the direction of the request. 

- The blue arrows represent _Pop Query_ requests, which poll for _Run Query_ requests.
- The black arrows are _Run Query_ requests, which are made by calling functions in the Retool UI. 

When a _Pop Query_ request detects a _Run Query_ request, it interacts with your codebase and then initiates the red flow. This sends a _Post Query Response_ to respond to the original _Run Query_ request.

Only making outbound requests ensures your codebase is never exposed to the internet, and that your data is secure.

Other security measures include:

- Retool requires a valid access token and resource access for all RPC-related requests.
- Each resource is given a different queue to ensure isolation between resources.

---

## Retool Storage quickstart

Retool Storage is a Retool-hosted file store for cloud-hosted organizations. Using Retool Storage, you can upload and download files and use them in your apps and workflows.

:::note

If you use a [Self-hosted Retool deployment](../../self-hosted/guides/retool-storage.mdx), you can use your own storage provider and access your files through the [Retool Storage interface](#managing-files-and-folders).

:::

## Features

With Retool Storage, you can:

- Store up to 5GB of files for use in apps and workflows.
- Easily upload user files with file input components.
- Enable public access to files for use over the internet.
- Upload, download, and manage files using either queries or the Retool Storage interface.

## Identify files

Retool Files are uniquely identified by their URL. URLs let users download files (your Retool app users for private files, anyone on the internet for public files). URLs use the following format: `{your-domain}/api/file/{file-uuid}`.

:::tip
Retool recommends using file URLs to refer to Retool Files from other data resources, like databases.
:::

Using the file's URL, you can download, modify, and otherwise interact with the file.

## Manage files and folders

You can use the Retool Storage interface to manage your files and folders. To access the Retool Storage interface, sign in to your Retool organization, select the **Resources** tab, and click **Retool Storage**.

Within this interface, you can:

- Upload, download, rename, move, delete, and set public access on files.
- Create, rename, and delete file folders.
- Search for files and folders.
- Monitor your storage usage.

## Restrict file access

You can optionally restrict access to files on Retool Storage.

---

## Retool-managed Vectors

This guide serves as an introduction to [Retool Vectors](https://retool.com/products/ai). It covers many of the concepts and terminology you would come across when storing and using vector data. After reading this page, you should have a good understanding of the fundamentals for Retool Vectors.
:::note[Set up Retool AI]
You must set up Retool AI before you can use Retool Vectors. Follow the setup instructions in [Retool AI](../../self-hosted/concepts/retool-ai.mdx#ai-actions).
:::
## Introduction

Retool Vectors enables you to use a vector database to store unstructured text from documents and web pages for use with Retool AI. You can use either:

- [Retool-managed Vectors](#retool-managed-vectors).
- A supported third-party vector store, such as [Amazon Knowledge Bases](#amazon-knowledge-bases).

## AI embeddings and vectors

AI models use embeddings to determine the meaning and connection between objects, such as blocks (chunks) of text. An embedding is a type of vector, a mathematical representation of an object. The more closely related text chunks are, the smaller the difference in their calculated vectors. For example, the vector difference between "water" and "wet" would be smaller than the difference between "water" and "banana".

For use cases that involve similarity search with large datasets, such as an AI-powered chat tool that relies on content from support articles, embedding vectors must be first calculated. This vector data is then provided to the AI model so it can make informed decisions. These vector calculations should be saved in a _vector database_ to allow for efficient storage and retrieval of large datasets of embeddings.

When you reference a Vector in an AI action, Retool includes the most relevant content in the AI model request. When run, Retool automatically:

1. Calculates the vector for the AI action's input.
2. Identifies which embeddings in the chosen vector closely relate to the input.
3. Appends the text from the embeddings when making the request to the AI model.

These steps are performed in the back-end and not visible to users, further reducing complexity.

### Vector organization

You can think of Vectors as file directories, and embeddings as the files they contain. Each Vector should contain relevant information that you consider related. For example, if you wanted to build an AI-powered chat tool that can respond using information from support articles, you would create (such as **Documentation**) and add URLs from your support site.

### Use Vectors in AI actions

You reference embeddings from Retool Vectors in AI actions. Retool includes the most relevant content in the AI model request, based on the input. When run, Retool automatically:

1. Calculates the vector for the AI action's input.
2. Identifies which embeddings in the chosen vector closely relate to the input.
3. Appends the text from the embeddings when making the request to the AI model.

These steps are performed in the back-end and not visible to users, further reducing complexity.

## Retool-managed Vectors

Retool-managed Vectors abstracts away the complexities of preparing text and automatically generates the required data for AI models to make decisions using your data. You create a _vector_ in which to store _embeddings_—unstructured text about a particular topic.

Retool automatically generates embeddings, splitting unstructured text into chunks where needed. If you add URLs to a Vector, Retool crawls matching web pages, fetching and storing the text.

:::info OpenAI embeddings

Retool uses the OpenAI [embeddings API](https://platform.openai.com/docs/api-reference/embeddings) to calculate vectors for text chunks.

:::

You can manually add text to a Vector or write queries that interact with Retool-managed Vectors. Once added, you can manage the embeddings and view the associated text or URL.

### Text embeddings

When you add text to Retool-managed vector, Retool automatically performs the following:

1. If a document is provided, Retool extracts the text.
2. Splits the text into chunks.
3. Calculates the vector for each chunk.
4. Stores this information in the vector.

### URL embeddings

When you add a URL to a Retool-managed vector, Retool automatically performs the following:

1. Crawls the URL for any pages that match. For example, specifying `https://docs.retool.com` would include `https://docs.retool.com/ai` but not `https://retool.com`.
2. Fetches the text for each page and creates a new embedding in the vector.
3. Splits the text into chunks.
4. Calculates the vector for each chunk.
5. Stores this information in the vector.

Retool can only fetch text from web pages that are publicly available and directly linked from other pages. Pages that are not accessible (e.g., requires authentication or behind a firewall) or that have no inbound links (e.g., pages only accessible with a direct URL) cannot be crawled.

You can also exclude certain URLs whose domain and path match. For example, `https://docs.retool.com/changelog` would prevent any pages that contain this URL from being crawled.

## Amazon Knowledge Bases

Retool supports [Amazon Knowledge Bases](https://docs.aws.amazon.com/bedrock/latest/userguide/kb-how-it-works.html) vector stores. You can [connect a knowledge base](retool-vectors.mdx) to use for vector embeddings in AI actions. Once configured, Retool communicates directly with the knowledge base to provide context for AI actions.

## Limitations

* Retool currently supports OpenAI for Vectors.
* The following limits apply when crawling a website:
    * A maximum of three web crawl requests can run concurrently.
    * Web crawls are limited to 25 URLs.
    * Web crawls time out after 15 seconds.
    * A maximum of two web crawls can occur during each five-second interval.

---

## Resources quickstarts

import Quickstarts from '/docs/_partials/_doctypes/_quickstart.mdx';

---

## Resources environment variables

import Resources from "@site/docs/self-hosted/reference/environment-variables/resources.mdx";

---

## Data sources glossary

import SharedGlossary from '../../_partials/_glossary.mdx';

---

## Retool Cloud IP addresses

Retool Cloud organizations must ensure that any configured resources, such as APIs and databases, allow access from Retool's IP addresses. If you make use of inbound firewall rules, include the following IP addresses in its allowlist. Refer to your data source or firewall documentation for specific guidance.

:::info Connect without allowlist

Retool is gathering interest in a feature that would enable querying firewalled resources without allowlisting Retool’s IP address. To learn more or be considered for early access, contact cloud-connect@retool.com.
::: 

By default, Retool uses the AWS `us-west-2` region, based in Oregon, US. To route resources through Europe or other regions, see the [outbound regions documentation](../guides/connections/outbound-retool-regions.mdx).

import RetoolIps from '../../_partials/_retool-ips.mdx'

If you use Retool Self-hosted, refer to the [self-hosted network and storage requirements](../../self-hosted/reference/requirements.mdx) for additional details.

---

## The Retool Storage File object

## Properties

---

## Resources reference

import Reference from '/docs/_partials/_doctypes/_reference.mdx';

:::tip Get started with web apps

If you are unfamiliar with Retool mobile apps and want to get started: 

- Read the [quickstart](./quickstart) to learn about the fundamental concepts.
- Follow a [tutorial](./tutorial/) to build your first mobile app.

:::

---

## Create a resource tutorial

A resource is a set of user-configured properties that determine how Retool interacts with a data source, such as an API or database. You create a resource for each data source you want to use with Retool. You can then select the resource when writing a [query](../../queries/index.mdx) so you can interact with the data.

Retool provides a number of [pre-built integrations](../guides/integrations/index.mdx) that enable you to connect third-party providers with Retool as resources. If there isn't a built-in integration for your desired data source, you can also connect any [REST API](../guides/integrations/api/rest.mdx) or [GraphQL API](../guides/integrations/api/rest.mdx)

In this tutorial, learn how to create a new resource that connects a REST API.

## Generate a mock API with customer data

## Create a new resource

The easiest way to create a new resource is from the Resources page. On this page, complete the following steps to create a new REST API resource:

1. Click **Create new**, and select **Resource** from the dropdown menu.
2. Select the **REST API** resource type from the list of resources.
3. Name the resource and paste the base URL you retrieved in the previous step. 
4. Click **Create resource** to finalize the creation of your resource. A confirmation message appears and prompts you to return to the **Resources** page or create an app.

export function CreateResource() {
  return (
    
      
    
  )
}

## Use the new resource

You can use your newly-created resource in web apps, mobile apps, and workflows. Refer to the following guides for more information about querying resources.

---

## Retool Database tutorial

[Retool Database](https://retool.com/products/database) is a fast, secure solution for saving and editing data to use in Retool apps. It combines a PostgreSQL database with a spreadsheet-like interface to manage your data. On Retool Cloud, the underlying database is managed by Retool. On [Self-hosted deployments](../../self-hosted/guides/retool-database.mdx), you host your own PostgreSQL database.

## 1. Create a table

You can visually interact with your database much like a spreadsheet. Log in to Retool and select the **Database** tab to access the Retool Database editor.

Databases organize data into _tables_ that can have different schema (e.g., separate tables for product and customer data). The sidebar contains a list of tables in Retool Database. When you open a table, it appears as a tab at the top of the editor for quick access.

Retool Database prompts you to create a new table automatically if one doesn't already exist. You can create an empty table, import existing data in CSV format, or generate a table schema with AI.

export function ArcadeCreateTable() {
  return (
    
      
    
  )
}

## 2. Set the primary key for the table

A _primary key_ is a field that uniquely identifies each table row (record). Retool automatically includes an `id` field for the primary key when you create a new table as it's the default option during a CSV import.

:::info

Tables without a primary key are read-only and you cannot make changes to data unless there is a primary key set.

:::

You can set or change a table's primary key at any time. Right-click a table tab and select **Edit Primary Key**, then select a field in the **New Primary Key** dropdown menu.

export function ArcadeEditKey() {
  return (
    
      
    
  )
}

If your data doesn't contain a single field that can uniquely identify rows, you can use a _composite key_. When enabled, you can select multiple fields and use their combined values as a primary key.

## 3. Add a row

Click **Add row** to add a new row of data to the table. To quickly edit existing table data, double-click on a cell and update its value, then click **Save**. You can also interact with certain fields using checkboxes or select options.

export function ArcadeNewRow() {
  return (
    
      
    
  )
}

4. ## Query your data

:::info Rate limit for cloud-hosted organizations

There is a limit of 1,000 queries per minute for Retool Database that applies across the whole organization.

:::

You [write queries](../../queries/quickstart.mdx#resource-queries) to interact with Retool Database data in the same way as any other SQL database resource connected to Retool.

Select the **Retool Database** resource in the query editor, then specify **SQL mode** to write raw SQL queries, or **GUI mode** to construct queries with an interface. As with other SQL databases, you can explore tables in the database.

You can switch between multiple environments from your apps which automatically refreshes any queries you've written. Provided you use the same table names, your app automatically reloads data from the selected environment.

---

## Retool RPC tutorial

:::info

Retool currently supports [JavaScript](https://github.com/tryretool/retoolrpc/blob/main/javascript/README.md) and [Python](https://github.com/tryretool/retoolrpc/blob/main/python/README.md) SDKs.

Reach out to your Retool account manager to access Retool RPC on self-hosted Retool 3.38 Edge versions and earlier.

:::

Retool RPC (Remote Procedure Call) is a fast, secure solution for connecting your own codebase to Retool. You define functions in your backend and then call them from Retool apps using a Retool RPC resource.

## Prerequisites

The prerequisites for Retool RPC depend on whether your organization is cloud-hosted or uses a self-hosted deployment.

You must set up a Redis server and connect it to your self-hosted instance before you can set up Retool RPC. The Redis server functions as the messaging queue for handling requests and responses between the instance and agent. 

Redis server requirements

Your Redis server must:

- Be accessible by hostname and password. 
- Have at least 10GiB memory.
- Be reachable from your Retool instance.

Run `redis-cli` on your Retool instance to verify it can connect to the Redis server. 

Configure eviction policy

Use `redis-cli` and the following command to set the eviction policy to `noeviction`.

```shell
CONFIG SET maxmemory-policy noeviction
```

Retool automatically clears data after a short period of time. 

Configure environment variables

:::note Restart your instance after changing environment variables

You must restart your Retool instance whenever you modify environment variables. 

:::

Edit `docker.env` on your Retool instance and update the following environment variables so it can connect to the Redis server.

| Variable                    | Description                                                           |
| --------------------------- | --------------------------------------------------------------------- |
| `RETOOL_RPC_REDIS_HOST`     | The Redis server hostname or IP address (e.g., `retool.example.com`). |
| `RETOOL_RPC_REDIS_PORT`     | The Redis server port (e.g., `6379`).                                 |
| `RETOOL_RPC_REDIS_PASSWORD` | The password with which to authenticate.                              |
| `RETOOL_RPC_REDIS_DB`       | The database number (e.g., `0`).                                      |
| `RETOOL_RPC_REDIS_TLS`      | Whether TLS should be used (e.g., `false`).                           |

To start using Retool RPC, you need to:

1. Create an RPC resource on Retool so Retool apps can communicate with your server.
2. Generate an access token to authorize your server so it can communicate with Retool.
3. Register a server with Retool's SDK to expose server-side functions to Retool and to handle function calls.

## 1. Set up Retool RPC

You can register a server with the [Retool CLI](#set-up-retool-rpc-with-retool-cli) or [set it up yourself](#set-up-retool-rpc-in-an-existing-project) with an existing project and the Retool SDK. The CLI option is recommended for initial testing.

:::info
[Node.js](https://nodejs.org/en/download) is required to use the CLI.
:::

The CLI is the easiest way to get started with Retool RPC. It automatically generates a resource and RPC server for you. You can use it to quickly test out Retool RPC and then migrate to a more permanent solution.

To setup Retool RPC with the CLI, run the following commands in your terminal.

```bash