Plug Database Advanced icon

Plug Database Advanced

Run Plug Database commands over REST or Socket.

Actions26

SQL → Execute SQL

AI-generated

Summary

Execute an SQL statement against a target Plug agent using either REST or socket channel, in guided or advanced JSON-RPC mode, and return the query result in various output formats.

Inputs

  • Channel — Select whether to run the SQL command over REST or the Plug consumer socket.
  • Input Mode (required) — Choose between Guided mode (simplified SQL with parameters) or Advanced mode (full JSON-RPC command input).
  • SQL (required) — The SQL statement to execute (used in Guided mode).
  • Named Params JSON — Optional JSON object defining named SQL parameters (used in Guided mode).
  • Raw JSON-RPC Command (required) — Full JSON-RPC command object to execute (used in Advanced mode).
  • Response Mode — Select output representation: Aggregated JSON, Chunked Items (streaming), or Raw JSON-RPC envelope.
  • Agent ID — Override the target Plug agent; if empty, uses Default Agent ID from credentials.
  • Client Token — Override the Plug client token; if empty, uses Default Client Token from credentials.
  • Include Plug Metadata — Whether to add the '__plug' metadata object to the output, containing channel, agent, request, and socket info.
  • Additional Options — Configure advanced settings such as timeout, API version, max rows, execution mode, pagination, database/schema target, idempotency key, and multi-result support.
  • Socket Options — When running over socket channel, options to control buffering and stream chunk request windows.

Output shape

a list of items representing the SQL query result rows, or a single JSON item when row-based conversion is not possible, or a streaming sequence of chunked items when streaming mode is enabled over socket.

The output format depends on the selected Response Mode. Aggregated JSON returns all rows as items or a single JSON. Chunk Items streams rows as items during socket SQL streams. Raw JSON-RPC returns the full normalized command response envelope useful for debugging or advanced workflows. The '__plug' metadata is included if enabled in options.

Examples

Example 1: Basic guided SQL execution

Set Channel to REST, Input Mode to Guided, provide SQL query and optional named parameters, and choose Aggregated JSON response mode.

Example 2: Advanced SQL with custom JSON-RPC

Set Input Mode to Advanced, provide full JSON-RPC command to run complex queries or additional parameters, and optionally select Raw JSON-RPC response to get command metadata.

Example 3: Streaming large result sets

Use Channel Socket with Response Mode Chunk Items and configure socket streaming options to handle large data in chunks.

Links

Discussion