PostgresSQL

PostgresSQL is a component that lets you read from, write to, and explore your PostgreSQL databases directly from the Nappai dashboard. It can add new data, run custom SQL queries, retrieve data using vector similarity, or fetch information about your database tables.

How it Works

When you drop the PostgresSQL component into a workflow, it connects to the PostgreSQL server you selected in the Credential field.

• Add: Inserts rows into a table and can also create the table if it doesn’t exist.
• SQL: Executes any SQL statement you write and returns the result set.
• Retriever: Builds a vector‑based retriever that can find similar rows based on an embedding.
• DatabaseInfo: Returns metadata about a table (columns, types, etc.).

All operations run inside Nappai, so you don’t need to write code—just fill in the fields and connect the component to the rest of your workflow.

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 rows into a table, optionally creating the table first.
• SQL: Execute a custom SQL query and return the results.
• Retriever: Build a retriever that can find similar rows using vector embeddings.
• DatabaseInfo: Retrieve metadata about a specific table.

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

Inputs

Credential
This component requires a Postgres SQL credential.

1. Configure the credential in the Credentials section of Nappai.
2. Select that credential in the Credential field of the component.
   The credential must contain a PostgresSQL Server Connection URL.

Input Fields

The following fields are available to configure this component. Each field may be visible in different operations:

• Embedding: Embedding to generate vector from text or to use similarity search.

  • Visible in: Add

• Ingest Data: Insert data into the database table.

  • Visible in: Add

• Operation: Choose which operation to run.

  • Visible in: Add, SQL, Retriever, DatabaseInfo

• Number of Results: Number of results to return.

  • Visible in: Add, SQL, Retriever, DatabaseInfo

• 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, DatabaseInfo

• Table Name: Name of the table in the database.

  • Visible in: Add, DatabaseInfo

• Drop Table: Drop the table if it exists before inserting data.

  • Visible in: Add, DatabaseInfo

Outputs

• Data: The result set from a SQL query or the data that was inserted.
• Retriever: A PostgresRetriever object that can be used to perform similarity searches.
• Database Info: Metadata about the specified table (columns, types, etc.).

Usage Example

Example 1 – Adding Data

1. Drag the PostgresSQL component into your workflow.
2. Set Operation to Add.
3. Enter the Table Name (e.g., customers).
4. Check Drop Table if you want to start fresh.
5. Provide the Ingest Data in JSON or CSV format.
6. Connect the Data output to the next component (e.g., a logger or a downstream processor).

Example 2 – Running a Custom Query

1. Drag the PostgresSQL component into your workflow.
2. Set Operation to SQL.
3. Enter a SQL statement in Search Query (e.g., SELECT * FROM orders WHERE amount > 100).
4. Set Number of Results to limit the rows returned.
5. Connect the Data output to a visualization component to display the results.

Related Components

• PostgresRetriever – Use the retriever output from PostgresSQL to perform vector similarity searches.
• DataTable – Display tabular data returned by PostgresSQL.
• DataFilter – Filter the Data output before passing it to other components.

Tips and Best Practices

• Keep your Search Query short and test it in a database client first to avoid errors.
• Use Number of Results to limit large result sets and improve performance.
• When using Add, enable Drop Table only if you’re sure you want to delete existing data.
• Store sensitive connection details in the credential and never hard‑code them in the workflow.

Security Considerations

• The component uses a Postgres SQL credential that contains the server connection URL.
• Ensure that the credential is stored securely in Nappai’s credential manager.
• Do not expose the credential or connection URL in logs or shared workflows.