PostgreSQL Visual Query Builder

Builds and executes PostgreSQL SELECT queries using a visual, parameter-driven configuration. Supports JOINs (INNER, LEFT, RIGHT, FULL, CROSS), WHERE/HAVING, GROUP BY, ORDER BY, LIMIT/OFFSET, and multiple output formats. Ideal for constructing complex queries without writing raw SQL.

Usage

Use this node when you want to query a PostgreSQL database by configuring tables, joins, and filters through parameters. Provide a PostgreSQL connection URI, specify the main table and schema, define columns to select, and optionally add joins and conditions. Choose the desired output format: plain text (with JSON), HTML table, XLSX, PDF, or all formats at once.

Inputs

Field	Required	Type	Description	Example
credentials_path	True	STRING	Database URI containing connection details for PostgreSQL.	postgresql://:@:5432/?ssl_mode=prefer
timeout	True	INT	Request timeout in seconds for the database service call.	60
main_table	True	STRING	Name of the main table to query.	users
main_table_schema	True	STRING	Schema name of the main table.	public
selected_columns	True	STRING	Comma-separated list of columns to select, or * for all columns.	users.id, users.name, orders.total_amount
join_config	False	STRING	JSON array describing JOINs. Each item must include type, table, and on; schema is optional (defaults to public).	[{"type": "INNER", "table": "orders", "schema": "public", "on": "users.id = orders.user_id"}]
where_conditions	False	STRING	SQL WHERE clause conditions to filter rows.	users.age > 25 AND users.city = 'New York'
group_by_columns	False	STRING	Comma-separated list of columns for GROUP BY.	users.city, users.age
having_conditions	False	STRING	SQL HAVING clause applied after GROUP BY.	COUNT(users.id) > 5
order_by_columns	False	STRING	Comma-separated list of columns to order by. Append DESC for descending.	users.created_at DESC, users.id
limit_count	False	INT	Maximum number of rows to return. Must be >= 1 to apply.	100
offset_count	False	INT	Number of rows to skip before starting to return rows.	0
output_format	True	["text", "html", "xlsx", "pdf", "all"]	Output format for results. 'text' returns formatted text plus JSON; 'html' returns an HTML table; 'xlsx' returns an Excel file (base64); 'pdf' returns a PDF (base64); 'all' returns all formats.	all

Outputs

Field	Type	Description	Example
result	STRING	Human-readable, formatted text summary of the query results.	Visual Query Results (10 rows): ...
json_result	STRING	Raw query results serialized as JSON string.	{"data": [{"id": 1, "name": "Alice"}], "row_count": 10}
html_table	STRING	HTML string representing the result set as a table. Empty if not requested.	......
xlsx_data	STRING	Base64-encoded XLSX content of the results. Empty if not requested.
pdf_data	STRING	Base64-encoded PDF content of the results. Empty if not requested.

Important Notes

• Join configuration must be valid JSON and structured as a list of objects with keys: type, table, on; schema is optional and defaults to public.
• Valid JOIN types are: INNER, LEFT, RIGHT, FULL, CROSS. CROSS JOIN does not use an ON condition.
• selected_columns accepts '*' or a comma-separated list; qualify columns with table names to avoid ambiguity (e.g., users.id).
• where_conditions and having_conditions are inserted into the SQL as provided; ensure they are syntactically valid and safe.
• limit_count and offset_count are applied only if greater than zero.
• When output_format is 'all', all output fields are populated; for other formats, only json_result plus the requested format output are returned.
• xlsx_data and pdf_data are returned as base64-encoded strings; decode before saving to files.
• The node requires a valid PostgreSQL URI in credentials_path; unsupported or malformed URIs will cause validation errors.

Troubleshooting

• Invalid JSON in join_config: Ensure join_config is a JSON array string. Example: [{"type": "INNER", "table": "orders", "on": "users.id = orders.user_id"}].
• Invalid JOIN type error: Use one of INNER, LEFT, RIGHT, FULL, CROSS.
• No data returned: Verify WHERE/HAVING filters and that selected_columns and joins reference existing columns.
• Credentials error: Provide a correct PostgreSQL URI (e.g., postgresql://:@:5432/).
• Service URL not configured: Ensure the PostgreSQL data connector endpoint is available in the environment configuration.
• Timeouts: Increase the timeout input for long-running queries or optimize the query (indexes, filters).
• Export outputs empty: html_table/xlsx_data/pdf_data are only populated when output_format is html/xlsx/pdf/all respectively.
• SQL syntax errors: Check that where_conditions, group_by_columns, having_conditions, and order_by_columns are valid SQL for PostgreSQL.