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 by these connectors |
| 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 fall into four categories. The category tells you where to
look; the message tells you what to change. Errors found when a query is saved
come back as 400 with code VALIDATION_ERROR, with the problem under
errors. Errors that happen while a query runs come back as 400 with code
BAD_REQUEST: the cause is in message, with secret values removed, and a
failure in the database also returns the query's slug in data.query_slug. A
500 with code INTERNAL_ERROR is an unexpected platform failure, not a
problem with the query.
Query validation#
The query text breaks a save-time check: it's empty, has more than one
statement, isn't 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. The detail is in errors.query_text. Correct the query
text.
Query configuration#
An external query has no connection secret, or the description is longer than
1,000 characters. The detail is in errors.secret_key or
errors.description. Correct the query definition.
Secret resolution#
The connection secret doesn't exist for the site and app, or its type isn't an
analytics type. The detail is in errors.secret_key. Create the secret, or one
of the right type.
Query execution#
The query was saved but failed while running: a parameter value is missing or
empty, the secret was deleted, the rows exceed the maximum, the connection
failed, or the database reported an error. Read message. A placeholder
problem can also carry a suggested fix in detail.
Interface support#
- TaruviBase Console — Find, create, edit, save, run, and delete queries; the Console builds CSV and JSON exports client-side from the returned rows.
- Python SDK 0.2.3 —
client.analytics.execute()and its async equivalent run a saved query. - JavaScript SDK 1.5.4 —
new Analytics(client).execute()runs a saved query. - Refine providers 1.3.7 —
appDataProviderruns a saved query withuseCustomandmeta.kind: 'analytics'; see the Refine provider reference. - Direct HTTP — The execution request below. Manage queries in the Console.
The Console counts the returned rows instead of reading total, and it
doesn't show execution_key. The execution route and both SDKs still receive
those fields.
Execution response format#
The SDK methods send this request:
{"params": {"year": 2026}}
Returns 200 with status, message, the rows in data, total, and
execution_key, which identifies the run.
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.