Skip to main content
POST
/
nql
/
run
Run a NQL Query
curl --request POST \
  --url https://api-dev.narrative.io/nql/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "nql": "CREATE MATERIALIZED VIEW \"dataset_name\" AS SELECT \"company_data\".\"1\".x AS xx, \"company_data\".\"1\".y AS yy, \"company_data\".\"1\".z AS zz, \"company_data\".\"1\".x + \"company_data\".\"1\".y + \"company_data\".\"1\".z AS xyz_sum FROM \"company_data\".\"1\""
}
'
import requests

url = "https://api-dev.narrative.io/nql/run"

payload = { "nql": "CREATE MATERIALIZED VIEW \"dataset_name\" AS SELECT \"company_data\".\"1\".x AS xx, \"company_data\".\"1\".y AS yy, \"company_data\".\"1\".z AS zz, \"company_data\".\"1\".x + \"company_data\".\"1\".y + \"company_data\".\"1\".z AS xyz_sum FROM \"company_data\".\"1\"" }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    nql: 'CREATE MATERIALIZED VIEW "dataset_name" AS SELECT "company_data"."1".x AS xx, "company_data"."1".y AS yy, "company_data"."1".z AS zz, "company_data"."1".x + "company_data"."1".y + "company_data"."1".z AS xyz_sum FROM "company_data"."1"'
  })
};

fetch('https://api-dev.narrative.io/nql/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-dev.narrative.io/nql/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'nql' => 'CREATE MATERIALIZED VIEW "dataset_name" AS SELECT "company_data"."1".x AS xx, "company_data"."1".y AS yy, "company_data"."1".z AS zz, "company_data"."1".x + "company_data"."1".y + "company_data"."1".z AS xyz_sum FROM "company_data"."1"'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-dev.narrative.io/nql/run"

	payload := strings.NewReader("{\n  \"nql\": \"CREATE MATERIALIZED VIEW \\\"dataset_name\\\" AS SELECT \\\"company_data\\\".\\\"1\\\".x AS xx, \\\"company_data\\\".\\\"1\\\".y AS yy, \\\"company_data\\\".\\\"1\\\".z AS zz, \\\"company_data\\\".\\\"1\\\".x + \\\"company_data\\\".\\\"1\\\".y + \\\"company_data\\\".\\\"1\\\".z AS xyz_sum FROM \\\"company_data\\\".\\\"1\\\"\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api-dev.narrative.io/nql/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"nql\": \"CREATE MATERIALIZED VIEW \\\"dataset_name\\\" AS SELECT \\\"company_data\\\".\\\"1\\\".x AS xx, \\\"company_data\\\".\\\"1\\\".y AS yy, \\\"company_data\\\".\\\"1\\\".z AS zz, \\\"company_data\\\".\\\"1\\\".x + \\\"company_data\\\".\\\"1\\\".y + \\\"company_data\\\".\\\"1\\\".z AS xyz_sum FROM \\\"company_data\\\".\\\"1\\\"\"\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/nql/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"nql\": \"CREATE MATERIALIZED VIEW \\\"dataset_name\\\" AS SELECT \\\"company_data\\\".\\\"1\\\".x AS xx, \\\"company_data\\\".\\\"1\\\".y AS yy, \\\"company_data\\\".\\\"1\\\".z AS zz, \\\"company_data\\\".\\\"1\\\".x + \\\"company_data\\\".\\\"1\\\".y + \\\"company_data\\\".\\\"1\\\".z AS xyz_sum FROM \\\"company_data\\\".\\\"1\\\"\"\n}"

response = http.request(request)
puts response.read_body
{
  "id": "7352a290-dea9-4932-b7d3-66723e145259",
  "company_id": 1,
  "completed_at": null,
  "created_at": "2025-04-14T17:33:24.941123Z",
  "failures": [],
  "idempotency_key": "3c7afdbb-1b2a-458b-a8bf-ac7b7942cb6c",
  "input": {
    "compiled_select": "SELECT\n  *\nFROM\n  (VALUES\n      (1, 2)) `t` (`a`, `b`)",
    "create_as_view": false,
    "dataset": {
      "id": 23499,
      "company_id": 1,
      "created_at": "2025-04-14T17:33:23.500965Z",
      "data_plane": {
        "type": "owned",
        "id": "f79cbdae-4848-47ca-95e8-69588364d185",
        "company_id": 1,
        "created_at": "2016-01-01T00:00:00Z",
        "description": "...",
        "display_name": "Narrative Data Collaboration Platform (us-east-1)",
        "external_id": "704349335716",
        "platform": {
          "type": "platform_aws",
          "account_id": "704349335716",
          "region": {
            "type": "region_aws",
            "id": "us-east-1"
          }
        },
        "status": "active",
        "updated_at": "2024-01-12T00:00:00Z",
        "collaborators": {
          "participants": {
            "type": "all"
          }
        }
      },
      "display_name": "test_gui",
      "is_narrative_managed": true,
      "materialized_view_config": {
        "nql": "SELECT 1 AS a, 2 AS b"
      },
      "name": "test_gui",
      "retention_policy": {
        "type": "retain_everything"
      },
      "schema": {
        "file_config": {
          "type": "json"
        },
        "type": "object",
        "properties": {
          "a": {
            "display_name": "a",
            "type": "long"
          },
          "b": {
            "display_name": "b",
            "type": "long"
          }
        }
      },
      "status": "pending",
      "tags": [
        "_nio_materialized_view"
      ],
      "updated_at": "2025-04-14T17:33:23.500965Z",
      "write_mode": "append"
    },
    "nql": "SELECT 1 AS a, 2 AS b"
  },
  "request_source": {
    "type": "api_user",
    "company_id": 1,
    "user_id": 1414
  },
  "result": null,
  "state": "pending",
  "updated_at": "2025-04-14T17:33:24.941123Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
nql
string
required

A NQL query.

​
data_plane_id
string<uuid>

A dataplane represent where you would run the query. Your query get compiled to the SQL dialect that your data engine understands. If you leave it blank, your query will target Narrative's dataplane on AWS using Apache Spark. We currently support Snowflake and we plan to support other dataplanes in the future. See https://next.narrative.io/products/narrative-anywhere for more details.

​
compute_pool_id
string<uuid>

The ID of the compute pool to use for running this query. The compute pool must be active, belong to your company, and be associated with the target data plane. If not specified, the default compute pool for the data plane will be used (if one is configured).

Response

Created

​
id
string<uuid>
required

Unique identifier for the job.

​
company_id
string<uuid>
required

Company that ran the job.

​
completed_at
string<date-time>
required

The timestamp representing when the job finished.

​
created_at
string<date-time>
required

The timestamp representing when the job was created.

​
failures
object[]
required

causes of job failure

​
idempotency_key
string
required

The unique ID associated with the job.

​
request_source
object
required
Example:
{
  "type": "api_user",
  "company_id": 1,
  "user_id": 1248
}
​
state
enum<string>
default:pending
required
Available options:
failed,
cancelled,
completed,
pending,
pending_cancellation,
running
​
updated_at
string<date-time>
required

The timestamp representing when the job was updated.

​
input
object
required

The query and it's compiled sql sent to the executor.

​
result
object