Skip to main content

Create and manage a saved query

Create a query, give it a name you can rely on, edit it without breaking callers, and remove it safely when it is no longer needed. You manage queries in TaruviBase Console; the SDKs only run them.

Prerequisites​

Find an existing query​

Open the app in TaruviBase Console and select Analytics. Use Search queries... to filter by name, slug, description, or connection secret key. Open a row to view its Analytics Query workspace.

Procedure​

1. Create the query​

  1. Select Create Query from Analytics.
  2. In Create New Query, enter a required Query Name. The name generates a slug, and SDK callers address the query by that slug from this point forward.
  3. Optionally enter a Description of at most 1,000 characters and add Tags. Console creates a tag on the fly if you type a name that does not already exist.
  4. Choose the connection mode. Turn Internal Query on for the site's own data; leave it off and choose Database Connection for an external query. Turning Internal Query on clears any connection the query held.

There is no policy field in this dialog. The query's execution policy is created open to callers who hold an app role, and locking execution down to specific roles is a separate step. That policy controls who can run the query, not who can edit or delete it — see Who can run and manage queries.

2. Write the query text​

Enter the statement under Query Text *. For an internal or SQL connection this is a read statement; for an Elasticsearch connection it is a JSON search body. Console offers starter templates if you want a working shape to edit.

For a self-contained first query, use SELECT 1 AS ready; it has no table, tag, secret, or parameter prerequisite.

3. Save and read the validation result​

Select Create Query. Analytics validates the query text against the target connector before storing it.

If it is refused, the message names the problem, for example: more than one statement, a statement that writes, a blocked function, a placeholder used in a way the rules do not allow, a stored secret outside a filter, an unknown internal table, a missing connection secret, or a referenced secret that does not exist. Correct the query text and save again. The troubleshooting page lists every message.

A query that saves has passed its connector's checks. No save check validates the types of future parameter values or proves that the query returns what you intended — see Run a query and read the results next.

Verify​

The query exists and is correctly defined when it appears in the app's Analytics list with the expected connection shown.

Rename or edit a query​

Open the query and use the edit control to open Edit Query. Change its Query Name, Description, connection selection, or Tags, then select Save Changes.

Edit the statement in the query workspace and select Save. Save & Run saves the edit and runs the query straight away. Every edit re-runs the same checks as creating the query. A successful save doesn't prove Analytics can reach the database.

Rename freely. The slug is fixed when the query is created, so renaming does not break callers that already reference it.

Delete a query​

Deletion is not reversible

Deleting a query permanently removes its query text, name, and connection settings, along with its execution records (the saved history of its past runs). The connection secret the query points to is not deleted. Anything still calling the query by its slug stops working.

Before you confirm deletion:

  • Affected resource and cascade — confirm the app and query slug; the query definition and its execution records will be deleted.
  • Reversibility — understand that Analytics has no archive, disable, or restore operation for a deleted query.
  • Authorization — deletion checks only that you are signed in, not your app role, so confirm you are the right person to remove the query.
  • Backup — copy the query text, connection mode, connection secret key if applicable, description, and tags needed to recreate it.
  • Confirmation — confirm that no caller still uses the slug. The dialog asks you to confirm before it deletes anything.
  • Success and postcondition — Console returns to the Analytics list, the query is gone, and its page no longer opens.
  • Recovery — if deletion was a mistake, recreate the query from the backup and update callers if the restored slug differs.

Open the query and select the delete control. In Delete Query, confirm the query name and read the warning: the action cannot be undone, and all execution history for the query will also be deleted. Select Delete Query only after completing the checks above; otherwise select Cancel.

When it succeeds, the query disappears from the app's Analytics list and its slug no longer resolves. Recreating a query with the same name produces the same slug as long as no other query in the site holds it, but you have to supply the query text again.

If you are not certain, rename the query instead and leave it unused. There is no archive or disable state, so renaming is the only reversible alternative.

Troubleshoot​

If the query will not save, see Troubleshoot Analytics.