Knowledge Base

Navigating Nested Structures in Narrative Query Language (NQL)

Introduction to Complex Data Types in NQL

When delving into data analysis with NQL, one frequently encounters complex types such as objects and arrays. These types are powerful tools for representing hierarchical or multi-valued data. Objects encapsulate data fields in key-value pairs, while arrays are ordered collections of items that may contain either primitive data types or further objects.

In the data-centric world of NQL, mastering these structures is vital for extracting meaningful insights from nested data. This guide will provide a clear understanding of working with these complex types, underpinned by an example that demonstrates the concepts in action.

Principles of Objects and Arrays in NQL

Objects are denoted by {} and contain a set of properties (key-value pairs), whereas arrays, denoted by [], contain an ordered list of items. NQL provides functionality to navigate through these nestled structures, allowing seamless access to the underlying data.

Crafting a Query for Materialized Views with Objects and Arrays

The following illustrates how to construct a generalized query that creates a materialized view with object and array notation in NQL:

CREATE MATERIALIZED VIEW "generic_billing_report" AS WITH ExpandedData AS
(SELECT "country_code",
"company_data"."dataset_identifier"."additional_info"."billing_details"[0]['source_id'] AS "billing_source"
FROM "company_data"."dataset_identifier"
WHERE "company_data"."dataset_identifier"."event_timestamp" BETWEEN 'start_period' AND 'end_period' )
SELECT "country_code",
COUNT("user_identifier") AS "Total_Billing_Entries"
FROM ExpandedData
GROUP BY "country_code",

*Note: Replace start_period and end_period with the actual time range for your analysis.*

In-Depth Understanding of Nested Structures:

1. Accessing Array Elements: Individual elements of an array can be accessed by using an index number enclosed in square brackets. For instance, billing_details[0] references the first element of the array.

2. Retrieving Object Properties: Use a bracketed string (e.g., ['source_id']) to extract specific properties from an object. This allows for pinpointing data within nested JSON-like structures.

3. Quotation Standards: While identifying columns and tables, always remember to enclose them in double quotes. Conversely, single quotes are used for accessing properties within an object to delineate literal strings.

Detailed Walkthrough:

Let’s dissect the example to articulate how objects and arrays contribute to the billing report creation:

- The WITH clause initiates a subquery ExpandedData that serves as a foundation to the main query.

- In ExpandedData, the country_code and user_identifier are directly acquired attributes, yet we delve deeper into the structure by addressing array elements and object properties with billing_details[0]['source_id'].

- billing_source is the alias we assign to our extracted property to epitomize it in the query and to later facilitate data grouping.

- The main SELECT block assembles the final view, synthesizing the required data fields and applying COUNT to tally user_identifier occurrences within the grouping.

- Consequently, the GROUP BY clause amalgamates the results by country_code and the derived billing_source.

Maximizing Query Efficacy:

- Consistent Reference: Unwavering attention to referencing accuracy is paramount to ensure that the intended data is accessed, avoiding any misalignment in results.

- Query Testing: Rigorously test and validate your NQL queries to safeguard query integrity and result reliability.

- Performance Awareness: High levels of nesting and array size can weigh down query performance. Working with complex data sometimes requires additional optimization strategies.


Objects and arrays present in your datasets can be navigated deftly with NQL, revealing potent avenues for data analysis. By applying these guidelines, you can harness NQL's full capabilities to dissect and analyze multidimensional data.

Should you have further inquiries or require more guidance, do not hesitate to refer to ongoing tutorials in our Knowledge Base or connect with Narrative's dedicated support.

< Back

Hi! I’m Rosetta, your big data assistant. Ask me anything! If you want to talk to one of our wonderful human team members, let me know! I can schedule a call for you.