curl --request POST \
  --url https://api-dev.narrative.io/nql/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "nql": "select\n  \"company_data\".\"1\".s,\n  \"company_data\".\"1\".x as xx\nfrom \"company_data\".\"1\"\nwhere \"company_data\".\"1\".x > 0"
}
'

{
  "type": "select",
  "nql": "SELECT \"1\".s, \"1\".x AS xx FROM \"company_data\".\"1\" AS 1 WHERE \"1\".x > CAST(0 AS DOUBLE)",
  "columns": [
    {
      "type": "column",
      "nql": "\"1\".s",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "s",
      "metadata": {
        "column_type": "column"
      }
    },
    {
      "as": "xx",
      "nql": "\"1\".x AS xx",
      "type": "column",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "x",
      "metadata": {
        "column_type": "column"
      }
    }
  ],
  "from": {
    "as": "1",
    "nql": "\"company_data\".\"1\" AS 1",
    "type": "table",
    "db": null,
    "schema": "company_data",
    "table": "1",
    "metadata": {
      "table_type": "dataset",
      "id": 1,
      "name": "dataset_name_1"
    }
  },
  "group_by": [],
  "having": null,
  "is_distinct": false,
  "limit": null,
  "order_by": [],
  "qualify": null,
  "where": {
    "type": "binary_op",
    "nql": "\"1\".x > CAST(0 AS DOUBLE)",
    "name": ">",
    "left": {
      "type": "column",
      "nql": "\"1\".x",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "x",
      "metadata": {
        "column_type": "column"
      }
    },
    "right": {
      "type": "literal",
      "nql": "0",
      "value_type": {
        "type": "double"
      },
      "value": "0"
    }
  },
  "windows": [],
  "with": []
}

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

curl --request POST \
  --url https://api-dev.narrative.io/nql/parse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "nql": "select\n  \"company_data\".\"1\".s,\n  \"company_data\".\"1\".x as xx\nfrom \"company_data\".\"1\"\nwhere \"company_data\".\"1\".x > 0"
}
'

{
  "type": "select",
  "nql": "SELECT \"1\".s, \"1\".x AS xx FROM \"company_data\".\"1\" AS 1 WHERE \"1\".x > CAST(0 AS DOUBLE)",
  "columns": [
    {
      "type": "column",
      "nql": "\"1\".s",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "s",
      "metadata": {
        "column_type": "column"
      }
    },
    {
      "as": "xx",
      "nql": "\"1\".x AS xx",
      "type": "column",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "x",
      "metadata": {
        "column_type": "column"
      }
    }
  ],
  "from": {
    "as": "1",
    "nql": "\"company_data\".\"1\" AS 1",
    "type": "table",
    "db": null,
    "schema": "company_data",
    "table": "1",
    "metadata": {
      "table_type": "dataset",
      "id": 1,
      "name": "dataset_name_1"
    }
  },
  "group_by": [],
  "having": null,
  "is_distinct": false,
  "limit": null,
  "order_by": [],
  "qualify": null,
  "where": {
    "type": "binary_op",
    "nql": "\"1\".x > CAST(0 AS DOUBLE)",
    "name": ">",
    "left": {
      "type": "column",
      "nql": "\"1\".x",
      "db": null,
      "schema": "company_data",
      "table": "1",
      "column": "x",
      "metadata": {
        "column_type": "column"
      }
    },
    "right": {
      "type": "literal",
      "nql": "0",
      "value_type": {
        "type": "double"
      },
      "value": "0"
    }
  },
  "windows": [],
  "with": []
}

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.

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: "select"

nql

string

required

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

columns

array

required

group_by

array

required

is_distinct

boolean

required

order_by

array

required

windows

array

required

Named windows declared in a WINDOW clause.

with

array

required

The common table expressions of a WITH clause. Each is a select node whose as is the CTE name.

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.

from

any | null

The FROM item, or null for a select with no FROM clause.

having

unknown

limit

unknown

qualify

unknown

where

unknown