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\""
}
'
{
  "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.

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