Knowledge Base

Overview of Narrative Query Language (NQL)

Narrative Query Language (NQL) is a SQL-like language designed for querying datasets within the Narrative Data Collaboration Platform. NQL allows users to create complex queries to search, analyze, and manipulate data stored in the platform. Its syntax and structure are similar to SQL, making it familiar and easy to use for those with SQL experience. For more information on Narrative's APIs and NQL visit our documentation: https://api.narrative.dev/

Finding Your Data Plane ID

Users can find their data_plane_id by navigating to My Data > Data Planes and selecting "Copy Identifier" from the ellipses on each row in the data planes table in the UI: Narrative Data Planes.

Using the Validate Endpoint

The validate endpoint in the NQL API allows users to verify the syntax and structure of their NQL queries before executing them. This ensures that the queries are correctly formatted and will not cause errors when passing through the /run endpoint. The primary goal of using the validate endpoint is to receive a 200 OK status code, which indicates that the query is valid.

Request URL and Method

• URL: https://app.narrative.io/openapi/nql/validate
• Method: POST

Request Payload

The request payload should contain the NQL query and the data plane ID. Here is an example payload:

{
    "nql": "SELECT company_data.\"8295\".\"hem_1\", 
company_data.\"8295\".\"ip_address\", company_data.\"8295\".\"maid\" 
FROM company_data.\"8295\" WHERE 
company_data.\"8295\".\"country_code\" = 'US' 
AND company_data.\"8295\".\"age\" > 45",
    "data_plane_id": "000000-aaaa-bbbb-cccc-ddddddddd"
}

Response Structure

A successful validation returns a status code of 200 OK and provides an Abstract Syntax Tree (AST) of the query, detailing the structure of the query and its components, such as the query type, columns, tables, and conditions.

Using the Run Endpoint

The run endpoint in the NQL API allows users to execute their NQL queries. This endpoint processes the query and performs the specified operations within the Narrative platform. Depending on the NQL provided, the run endpoint can create materialized views or generate forecasts.

Request URL and Method

• URL: https://app.narrative.io/openapi/nql/run
• Method: POST

Request Payload

The request payload should contain the NQL query and the data plane ID. Here are two example payloads:

Creating a Materialized View

{
    "nql": "CREATE MATERIALIZED VIEW \"how_to_create_a_query\" AS 
SELECT company_data.\"8295\".\"hem_1\", company_data.\"8295\".\"ip_address\", 
company_data.\"8295\".\"maid\" FROM company_data.\"8295\" WHERE 
company_data.\"8295\".\"country_code\" = 'US' 
AND company_data.\"8295\".\"age\" > 45",
    "data_plane_id": "000000-aaaa-bbbb-cccc-ddddddddd"
}

EXPLAIN Query

{
    "nql": "EXPLAIN SELECT company_data.\"8295\".\"hem_1\", 
company_data.\"8295\".\"ip_address\", 
company_data.\"8295\".\"maid\" FROM company_data.\"8295\" 
WHERE company_data.\"8295\".\"country_code\" = 
'US' AND company_data.\"8295\".\"age\" > 45",
    "data_plane_id": "000000-aaaa-bbbb-cccc-ddddddddd"
}

Response Structure

A successful request returns a status code of 201 Created and provides details about the executed job, including a unique job ID which can be used to track the execution status. The response includes metadata such as the query type, created timestamp, job state, and any compiled SQL queries. For EXPLAIN queries, the response may also provide forecasts for the number of rows in the output and the estimated cost.

Conclusion

Using the validate and run endpoints allows users to ensure their NQL queries are correctly formatted and ready for execution within the Narrative platform. The validate endpoint checks the syntax and structure, while the run endpoint executes the queries, creating materialized views or generating forecasts. Successful responses from these endpoints confirm that the queries are valid and executed, facilitating seamless data operations and workflow integration within the Narrative ecosystem.