Query

Queries allow you write SQL queries to retrieve data from your data sources or modify your databases in queries.

Queries must be created from Tables and are only available in the current app. However, you can have multiple queries for the same tables.

All elements across pages can interact with Queries through interactions, including trigger Run Query or Set SQL Parameters.

Set up a query

Queries must be created from Tables and are only available in the current app. There are two methods to instantiate a query:

From Tables
1. Navigate to the desired table.
2. Click on the More option
3. Select Create Query .
Adding from Query Tab
1. Go to the Query tab.
2. Click on Add Query.
3. Choose the table from which you wish to create the query.

Edit Queries

After creating the queries, double click on it to edit.

Queries Name: In app name of your query
Database Name: Represents the database you are currently querying against.
Data Directory: Displays all the available tables across different databases within the same database type, including Acho-hosted and self-hosted databases. For example, in the PostgreSQL query, you can find all the available PostgreSQL databases, but it doesn't include other types of databases (such as MySQL). Also, you cannot query against tables across different PostgreSQL databases simultaneously.
Query Pane: The pane allows you to write queries. It supports writing a single query at a time. Currently, it doesn't support writing functions or procedures. Macro is supported to help you do complex operation Macros
Generate by AI: Click on this button to access the AI panel, which leverages generative AI to assist you in writing SQL queries. You can streamline the query creation process using natural language prompts.
Run: Run the query in the Query Pane and display the query results in the above Table Preview. Note that it's only to run the query but won't save it and its results.
Save: Run the query and save all the changes (including the query, query results, and parameters).
Parameter Pane: This pane allows you to create parameters and their initial values. These parameters are dynamic and can be used in the Query Pane. See here to learn more about how to set up parameters.
Table Preview: When you run a query, the results will be presented in the Table Preview. Use the pagination below to switch page.

How do queries work?

Each queries functions like a script, storing an SQL query. When triggered by other elements, the query node fetch information including database address from table node, then run the query, either retrieving data or modifying the database. If the query returns data, the data is stored in Acho's in-memory database, serving as a cache layer for your app. However if your statement is DML (UPDATE, INSERT, DELETE) or DDL(CREATE, DROP), no data will be stored in the query.

Queries Syntax

The syntax of a queries is determined by the data source they connected

Acho resource and Data Prep Projects: Acho resource and Data Prep Projects are replicated and stored in an Acho-hosted data warehouse. For query nodes connected to resources and the Data Prep Project, use BigQuery syntax. See which statements and functions you can use.
At present, it's recommended to use only SELECT queries in such queries. Any data modifications made using DML (UPDATE, INSERT, DELETE) or DDL (CREATE, DROP) may be overwritten when the data source is synced, resulting in the loss of those changes.
Direct Connector: Query against your database directly. It allows you to query all data stored in your database and supports DQL (SELECT), DML (UPDATE, INSERT, DELETE) or DDL(CREATE, DROP). Different databases have their own SQL dialects and syntax. Currently, we support the following databases for direct access: - PostgreSQL - MySQL - Snowflake - MongoDB

Set SQL Parameters

Parameters are used for creating dynamic queries. They are like variables that can store any value and be inserted into queries. Their values can be changed via event actions Set SQL Parameters. See detailed example in Create a filter.

1. Add new parameter

Click the plus icon at the Parameter Panel to add new parameter. You need to specify name and datatype and Default value(optional but recommended).

2. Insert parameters in SQL query

All parameters can be inserted anywhere in the query. The parameter replaces {{parameter_name}} with the value specified in the parameter.

Here are some examples:

Pass a string: (need quotes to represent it as string)

SELECT *
FROM customers
WHERE customer_id = '{{customer_id}}'

Pass an integer or a number: (doesn't require quotes)

SELECT *
FROM customers
WHERE age = {{customer_id}}

Pass a column name: (doesn't require quotes)

SELECT {{category}}, COUNT(DISTINCT customer_id) AS n_customers
FROM customers
GROUP BY {{category}}

3. Deal with arrays or objects

If your parameter is an array, you have to use "macro" to turn the array or object into a format that the database can ingest.

Use an array to specify values in the IN statement

Suppose you have a parameter called categories. It's an array and contains three values.

{
categories: ["New", "Repeat", "Royal"]
}

Now, we want to create a query to filter the customer table and get all the customers in these three categories via the IN statement as shown below.

SELECT *
FROM customers
WHERE category IN ("New", "Repeat", "Royal")

However, the array cannot be passed to the query directly since the query doesn't need the square brackets. In this situation, we need to use "macro" to do some transformation to the array parameter. Macro is a templating language that can help you generate queries. It supports various functionalities, such as for loop, or conditional statement (if and else). In this example, we want to use the for loop to pass all the values in the array one by one and use joiner() the function in macro to concatenate all the values with a comma.

{% set comma = joiner() %}
SELECT *
FROM customers
WHERE category IN ( {% for category in categories} {{comma}} '{{category}}' {% endfor %})

You can also use an array to select multiple columns. Suppose you have a parameter called columns, which you can dynamically set by Set SQL parameters. By default, columns is an array that contains four column names.

{
categories: [
    "first_name",
    "last_name",
    "type",
    "last_login"
    ]
}

SELECT {{ columns|join(',') }}
FROM customers

Macros

Macro is a templating language that enhances queries to make them dynamic. It supports various functionalities, including for loops and conditional statements (if and else).

See available macros template at https://mozilla.github.io/nunjucks/templating.html