Skip to main content
POST
Execute an NQL statement

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

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.

id
string<uuid>
required

Unique identifier for a workflow.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

name
string
required

The name of the workflow, extracted from the specification.

Example:

"my-etl-workflow"

specification
string
required

The workflow specification in YAML format.

Example:

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

data_plane_id
string<uuid>
required

The data plane this workflow is associated with.

Example:

"d1e2f3a4-b5c6-7890-abcd-ef1234567890"

company_id
integer<int64>
required

The company that owns this workflow.

Example:

100

created_at
string<date-time>
required

ISO-8601 timestamp of when the workflow was created.

Example:

"2025-01-15T10:30:00Z"

created_by
integer<int64>
required

The ID of the user who created this workflow.

Example:

20

updated_at
string<date-time>
required

ISO-8601 timestamp of when the workflow was last updated.

Example:

"2025-01-15T10:30:00Z"

status
enum<string>
required

The current status of the workflow.

Available options:
active,
archived
Example:

"active"

tags
string[]
required

Tags that describe the workflow.

run_id
string
required

Workflow execution run ID.

Example:

"b7e3f1a2-4c5d-6e7f-8a9b-0c1d2e3f4a5b"

archived_at
string<date-time> | null

ISO-8601 timestamp of when the workflow was archived, or null if active.

Example:

null