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"
}

NQL

Run a NQL Query

deprecated

Deprecated. Use POST /v1/nql/execute instead — it returns a workflow and run id rather than a job. /nql/run continues to work; removal will be announced separately. See https://docs.narrative.io/reference/deprecations/nql-run

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 specified data plane. Depending on the NQL provided, the run endpoint can create materialized views or generate forecasts.

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 run on. 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).

Example:

"5c8f4a2e-3b1d-4f6a-9c7e-2d8b1a0f5e93"

create_as_view

boolean

default:false

When true, a CREATE MATERIALIZED VIEW statement creates a view over the query rather than a materialized table, so reads run the query instead of returning stored rows. Ignored for any other statement type, and not compatible with MERGE, DELTA, CHUNKING_STRATEGY, or PARTITIONED_BY.

Example:

false

Response

Created

Option 1
Option 2

A forecast job, started by an EXPLAIN statement.

string<uuid>

required

Unique identifier for the job.

company_id

integer<int64>

required

Company that ran the job.

Example:

345

created_at

string<date-time>

required

The timestamp representing when the job was created.

failures

object[]

required

causes of job failure

Show child attributes

idempotency_key

string

required

The unique ID associated with the job.

request_source

object

required

Who asked for the job. Discriminated by type: api_user for a job requested through the API on behalf of a user, process for one enqueued by a Narrative process.

Option 1
Option 2

Show child attributes

Example:

{
  "type": "api_user",
  "company_id": 1,
  "user_id": 1248
}

state

enum<string>

required

Where a job is in its lifecycle.

pending — enqueued and waiting to be picked up.
scheduled — claimed by an executor but not yet started.
running — being executed.
pending_cancellation — cancellation has been requested and the data plane has yet to stop the work.
completed, cancelled, failed — terminal states.

Available options:

pending,

scheduled,

running,

pending_cancellation,

completed,

cancelled,

failed

updated_at

string<date-time>

required

The timestamp representing when the job was updated.

input

object

required

The query and its compiled SQL as sent to the executor.

Show child attributes

completed_at

string<date-time> | null

When the job finished, or null while it is still pending or running.

result

object

The forecast once the job has completed, or the failure that ended it. Null while the job is pending or running.

Option 1
Option 2

Show child attributes