Finding the QQL Console
Whenever you start building a new metric, the QQL console within our tool is your starting point. You find it within our settings, by clicking the big wrench icon on the upper right, then navigating to “Custom metrics” on the left side.
Beside starting from scratch, you can also start from any of the existing metrics and modify, which sometimes makes life a lot easier, especially when you are just about to start building custom metrics. We always give the advice to search for a metric similar to what you try to build, and then use this metric as a starting point.
So let’s assume you would like to build a slightly modified version of our default Interaction Rate metric for Facebook. To take that metric as a starting point, simply click the little question mark either on a dashboard showing that metric, or on its maximized view.
Next you’ll see a dialog coming up showing further help for this metric. Within that dialog, if you scroll to the very end, you’ll see the QQL query this metric is built on. Next to it there is a little link called “Open in console”. This will take you straight into our QQL console using the Interaction Rate metric as a starting point.
The same approach works for any other metric in our tool. As you can see, even the pre-made metrics within our tool have all been built using the QQL Console, there is no exception.
How to use the QQL Console
Our QQL Console splits into multiple parts.
Metric name and list of all your existing custom metrics
On the very top left, you can see the current name of the metric you are working on. In case you started with one of the existing metrics as a base, you’ll notice that it already prefixed the metric name with “Custom”. It does that on purpose to indicate you are working on a new copy of the existing metric. Of course you are not able to overwrite any of the public metrics, but instead it’s creating your own private copy of it.
On the top right you find a drop-down listing all your custom metrics. In the very beginning this just holds one option named “Create a new metric…”. Once you save your first metric, it will be shown within that drop-down. This way you can easily navigate between all your custom metrics.
The query editor
Also on the left side, but slightly below the metric name, is the query editor box, which is definitely the heart of our QQL Console. Here you specify the visualization type (e.g. a table or a line chart), the QQL query used for fetching data, and further config by clicking “Edit config”.
The additional config beside the QQL query is especially important for visualization types that rely on further configuration. A very prominent example is a table metric, which holds information about the table’s column names, widths and types. For other visualization types like a line chart, the additional config is not used at all, at least not for standard use cases. Still, the “Edit config” dialog holds the full description of a metric in a JSON representation. You will also find the QQL query within that config, which is automatically synchronized from the query editor. The only information not being part of that config is the visualization type, which has to be set explicitly by using the drop-down left next to the “Edit config” link.
So whenever you want to send a custom metric to a colleague, the only thing you need to share is the visualization type and the full config you can see within the “Edit config” dialog. Sometimes our support team will also send you a metric config as JSON and it’s visualization type which you can then safely copy&paste into the “Edit config” dialog. Once saved and the correct visualization type is set, you can be sure you have the same metric in place as shared by our support team or your colleague.
Looking at the top right of the query editor you’ll find two buttons called “Run QQL” and “Save as…”. Whenever you do changes to your query or additional config, Run QQL is here to run the metric based on the new configuration. As a result the output shown within the visualization preview and query result will change. Once you finished building your custom metric, Save as… is what you need to permanently store it within your quintly account. It will kindly ask you to set a custom name and description to easily identify it later on. In case you are editing one of your existing custom metrics, it will always ask you if you want to create a new metric or if you want to overwrite the existing one.
Information about available data sources
Right next to the query editor you can see information about all data sources and their columns. These are the SQL tables you are able to access within your QQL query. Just click on a data source’s name and it will show the columns within that data source below.
Visualization Preview and Query Result
Once you click the Run QQL button, the output will be shown here, and it splits into two different parts. The Query Result simply shows the direct result of the QQL query as a table representation. This helps a lot to first figure out if your query running on top of the data sources has the correct output.
As a second step you need to ensure data is correctly mapped onto the visualization type you have selected. Each visualization type has different requirements when it comes to map data onto the visualization. In most of the cases mapping is done by renaming columns directly within the QQL query, usually named “dim1” to “dim<n>”. A very typical example is a line chart which expects columns “dim1”, “dim2” and a third column which it will automatically interpret as “dim3” (though you can of course also call it “dim3”) within the query result. Here is a simple example for a query fulfilling the mapping requirements of a line chart.
SELECT profileId AS dim1, time AS dim2, ownPostsLikes+ownPostsComments+ownPostsShares AS dim3 FROM facebook
Further information on mapping requirements per visualization type can be found separately within our documentation.