Nested Analysis 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
  • A child or nested analysis can only contain low cardinality targets (fewer than 50 unique values)

For more details see our Analysis Using Nested Queries guide. Or for further examples see the Example Nested Queries page.

Single-level nesting - age-gender breakdown

A common example analysis you might want to perform is an age-gender breakdown. You could achieve this by submitting a separate age analysis request for each gender in turn and combining the results yourself, but using a nested query achieves this for you in one API call.

You perform a nested query by speficifying the child parameter of your call to /pylon/analyze. This parameter expects similar arguments as its parent analysis.

If you start with a Frequency Distribution analysis of gender:

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

You can add nesting to this query (here looking at age groups) by adding a child parameter. So here our top-level analysis is by gender and the child analysis is by age:

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

The results you receive from the API are nested accordingly. For this example query for instance for each gender you'll receive overall counts plus within each gender a child distribution with counts for age groups within the gender.

For example:

{
    "analysis": {
        "analysis_type": "freqDist",
        "parameters": {
            "target": "fb.author.gender",
            "threshold": 2
        },
        "redacted": false,
        "results": [
            {
                "child": {
                    "analysis_type": "freqDist",
                    "parameters": {
                        "target": "fb.author.age",
                        "threshold": 2
                    },
                    "redacted": false,
                    "results": [
                        {
                            "interactions": 37900,
                            "key": "25-34",
                            "unique_authors": 27200
                        },
                        {
                            "interactions": 36800,
                            "key": "18-24",
                            "unique_authors": 26700
                        }
                    ]
                },
                "interactions": 131600,
                "key": "male",
                "unique_authors": 97300
            },
            {
                "child": {
                    "analysis_type": "freqDist",
                    "parameters": {
                        "target": "fb.author.age",
                        "threshold": 2
                    },
                    "redacted": false,
                    "results": [
                        {
                            "interactions": 18900,
                            "key": "25-34",
                            "unique_authors": 14700
                        },
                        {
                            "interactions": 16700,
                            "key": "35-44",
                            "unique_authors": 13200
                        }
                    ]
                },
                "interactions": 80100,
                "key": "female",
                "unique_authors": 70400
            }
        ]
    },
    "interactions": 215600,
    "unique_authors": 161000
}

Summarizing the results above in the table:

Gender Age Group Interactions Authors
Male -- all -- 13400 10000
25-34 13000 9800
Female -- all -- 5500 5400
18-24 5100 4900
25-34 300 300

Two-level nesting

The platform allows you to perform upto two levels of nesting. To achieve this you again add a child parameter this time to the child of the top analysis.

For example perhaps you'd like to analyze by country, gender then age. The request would be as follows, notice here we have three levels of analysis parameters:

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

Again the results from the API will be nested to match the structure of the query...

{
   "unique_authors":161000,
   "analysis":{
      "analysis_type":"freqDist",
      "redacted":false,
      "results":[
         {
            "child":{
               "analysis_type":"freqDist",
               "redacted":false,
               "results":[
                  {
                     "child":{
                        "analysis_type":"freqDist",
                        "redacted":false,
                        "results":[
                           {
                              "unique_authors":24600,
                              "key":"25-34",
                              "interactions":34100
                           },
                           {
                              "unique_authors":24300,
                              "key":"18-24",
                              "interactions":33600
                           }
                        ],
                        "parameters":{
                           "threshold":2,
                           "target":"fb.author.age"
                        }
                     },
                     "unique_authors":89200,
                     "key":"male",
                     "interactions":118200
                  },
                  {
                     "child":{
                        "analysis_type":"freqDist",
                        "redacted":false,
                        "results":[
                           {
                              "unique_authors":13900,
                              "key":"25-34",
                              "interactions":17700
                           },
                           {
                              "unique_authors":12600,
                              "key":"35-44",
                              "interactions":15900
                           }
                        ],
                        "parameters":{
                           "threshold":2,
                           "target":"fb.author.age"
                        }
                     },
                     "unique_authors":67500,
                     "key":"female",
                     "interactions":76100
                  }
               ],
               "parameters":{
                  "threshold":2,
                  "target":"fb.author.gender"
               }
            },
            "unique_authors":151700,
            "key":"United States",
            "interactions":195000
         },
         {
            "child":{
               "analysis_type":"freqDist",
               "redacted":false,
               "results":[
                  {
                     "child":{
                        "analysis_type":"freqDist",
                        "redacted":false,
                        "results":[
                           {
                              "unique_authors":2400,
                              "key":"25-34",
                              "interactions":3700
                           },
                           {
                              "unique_authors":1900,
                              "key":"35-44",
                              "interactions":3200
                           }
                        ],
                        "parameters":{
                           "threshold":2,
                           "target":"fb.author.age"
                        }
                     },
                     "unique_authors":8400,
                     "key":"male",
                     "interactions":13400
                  },
                  {
                     "child":{
                        "analysis_type":"freqDist",
                        "redacted":false,
                        "results":[
                           {
                              "unique_authors":800,
                              "key":"25-34",
                              "interactions":1100
                           },
                           {
                              "unique_authors":600,
                              "key":"18-24",
                              "interactions":900
                           }
                        ],
                        "parameters":{
                           "threshold":2,
                           "target":"fb.author.age"
                        }
                     },
                     "unique_authors":3000,
                     "key":"female",
                     "interactions":3900
                  }
               ],
               "parameters":{
                  "threshold":2,
                  "target":"fb.author.gender"
               }
            },
            "unique_authors":11700,
            "key":"United Kingdom",
            "interactions":17500
         }
      ],
      "parameters":{
         "threshold":2,
         "target":"fb.author.country"
      }
   },
   "interactions":215600
}