Execute an NQL statement
The execute 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. The query runs as a workflow, and the response carries the ID of that workflow run.
Supported statements: INSERT, UPDATE, DELETE, EXPLAIN, and CREATE MATERIALIZED VIEW.
Set create_as_view to create a view rather than a materialized table; it applies only to
CREATE MATERIALIZED VIEW and is ignored for other statements.
Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A NQL query.
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.
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).
"5c8f4a2e-3b1d-4f6a-9c7e-2d8b1a0f5e93"
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.
false
Response
The created workflow and the id of the run started for it.
A created workflow whose run was started, so the run ID is always present.
Unique identifier for a workflow.
"a1b2c3d4-e5f6-7890-abcd-ef1234567890"
The name of the workflow, extracted from the specification.
"my-etl-workflow"
The workflow specification in YAML format.
"document:\n dsl: '1.0.0'\n namespace: test\n name: test-workflow\n version: '1.0.0'\n do:\n - createView:\n call: CreateMaterializedViewIfNotExists\n with:\n nql: \"CREATE MATERIALIZED VIEW workflow_output_dataset AS SELECT track_id FROM company_data.workflow_input_dataset\"\n - refreshView:\n call: RefreshMaterializedView\n with:\n datasetName: workflow_output_dataset\n - insertData:\n call: ExecuteDml\n with:\n nql: \"INSERT INTO company_data.workflow_input_dataset (track_id) VALUES ('test')\n"
The data plane this workflow is associated with.
"d1e2f3a4-b5c6-7890-abcd-ef1234567890"
The company that owns this workflow.
100
ISO-8601 timestamp of when the workflow was created.
"2025-01-15T10:30:00Z"
The ID of the user who created this workflow.
20
ISO-8601 timestamp of when the workflow was last updated.
"2025-01-15T10:30:00Z"
The current status of the workflow.
active, archived "active"
Tags that describe the workflow.
Workflow execution run ID.
"b7e3f1a2-4c5d-6e7f-8a9b-0c1d2e3f4a5b"
ISO-8601 timestamp of when the workflow was archived, or null if active.
null

