Schedule a job - Narrative I/O Knowledge Base

Schedule a job

curl --request POST \
  --url https://api-dev.narrative.io/jobs/{job_id}/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266"
}
'

import requests

url = "https://api-dev.narrative.io/jobs/{job_id}/schedule"

payload = { "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266" }
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({executor: 'job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266'})
};

fetch('https://api-dev.narrative.io/jobs/{job_id}/schedule', 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/jobs/{job_id}/schedule",
  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([
    'executor' => 'job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266'
  ]),
  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/jobs/{job_id}/schedule"

	payload := strings.NewReader("{\n  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\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/jobs/{job_id}/schedule")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/jobs/{job_id}/schedule")

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  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\n}"

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

{
  "job_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
  "company_id": 1,
  "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
  "compute_pool_id": null,
  "request_source": {
    "type": "api_user",
    "company_id": 1,
    "user_id": 407
  },
  "state": "completed",
  "type": "materialize-view",
  "operator_type": "materialized-view-refresh",
  "tags": [],
  "input": {
    "nql": "CREATE MATERIALIZED VIEW \"test_stats\" AS SELECT \"value\" FROM \"company_data\".\"10674\"",
    "compiled_select": "SELECT\n  `ds_10674`.`value`\nFROM\n  narrative.datasets.ds_10674 `ds_10674`",
    "create_as_view": null,
    "dataset_id": 10736,
    "billing_enabled": null,
    "stats_enabled": true,
    "contains_delta_syntax": null,
    "first_run": false,
    "merge": true,
    "partitions": null,
    "snowflake_create_table": null,
    "snowflake_insert_statement": null,
    "chunk_metadata": null,
    "nio_last_modified_at": null,
    "delta_dataset_bounds": null,
    "write_mode": "append"
  },
  "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266",
  "execution_cluster": "shared",
  "idempotency_key": "10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2",
  "result": {
    "dataset_id": 10736,
    "snapshot_id": 1724919539450264600,
    "recalculation_id": "abf9a2ec-426b-4751-bd16-fcb435061925",
    "row_stats": null
  },
  "dequeued_at": "2023-10-31T11:19:13.400498Z",
  "created_at": "2023-10-31T11:19:13.400498Z",
  "updated_at": "2023-10-31T11:25:08.327209Z",
  "attempted_at": "2023-10-31T11:19:13.400498Z",
  "attempt_version": 1,
  "ended_at": "2023-10-31T11:25:08.327194Z",
  "workflow_id": null,
  "workflow_run_id": null
}

{
  "error": "Unauthorized",
  "error_description": "You are not authorized to use this endpoint."
}

POST

jobs

{job_id}

schedule

Schedule a job

curl --request POST \
  --url https://api-dev.narrative.io/jobs/{job_id}/schedule \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266"
}
'

import requests

url = "https://api-dev.narrative.io/jobs/{job_id}/schedule"

payload = { "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266" }
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({executor: 'job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266'})
};

fetch('https://api-dev.narrative.io/jobs/{job_id}/schedule', 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/jobs/{job_id}/schedule",
  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([
    'executor' => 'job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266'
  ]),
  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/jobs/{job_id}/schedule"

	payload := strings.NewReader("{\n  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\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/jobs/{job_id}/schedule")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-dev.narrative.io/jobs/{job_id}/schedule")

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  \"executor\": \"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266\"\n}"

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

{
  "job_id": "2a5b9ad7-dc8f-47bb-8e62-843a38f8054c",
  "company_id": 1,
  "data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
  "compute_pool_id": null,
  "request_source": {
    "type": "api_user",
    "company_id": 1,
    "user_id": 407
  },
  "state": "completed",
  "type": "materialize-view",
  "operator_type": "materialized-view-refresh",
  "tags": [],
  "input": {
    "nql": "CREATE MATERIALIZED VIEW \"test_stats\" AS SELECT \"value\" FROM \"company_data\".\"10674\"",
    "compiled_select": "SELECT\n  `ds_10674`.`value`\nFROM\n  narrative.datasets.ds_10674 `ds_10674`",
    "create_as_view": null,
    "dataset_id": 10736,
    "billing_enabled": null,
    "stats_enabled": true,
    "contains_delta_syntax": null,
    "first_run": false,
    "merge": true,
    "partitions": null,
    "snowflake_create_table": null,
    "snowflake_insert_statement": null,
    "chunk_metadata": null,
    "nio_last_modified_at": null,
    "delta_dataset_bounds": null,
    "write_mode": "append"
  },
  "executor": "job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266",
  "execution_cluster": "shared",
  "idempotency_key": "10736:29329c64e7b8a4eda86aaabe04872b832ab456b5543d0c259c812525391f158c:669a5f8e4f373c2f907700decde47511aac6470f5698e2b856fb07f09160e5f2",
  "result": {
    "dataset_id": 10736,
    "snapshot_id": 1724919539450264600,
    "recalculation_id": "abf9a2ec-426b-4751-bd16-fcb435061925",
    "row_stats": null
  },
  "dequeued_at": "2023-10-31T11:19:13.400498Z",
  "created_at": "2023-10-31T11:19:13.400498Z",
  "updated_at": "2023-10-31T11:25:08.327209Z",
  "attempted_at": "2023-10-31T11:19:13.400498Z",
  "attempt_version": 1,
  "ended_at": "2023-10-31T11:25:08.327194Z",
  "workflow_id": null,
  "workflow_run_id": null
}

{
  "error": "Unauthorized",
  "error_description": "You are not authorized to use this endpoint."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

job_id

string<uuid>

required

Unique identifier for a job.

Body

application/json

Records which executor has claimed a pending job and moves it to scheduled.

executor

string

required

Identifier of a job executor. Non-blank, at most 255 characters.

Required string length: 1 - 255

Example:

"job-executor-98e1f48e-bf54-4f11-bbd1-73c445120266"

Response

A job. Every job carries the same envelope of fields — see JobBase — but input and result hold job-type-specific payloads, so the response is a union over type: pick the branch whose type matches and you get the typed input and result for that kind of job.

The union is open on purpose. Job types are free strings on the server, so a type this spec version does not describe lands in OtherJobResponse, where both fields stay free-form. No branch closes itself to extra properties, and new job types can appear without a spec change.

input and result are returned exactly as they were stored when the job was enqueued or completed. The server never reshapes them, so a field a job type gained after a row was written is absent from that row rather than null. The typed branches describe what the current code writes; fields that have not always been written are left out of each branch's required list.

result is null in every branch until the job reaches a terminal state.

job_id

string<uuid>

required

Unique identifier for the job.

company_id

integer<int64>

required

The company the job belongs to.

request_source

object

required

Who asked for the job. Discriminated by type: api_user for a job requested through the API on behalf of a user, process for one enqueued by a Narrative process.

Option 1
Option 2

Show child attributes

Example:

{
  "type": "api_user",
  "company_id": 1,
  "user_id": 1248
}

state

enum<string>

required

Where a job is in its lifecycle.

pending — enqueued and waiting to be picked up.
scheduled — claimed by an executor but not yet started.
running — being executed.
pending_cancellation — cancellation has been requested and the data plane has yet to stop the work.
completed, cancelled, failed — terminal states.

Available options:

pending,

scheduled,

running,

pending_cancellation,

completed,

cancelled,

failed

operator_type

string

required

Which operator runs the job, e.g. materialized-view-refresh or datasets_execute_select. Finer-grained than type: several job types can share one operator, and where no such mapping exists the two are equal.