SQL – FACE Documentation

SQL

SqlService runs read-only SQL against one of the instance’s configured connections (see Configuration, connections & runners). The statement goes to the connection’s own engine, with parameters bound by the driver. FACE never builds SQL from your values. The agent loop’s run_sql tool uses the same service.

Summary

Service	RPC	Kind	Purpose
SqlService	Execute	Unary	Run a read-only query on a connection
SqlService	ExecuteSelect	Unary	The same as `Execute`, with its own message types
SqlService	ExecuteBatch	Unary	Run several read-only statements, one response each

Read-only rules

The server checks every statement before any connection is opened. The engine’s driver checks it again.

Comments and string literals are removed first. The rest is split on ; and each statement must start with SELECT, WITH, SHOW, DESCRIBE, DESC or EXPLAIN.
A statement that contains UPDATE, INSERT, DELETE, DROP, ALTER, GRANT, REVOKE, REPLACE, TRUNCATE, MERGE, EXEC, EXECUTE or CREATE as a word outside a string or comment is refused, even inside a SELECT.
A refusal is INVALID_ARGUMENT with the reason: only read-only queries (SELECT, WITH, SHOW, DESCRIBE, EXPLAIN) are allowed, query contains restricted keywords or empty query.

This check governs the shape of the query. What a query can read is governed by the credentials of the connection it runs on, so give each connection a read-only database role.

Engines

Connection type	Behaviour
Snowflake, Databricks, PostgreSQL, MySQL	Executes the statement or statements through the driver, with `params` bound as positional parameters.
BigQuery	Not executable. The call fails with `INTERNAL` and says so.
CCTV	No tabular result. The call fails with `INTERNAL`. Use the vision services.
Other connector types	Interpreted by that connector. A connector with nothing to query returns an error.

Several statements in one sql. The statements run in order on one database session. Their rows are concatenated into one result_json array. If the engine refuses some statements, the call still succeeds (success: true), and message names how many were refused and why. Their rows are not in the result. params cannot be combined with more than one statement.

SqlService

Full name semantics.v1.SqlService.

Execute

rpc Execute(ExecuteRequest) returns (ExecuteResponse);

Kind: Unary.
Auth: Bearer session. Every recognised role may call it.
Errors: INVALID_ARGUMENT if connection_id or sql is empty, the query breaks the read-only rules, the connection is not registered, or no connector exists for its type. INTERNAL if the connection record cannot be read, or the connector or engine fails (connecting, executing, or an unsupported type). The message carries the connector’s error.

Runs sql on the connection. The connection’s stored credentials are used. They never appear in the request or the response. When the call is made as part of a fetch, the run is also recorded in the lineage log.

Request: ExecuteRequest

Field	Type	Description
`connection_id`	`string`	Required. The connection to query.
`sql`	`string`	Required. One or more read-only statements.
`params`	`repeated string`	Positional parameters, bound by the driver. Allowed only with a single statement.

Response: ExecuteResponse

Field	Type	Description
`success`	`bool`	`true` when the read completed, even if some statements in a batch were refused (see `message`).
`message`	`string`	Empty on a clean read. Otherwise names the statements the engine refused and why.
`result_json`	`string`	The rows, as a JSON array of objects keyed by column name.
`columns`	`repeated string`	Column names, in result order.
`affected_rows`	`int64`	Number of rows read.

ExecuteSelect

rpc ExecuteSelect(ExecuteSelectRequest) returns (ExecuteSelectResponse);

Kind: Unary.
Auth: Bearer session.
Errors: The same as Execute.

Identical to Execute, with separate request and response messages.

Request: ExecuteSelectRequest

Field	Type	Description
`connection_id`	`string`	Required. The connection to query.
`sql`	`string`	Required. One or more read-only statements.
`params`	`repeated string`	Positional parameters. Allowed only with a single statement.

Response: ExecuteSelectResponse

Field	Type	Description
`success`	`bool`	As in `ExecuteResponse`.
`message`	`string`	As in `ExecuteResponse`.
`result_json`	`string`	JSON array of row objects.
`columns`	`repeated string`	Column names.
`affected_rows`	`int64`	Number of rows read.

ExecuteBatch

rpc ExecuteBatch(ExecuteBatchRequest) returns (ExecuteBatchResponse);

Kind: Unary.
Auth: Bearer session.
Errors: INVALID_ARGUMENT if connection_id is empty or statements is empty. Per-statement failures are not returned as errors: each one appears in responses.

Runs each StatementRequest as a separate Execute on the same connection, in order. A statement that fails yields a response with success: false and the message statement <n> failed. The detail is not returned, so retry that statement alone with Execute to see why.

Request: ExecuteBatchRequest

Field	Type	Description
`connection_id`	`string`	Required. The connection for every statement.
`statements`	`repeated` `StatementRequest`	Required. The statements, run in order.

Response: ExecuteBatchResponse

Field	Type	Description
`success`	`bool`	`true` only if every statement succeeded.
`responses`	`repeated` `ExecuteResponse`	One per statement, in order.

Messages

StatementRequest

Field	Type	Description
`sql`	`string`	A read-only statement.
`params`	`repeated string`	Positional parameters for this statement.

Compliance, finance & operations Lineage & activity