Knowledge Base

Creating Materialized Views in NQL

Creating Materialized Views in NQL

Materialized views in Narrative SQL (NQL) offer a powerful way to store the results of complex queries as datasets within the Narrative Data Collaboration Platform. These datasets, generated from materialized views, inherit all the benefits of standard datasets, including accessibility, integration capabilities, and governance. This document details the process of creating materialized views in NQL, emphasizing the available metadata options to optimize your data management practices.

Understanding Materialized Views

A materialized view in NQL is not just a view but a stored dataset created from a specific query. Unlike traditional views that dynamically retrieve data, materialized views hold the data as it was at the time of the view's creation, making it a snapshot of the query result. This approach is particularly useful for capturing and analyzing data states over time.

Example Usage: Creating a Materialized View

DISPLAY_NAME = 'Female Audience'
DESCRIPTION = 'Audience containing demographic of female users.'
EXPIRE = 'retain_everything'
STATUS = 'active'
TAGS = ( '_nio_materialized_view', 'user_engagement', 'metrics' )
WRITE_MODE = 'overwrite'
SELECT "unique_identifier",
FROM narrative.rosetta_stone
    "hl7_gender"."gender" = 'female'
    AND "event_timestamp" > CURRENT_TIMESTAMP - INTERVAL 160 DAYS
    AND rosetta_stone._price_cpm_usd <= 2.00

This example creates a materialized view that tracks daily user engagement, with detailed specifications on display name, description, retention policy, and data partitioning.

Metadata Options for Materialized Views

When creating a materialized view in NQL, several metadata options allow for customization and optimization of the resultant dataset. These options include:


  • Purpose: Assigns a human-readable name to the dataset, often reflecting its content or business context.
  • Syntax: DISPLAY_NAME = '<display_name>'


  • Purpose: Provides a detailed description of the dataset's purpose, contents, and any relevant contextual information.
  • Syntax: DESCRIPTION = '<description_text>'


  • Purpose: Sets a data retention policy for the dataset, specifying how long data should be retained.
  • Syntax: EXPIRE = { <ISO 8601 PERIOD> }
  • Options:
    • expireWhen > ISO PERIOD: Data expires after the specified ISO 8601 period.
    • retain_everything: Retains all data indefinitely.
    • expire_everything: Specifies that the data should be expired immediately, effectively not retaining any data.


  • Purpose: Defines the current status of the materialized view.
  • Syntax: STATUS = { 'active' | 'updating' | 'draft' }
  • Options:
    • active: The view is active and queryable.
    • updating: The view is currently being updated.
    • draft: The view is in a draft state and not queryable (planned for future implementation).


  • Purpose: Allows for the assignment of tags to the dataset for organizational and searchability purposes.
  • Syntax: TAGS = ( '_nio_materialized_view', '<tag1>', ... )


  • Purpose: Determines how the data is written to the dataset when the materialized view is refreshed.
  • Syntax: WRITE_MODE = { 'append' | 'overwrite' }
  • Options:
    • append: Adds new data to the existing dataset.
    • overwrite: Overwrites the existing dataset with the new data.


  • Purpose: Enables or disables the collection of extended statistics for the dataset.
  • Syntax: EXTENDED_STATS = { 'all' | 'none' }


  • Purpose: Defines how the dataset should be partitioned, based on specified fields and transformations.
  • Syntax: PARTITIONED_BY <field> <transform>, <field2> <transform>


Creating materialized views in NQL is a strategic approach to data management, offering enhanced data analysis capabilities through the persistence of query results. By understanding and utilizing the available metadata options, you can tailor your materialized views to fit your specific data management and analysis needs on the Narrative Data Collaboration Platform.

Learn more about datasets

Learn more about the Narrative dataset construct.

< 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.