Analysis Using Nested Queries

Nested queries are powerful as they allow you to perform in-depth analysis in one API call that would require many individual calls with simple queries.

A normal analysis query provides frequency distribution or time series data for a single target. Nested analysis queries allows each result of a frequency distribution analysis to be broken down by the values of another target.

When creating nested queries you need to be aware that:

  • Nested analysis can only be used with analysis type freqDist, not timeSeries
  • The maximum depth of nesting is three: a parent and two children

Valid targets for nested queries

You can use any valid analysis target at the top level of your query. Valid analysis targets are listed on the targets page.

For child (or nested) analysis only low cardinality targets can be used. These are currently:

Submitting a nested query to the API

When you submit a standard frequency distribution query to the API it will take the following form, here for example analyzing author gender:

{
    "analysis_type": "freqDist",
    "parameters": {
        "target": "fb.author.gender",
        "threshold": 3
    }
}

To submit a nested query you add a child element to your query. So here our top-level analysis is by gender and the child analysis is by age:

{
    "analysis_type": "freqDist",
    "child": {
        "analysis_type": "freqDist",
        "parameters": {
            "target": "fb.author.age",
            "threshold": 5
        }
    },
    "parameters": {
        "target": "fb.author.gender",
        "threshold": 2
    }
}

Take a look at our nested query example for more details on submitting nested queries. Or for further examples see our Example Nested Queries page.

Valid target combinations

This matrix shows which targets you can use in combination for nested queries. Hover on a combination to understand what the combination will analyze.

You can see examples of the 'high' value queries on the Example Nested Queries page.