Finding the Metric Builder
Whenever you start building a new metric, the Metric Builder within our tool is your starting point. You find it by clicking on the Custom Metrics tab and then the Build new Metric button to the top right.
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.
For example, if you want to show data over time in a line chart, you may choose to start with the default Fans Total metric for Facebook. To take that metric as a starting point, simply click the three dots on the dashboard widget of that metric and then on Open in Metric Builder.
You can also open a metric in the Metric Builder before even adding it to a dashboard. When you're in Discover and preview a metric, you will see a section called Metric Customization which will also link to the Metric Builder.
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 Metric Builder
The Metric Builder has several parts: The metric name and information, the QQL Console, the Config, the results & the documentation.
Metric name and information
Here you can name your metric and also add additional information such as a summary, description and use case. Note: only the name field is required to be filled in - the other fields are optional.
The QQL Console
This is where the query goes. Make sure you check the Documentation section to the right if you are unfamiliar with the available data sources and fields. We also have an article on the Technical Details on Writing QQL Queries.
For our Fans Total example, this is what you'll see in the QQL Console when you first open this metric in the Metric Builder: SELECT profileId AS dim1, time AS dim2, fans FROM facebook
Now, let's say we actually just wanted to see the number of local fans. We can modify the metric to have this new query: SELECT profileId AS dim1, time AS dim2, fansLocal FROM facebook
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 config dialog holds the full 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 above the QQL Consoles.
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 config 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 config. 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.
Here you can view the most updated results based on changes you've made in the console or config. The preview is the actual visual representation of the results, while the query results 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.
So for our local fans example, the preview will be the line chart, while the query results will be the values for dim1, dim2 and localFans.
This is a list of all available data sources and their respective fields in quintly. For descriptions of these fields, you can reference our API Documentation.