Execution model

DataPorch uses a progressive workflow so an agent does not have to guess the database shape:

source ID
  → exact schema
  → exact relation
  → exact columns
  → one row-producing statement

Discovery

Discovery searches are case-insensitive literal substrings. They are not arbitrary SQL or regular expressions. Each operation accepts an optional limit and opaque cursor; cursors are tied to the request shape, so changing the source, parent identifier, or search parameters invalidates a cursor.

Use the returned identifiers exactly. Do not normalize case, rewrite quoted names, or invent a schema when the source did not return one.

Query execution

relational_database.query accepts kind, source_id, and one complete row-producing query. The execution service checks that the declared kind matches the configured source, authorizes the operation, and delegates to the matching adapter. The query result includes column names and database types, rows represented as arrays, row_count, and a truncated flag.

Null cells remain JSON null; they are not converted to empty strings. A successful response can be truncated by the row or encoded-response budget, so clients must inspect truncated before treating a result as complete.

Failure handling

Failures have a stable category, human-readable message, retryability flag, and optional bounded database error metadata. Retry only categories marked retryable, such as temporary database unavailability or query timeout. An invalid cursor, missing source, permission denial, or unsupported capability needs a changed request or configuration.

See the complete category table in Errors.