SupabaseSQL

SupabaseSQL is a tool in the Nappai dashboard that lets you interact with a Supabase PostgreSQL database.
You can add new rows, run custom SQL commands, or create a retriever that searches the database using vector embeddings. The component handles all the connection details for you, so you only need to provide the query or data you want to work with.

How it Works

SupabaseSQL connects to your Supabase database through the Supabase API.
When you choose an operation, the component builds the appropriate SQL command and sends it to the database.

• For Add, it creates an INSERT statement and optionally drops the table first.
• For SQL, it runs whatever query you paste into the Search Query field.
• For Retriever, it builds a vector‑based search retriever that can be used later in the workflow.

The component returns the results as JSON rows for SELECT queries, or a status object for other commands. If an error occurs, it is caught and returned in a friendly format so you can see what went wrong.

Operations

This component offers several operations that you can select based on what you need to do. You can only use one operation at a time:

• Add: Insert new data into a specified table, optionally dropping the table first.
• SQL: Execute any custom SQL query and return the results.
• Retriever: Build a retriever that can perform similarity searches on the database.

To use the component, first select the operation you need in the “Operation” field.

Inputs

• Embedding: Embedding to generate vector from text or to use similarity search.
  • Visible in: Add, SQL, Retriever
• Ingest Data: Insert data into the database table.
  • Visible in: Add
• Operation: Choose which operation to run.
  • Visible in: Add, SQL, Retriever
• Number of Results: Number of results to return.
  • Visible in: Add, SQL, Retriever
• Search Query: SQL query to execute.
  • Visible in: SQL
• Search Score Threshold: If value is distinct to 0.0, it will filter the results with distance score lower than the threshold.
  • Visible in: Add, SQL, Retriever
• Table Name: Name of the table in the database.
  • Visible in: Add
• Drop Table: Drop the table if it exists before inserting data.
  • Visible in: Add

Credential
This component requires a Supabase API credential.

1. First, configure the credential in the Nappai credentials section.
2. Then select that credential in the component’s “Credential” field.
   The credential must contain a Supabase URL and a Supabase Service Key.

Outputs

• Data: Returns the query results as JSON rows or a status object for non‑SELECT commands.
• Retriever: Provides a retriever object that can be used for similarity searches later in the workflow.
• Database Info: Gives information about the connected database.

Usage Example

Example 1 – Adding Data

1. Set Operation to Add.
2. Enter the Table Name (e.g., customers).
3. Toggle Drop Table if you want to start fresh.
4. Paste your data into Ingest Data (JSON format).
5. Click Run.
   The component will create the table (if needed), insert the rows, and output a status in Data.

Example 2 – Running a Custom Query

1. Set Operation to SQL.
2. Paste a SELECT statement into Search Query (e.g., SELECT * FROM customers LIMIT 10;).
3. Optionally set Number of Results.
4. Click Run.
   The results appear in Data as a list of JSON objects.

Example 3 – Building a Retriever

1. Set Operation to Retriever.
2. Provide an Embedding model.
3. Set Number of Results and Search Score Threshold if needed.
4. Click Run.
   The component outputs a retriever that can be connected to other components for similarity search.

Related Components

• SupabaseBaseComponent – The base component that handles the connection to Supabase.
• VectorStore – Stores embeddings for fast similarity search.
• SQLQueryBuilder – Helps construct complex SQL queries visually.

Tips and Best Practices

• Keep your Search Query simple and test it in a database client first to avoid syntax errors.
• Use Drop Table only when you’re sure you want to delete existing data.
• For large data imports, split the data into smaller batches to avoid timeouts.
• Store sensitive credentials in the Nappai credentials manager; never hard‑code them in the workflow.

Security Considerations

• The component uses the Supabase API key, so ensure the key is stored securely in Nappai’s credential store.
• Limit the permissions of the Supabase service key to only the database actions you need (e.g., read/write on specific tables).
• Review the output of the Data field to avoid exposing sensitive information in downstream components.