Parse an NQL statement

curl --request POST \
  --url https://api-dev.narrative.io/nql/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "nql": "EXPLAIN SELECT \"company_data\".\"1\".s, \"company_data\".\"1\".arr FROM \"company_data\".\"1\" WHERE \"company_data\".\"1\".x > -10.0"
}
'

import requests

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

payload = { "nql": "EXPLAIN SELECT \"company_data\".\"1\".s, \"company_data\".\"1\".arr FROM \"company_data\".\"1\" WHERE \"company_data\".\"1\".x > -10.0" }
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: 'EXPLAIN SELECT "company_data"."1".s, "company_data"."1".arr FROM "company_data"."1" WHERE "company_data"."1".x > -10.0'
  })
};

fetch('https://api-dev.narrative.io/nql/parse', 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/parse",
  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' => 'EXPLAIN SELECT "company_data"."1".s, "company_data"."1".arr FROM "company_data"."1" WHERE "company_data"."1".x > -10.0'
  ]),
  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/parse"

	payload := strings.NewReader("{\n  \"nql\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\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/parse")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"nql\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\n}"

response = http.request(request)
puts response.read_body

{
  "type": "agg_function",
  "nql": "<string>",
  "args": "<array>",
  "name": "<string>",
  "as": "<string>",
  "quantifier": "all"
}

{
  "type": null,
  "title": "Cannot validate certain queries when unauthentified",
  "status": 400,
  "detail": "cannot create a materialized view if not authenticated",
  "instance": "/nql/parse",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

{
  "type": null,
  "title": "Failed to Parse Query",
  "status": 400,
  "detail": "Invalid query format.",
  "instance": "/nql/validate",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

{
  "type": null,
  "title": "Failed to Parse Query",
  "status": 400,
  "detail": "Invalid query format.",
  "instance": "/nql/validate",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

NQL

Parse an NQL statement

The same check as POST /nql/validate, open to any token and to callers with no token at all, so a query editor can report problems as the user types. The response and error shapes are those of /nql/validate.

With a bearer token the statement is checked against the datasets, access rules and views of the token’s company, exactly as /nql/validate does, and the token needs no particular permission.

Without a token there is no company context. The statement is still parsed with the dialect of the given data plane and type-checked, but it can only resolve tables that need no company, such as narrative.rosetta_stone, and statements that write data (CREATE MATERIALIZED VIEW, INSERT, UPDATE, DELETE, MERGE) are rejected with a 400 titled Cannot validate certain queries when unauthentified.

POST

nql

parse

Parse an NQL statement

curl --request POST \
  --url https://api-dev.narrative.io/nql/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "nql": "EXPLAIN SELECT \"company_data\".\"1\".s, \"company_data\".\"1\".arr FROM \"company_data\".\"1\" WHERE \"company_data\".\"1\".x > -10.0"
}
'

import requests

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

payload = { "nql": "EXPLAIN SELECT \"company_data\".\"1\".s, \"company_data\".\"1\".arr FROM \"company_data\".\"1\" WHERE \"company_data\".\"1\".x > -10.0" }
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: 'EXPLAIN SELECT "company_data"."1".s, "company_data"."1".arr FROM "company_data"."1" WHERE "company_data"."1".x > -10.0'
  })
};

fetch('https://api-dev.narrative.io/nql/parse', 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/parse",
  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' => 'EXPLAIN SELECT "company_data"."1".s, "company_data"."1".arr FROM "company_data"."1" WHERE "company_data"."1".x > -10.0'
  ]),
  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/parse"

	payload := strings.NewReader("{\n  \"nql\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\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/parse")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"nql\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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\": \"EXPLAIN SELECT \\\"company_data\\\".\\\"1\\\".s, \\\"company_data\\\".\\\"1\\\".arr FROM \\\"company_data\\\".\\\"1\\\" WHERE \\\"company_data\\\".\\\"1\\\".x > -10.0\"\n}"

response = http.request(request)
puts response.read_body

{
  "type": "agg_function",
  "nql": "<string>",
  "args": "<array>",
  "name": "<string>",
  "as": "<string>",
  "quantifier": "all"
}

{
  "type": null,
  "title": "Cannot validate certain queries when unauthentified",
  "status": 400,
  "detail": "cannot create a materialized view if not authenticated",
  "instance": "/nql/parse",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

{
  "type": null,
  "title": "Failed to Parse Query",
  "status": 400,
  "detail": "Invalid query format.",
  "instance": "/nql/validate",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

{
  "type": null,
  "title": "Failed to Parse Query",
  "status": 400,
  "detail": "Invalid query format.",
  "instance": "/nql/validate",
  "log_id": "c06fea02-0950-45c6-aaff-07ab07c0d04c",
  "debug": null
}

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

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.

Response

The statement is valid. The body is its AST, or an empty object for a MERGE statement, which has no AST representation. See POST /nql/validate for worked examples.

The parsed statement as an AST. A MERGE statement has no AST representation and returns an empty object instead, as does a statement whose AST could not be serialized.

type

string

required

Allowed value: "agg_function"

nql

string

required

The text of the query fragment this node was parsed from.

args

array

required

name

string

required

The function name as written, for example SUM or COUNT.

string

The alias given with AS. Only present on aliased nodes: select-list expressions, FROM items and common table expressions. When it is present the node's nql is the full <expression> AS <alias> text.

quantifier

enum<string> | null

The ALL or DISTINCT quantifier, or null when none was written.

Available options:

all,

distinct,

null