Analytics connectors and execution reference
Connector support, secret type naming, and the error categories a query can produce. Management is documented through TaruviBase Console, while application execution is documented through the SDKs.
Connectors
A saved query reaches exactly one connector, selected by its connection mode and, for external connections, by the type of the connection secret.
| Connector | Connection mode | Query language | Secret type |
|---|---|---|---|
| Your site's own data | Internal | SQL, PostgreSQL dialect | None |
| PostgreSQL | External | SQL | analytics-postgres |
| MySQL | External | SQL | analytics-mysql |
| Amazon Redshift | External | SQL | analytics-redshift |
| ClickHouse | External | SQL, ClickHouse dialect | analytics-clickhouse |
| Elasticsearch | External | Query DSL, JSON | analytics-elasticsearch |
An external connector works when TaruviBase can reach your database over the network and you supply read-only credentials in a connection secret of the matching type.
When a query is saved, its text is read in the SQL dialect of its own connector: PostgreSQL for internal and PostgreSQL queries, and the MySQL, Redshift, or ClickHouse dialect for those connectors. A statement the dialect cannot read is refused when the query is saved.
| Connector | Default row maximum | Where it is set |
|---|---|---|
| Internal | 10,000 rows | Fixed in the connector |
| PostgreSQL, MySQL, Redshift, ClickHouse, Elasticsearch | 10,000 rows | max_result_rows in the connection secret, when present |
A run that exceeds the maximum fails instead of returning a partial result.
Connection secret types
The secret's type selects the connector. Type slugs follow a single convention:
analytics-{connector}
A secret whose type is outside the set above is rejected when the query is saved. An internal query uses no secret and no type.
Credential fields are defined by each secret type's schema, but stored fields and consumed fields are not identical in the current connectors:
| Connector | Stored field that is currently ignored |
|---|---|
| PostgreSQL, MySQL, Redshift | SQL options is ignored when the SQLAlchemy URL is built |
| Elasticsearch | Elasticsearch api_key, verify_certs, and ca_certs are ignored; use the consumed username/password or custom headers, and do not infer a TLS override |
| ClickHouse | No ignored seeded connection field identified in the current constructor |
Read both the secret type and this consumption boundary before filling in a connection. Secret resolution is cached for up to 3,600 seconds by default, with best-effort invalidation on mutation.
Error categories
Analytics failures resolve to a small set of categories. The category tells you where to look; the message tells you what to change.
| Category | Raised when | Where the detail appears | Fix |
|---|---|---|---|
| Query validation | The query text breaks a save-time check: it is empty, is more than one statement, is not a read, uses a blocked function, misuses a placeholder, puts a stored secret outside a filter, names an unknown internal table, or is invalid JSON for Elasticsearch | errors.query_text, with a suggested fix in detail when one exists | Correct the query text |
| Query configuration | An external query has no connection secret, or the description is longer than 1,000 characters | errors.secret_key or errors.description | Correct the query definition |
| Secret resolution | The connection secret does not exist for the site and app, or its type is not an analytics type | errors.secret_key | Create the secret, or create one of the right type |
| Query execution | The query was saved but failed while running: a missing or empty parameter value, a deleted secret, a row count over the maximum, a connection failure, or an error the database reports | message, with a suggested fix in detail when one exists | Read the returned message |
Errors found when a query is saved come back as HTTP 400 with code
VALIDATION_ERROR. Errors that happen while a query runs come back as HTTP
400 with code BAD_REQUEST; the message says what went wrong.
Interface support
| Interface | State | Notes |
|---|---|---|
| TaruviBase Console | Supported | Find, create, edit, save, run, and delete; CSV/JSON export is performed client-side from returned rows |
| Python SDK | Supported (0.2.1) | client.analytics.execute() and its async equivalent run a saved query |
| JavaScript SDK | Supported (1.5.3) | new Analytics(client).execute() runs a saved query. The response includes execution_key, although the TypeScript type doesn't declare it |
| Direct HTTP | Reference only | The execution request is shown below; manage queries in the Console |
| Refine provider | Not applicable | No analytics-specific provider exists |
The Console uses the returned row count instead of the wire total when it
processes the current flat response, and it does not surface the top-level
execution_key. The execution route and both SDKs still receive those fields
on the wire.
Execution response format
This is a non-executable protocol reference for the request made by the SDK methods. It is not a direct-HTTP tutorial.
| Part | Contract |
|---|---|
| Method and path | POST /api/apps/{app_slug}/analytics/queries/{slug}/execute/ |
| Request body | { "params": { ... } } |
| Success | HTTP 200; a flat envelope with status, message, top-level data, total, and execution_key |
Create, list, retrieve, update, and delete HTTP routes are not published; manage queries in TaruviBase Console. There is no server-side export operation; Console formats already-returned rows in the browser.