Skip to main content

Run a query and read the results

Run a saved query with the JavaScript or Python SDK, pass the values it needs, and check that the result changes with those values before you rely on it. Use TaruviBase Console to preview results and export them.

Prerequisites​

A saved query. See Create and manage a saved query if you do not have one yet.

Procedure​

1. Execute the query with parameters​

Send one value for each placeholder in the query text, keyed by the placeholder's name. Every placeholder is required. Each value is treated as data and cannot change what the query does. See Placeholders and bound values for the full rules.

const analytics = new Analytics(client);

const result = await analytics.execute('QUERY_SLUG', {
  params: { status: 'open' },
});

Both SDKs return the whole response, so read the rows from data. JavaScript SDK 1.5.3 returns execution_key, but its AnalyticsResponse type doesn't declare it. Python SDK 0.2.1 returns the full dictionary. See the execution response format for every field.

To match several values, send a list and write the placeholder inside IN, for example WHERE status IN ({{ statuses }}) with params: { statuses: ['open', 'paid'] }. An empty list is refused.

Analytics stores the raw parameter values in the execution record. Do not send credentials, tokens, or personal data as parameters.

2. Read the result​

Check three things before trusting the query:

  • the columns are the ones you expected;
  • the row count is plausible for the filter you supplied; and
  • changing a parameter value changes the result.

Changing a value and watching the result change verifies that the placeholder affects this query. It does not check that the value has the type the column expects; a value of the wrong type produces an error from the database.

For an Elasticsearch connection, a query containing aggregations returns the aggregation output as rows instead of matching documents — each row identifies which aggregation it came from.

Preview and export in TaruviBase Console​

  1. Open the query from the app's Analytics list and select Params.
  2. Console detects the {{ param }} placeholders in Query Text and shows a field for each one. Supply a value for every field.
  3. Select Run, or press Ctrl/Cmd+Enter.
  4. Open Result and verify the returned rows. The Console counts the rows it received and doesn't show the execution_key.

Export the returned rows​

From Result, select Copy results as JSON to copy the rows, or select Export, then Export as CSV or Export as JSON. These actions format rows already in the browser; they do not call a server-side export operation. There is no export path for execution history, and neither SDK has an export method. If application code needs a file, format the rows its execute call already returned.

Verify​

The SDK call is working when it returns rows without an error and includes an execution key. Supplying a different value should return a different result. A Console run is working when Result changes as expected. Console doesn't show the execution key.

Troubleshoot​

If a run fails, returns too many rows, or the result does not change with your parameters, see Troubleshoot Analytics.