Create a query
curl --request POST \
--url https://api-dev.narrative.io/v2/queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "query1",
"display_name": "Query One",
"tags": [
"tag1",
"tag2"
],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [
789
]
},
"view": {
"type": "all"
}
},
"ast": {
"parsed": {
"type": "select"
},
"compiled": "SELECT age FROM narrative.rosetta_stone",
"ast_metadata": {
"node_type": "multiple",
"version": "2"
}
}
}
'import requests
url = "https://api-dev.narrative.io/v2/queries"
payload = {
"name": "query1",
"display_name": "Query One",
"tags": ["tag1", "tag2"],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [789]
},
"view": { "type": "all" }
},
"ast": {
"parsed": { "type": "select" },
"compiled": "SELECT age FROM narrative.rosetta_stone",
"ast_metadata": {
"node_type": "multiple",
"version": "2"
}
}
}
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({
name: 'query1',
display_name: 'Query One',
tags: ['tag1', 'tag2'],
collaborators: {query: {type: 'inclusion', company_ids: [789]}, view: {type: 'all'}},
ast: {
parsed: {type: 'select'},
compiled: 'SELECT age FROM narrative.rosetta_stone',
ast_metadata: {node_type: 'multiple', version: '2'}
}
})
};
fetch('https://api-dev.narrative.io/v2/queries', 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/v2/queries",
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([
'name' => 'query1',
'display_name' => 'Query One',
'tags' => [
'tag1',
'tag2'
],
'collaborators' => [
'query' => [
'type' => 'inclusion',
'company_ids' => [
789
]
],
'view' => [
'type' => 'all'
]
],
'ast' => [
'parsed' => [
'type' => 'select'
],
'compiled' => 'SELECT age FROM narrative.rosetta_stone',
'ast_metadata' => [
'node_type' => 'multiple',
'version' => '2'
]
]
]),
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/v2/queries"
payload := strings.NewReader("{\n \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\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/v2/queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/v2/queries")
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 \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"name": "query1",
"id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
"display_name": "Query One",
"owner": {
"company_id": 456,
"company_name": "ExampleCorp",
"company_slug": "examplecorp"
},
"tags": [
"tag1",
"tag2"
],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [
789
]
},
"view": {
"type": "all"
}
},
"is_owned": true,
"metadata": {
"created_at": "2024-04-12T19:57:05.012908",
"created_by_user_id": 321,
"updated_at": "2024-04-12T20:03:48.031825",
"updated_by_user_id": 321
},
"ast": {
"type": "select",
"nql": "SELECT age FROM narrative.rosetta_stone",
"budget": null,
"columns": [
{
"type": "table",
"nql": "age",
"db": null,
"schema": null,
"table": "age"
}
],
"from": {
"type": "table",
"nql": "narrative.rosetta_stone",
"db": null,
"schema": "narrative",
"table": "rosetta_stone"
},
"group_by": [],
"having": null,
"is_distinct": false,
"limit": null,
"order_by": [],
"qualify": null,
"where": null,
"windows": [],
"with": []
}
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{}Queries
Create a query
Saves a query for the calling company. Needs a token that belongs to a user, since the user is recorded as the query’s creator; any other token is refused with a 401.
POST
/
v2
/
queries
Create a query
curl --request POST \
--url https://api-dev.narrative.io/v2/queries \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "query1",
"display_name": "Query One",
"tags": [
"tag1",
"tag2"
],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [
789
]
},
"view": {
"type": "all"
}
},
"ast": {
"parsed": {
"type": "select"
},
"compiled": "SELECT age FROM narrative.rosetta_stone",
"ast_metadata": {
"node_type": "multiple",
"version": "2"
}
}
}
'import requests
url = "https://api-dev.narrative.io/v2/queries"
payload = {
"name": "query1",
"display_name": "Query One",
"tags": ["tag1", "tag2"],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [789]
},
"view": { "type": "all" }
},
"ast": {
"parsed": { "type": "select" },
"compiled": "SELECT age FROM narrative.rosetta_stone",
"ast_metadata": {
"node_type": "multiple",
"version": "2"
}
}
}
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({
name: 'query1',
display_name: 'Query One',
tags: ['tag1', 'tag2'],
collaborators: {query: {type: 'inclusion', company_ids: [789]}, view: {type: 'all'}},
ast: {
parsed: {type: 'select'},
compiled: 'SELECT age FROM narrative.rosetta_stone',
ast_metadata: {node_type: 'multiple', version: '2'}
}
})
};
fetch('https://api-dev.narrative.io/v2/queries', 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/v2/queries",
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([
'name' => 'query1',
'display_name' => 'Query One',
'tags' => [
'tag1',
'tag2'
],
'collaborators' => [
'query' => [
'type' => 'inclusion',
'company_ids' => [
789
]
],
'view' => [
'type' => 'all'
]
],
'ast' => [
'parsed' => [
'type' => 'select'
],
'compiled' => 'SELECT age FROM narrative.rosetta_stone',
'ast_metadata' => [
'node_type' => 'multiple',
'version' => '2'
]
]
]),
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/v2/queries"
payload := strings.NewReader("{\n \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\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/v2/queries")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/v2/queries")
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 \"name\": \"query1\",\n \"display_name\": \"Query One\",\n \"tags\": [\n \"tag1\",\n \"tag2\"\n ],\n \"collaborators\": {\n \"query\": {\n \"type\": \"inclusion\",\n \"company_ids\": [\n 789\n ]\n },\n \"view\": {\n \"type\": \"all\"\n }\n },\n \"ast\": {\n \"parsed\": {\n \"type\": \"select\"\n },\n \"compiled\": \"SELECT age FROM narrative.rosetta_stone\",\n \"ast_metadata\": {\n \"node_type\": \"multiple\",\n \"version\": \"2\"\n }\n }\n}"
response = http.request(request)
puts response.read_body{
"name": "query1",
"id": "7409b999-2a9a-40cd-89dc-8430d85e0391",
"display_name": "Query One",
"owner": {
"company_id": 456,
"company_name": "ExampleCorp",
"company_slug": "examplecorp"
},
"tags": [
"tag1",
"tag2"
],
"collaborators": {
"query": {
"type": "inclusion",
"company_ids": [
789
]
},
"view": {
"type": "all"
}
},
"is_owned": true,
"metadata": {
"created_at": "2024-04-12T19:57:05.012908",
"created_by_user_id": 321,
"updated_at": "2024-04-12T20:03:48.031825",
"updated_by_user_id": 321
},
"ast": {
"type": "select",
"nql": "SELECT age FROM narrative.rosetta_stone",
"budget": null,
"columns": [
{
"type": "table",
"nql": "age",
"db": null,
"schema": null,
"table": "age"
}
],
"from": {
"type": "table",
"nql": "narrative.rosetta_stone",
"db": null,
"schema": "narrative",
"table": "rosetta_stone"
},
"group_by": [],
"having": null,
"is_distinct": false,
"limit": null,
"order_by": [],
"qualify": null,
"where": null,
"windows": [],
"with": []
}
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{
"error": "Unauthorized",
"error_description": "You are not authorized to use this endpoint."
}{}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
Unique among the owning company's queries. At most 256 characters, letters, digits and underscores only.
Maximum string length:
256Pattern:
^[a-zA-Z0-9_]+$Describes who can view or query a resource
Show child attributes
Show child attributes
The saved query body. The API stores the object exactly as it was sent and returns it unchanged. It does not validate the contents, so a reader has to cope with whatever an earlier client wrote. That is why the schema lists no fields.
The Narrative platform app writes an object with these fields, and older rows can lack any of them:
parsed: the parsed statement. Its shape is set byast_metadata.version. With no version it is the platform app's original parser output.compiled: the NQL text the statement was printed to when it was saved.ast_metadata: an object withnode_typeand, on rows written since versioning,version. Absent on some older rows.markdown,sourcesandplaceholdersWithContext: present on some rows.
Some rows instead hold a bare parsed statement at the top level (type, nql, columns, from and so on)
with none of these fields.
At most 999 characters, and not blank once surrounding whitespace is trimmed. Null when the query has none.
A human-friendly description of the query. Null when the query has none.
Each tag is between 1 and 255 characters. Omit the field for no tags; null is rejected.
Required string length:
1 - 255Response
OK
A query owned by the calling company.
Unique among the owning company's queries. At most 256 characters, letters, digits and underscores only.
Maximum string length:
256Pattern:
^[a-zA-Z0-9_]+$Each tag is between 1 and 255 characters.
Required string length:
1 - 255Describes who can view or query a resource
Show child attributes
Show child attributes
Information about the owner of the query
Show child attributes
Show child attributes
Available options:
true When and by whom the query was created and last updated.
Show child attributes
Show child attributes
The saved query body. The API stores the object exactly as it was sent and returns it unchanged. It does not validate the contents, so a reader has to cope with whatever an earlier client wrote. That is why the schema lists no fields.
The Narrative platform app writes an object with these fields, and older rows can lack any of them:
parsed: the parsed statement. Its shape is set byast_metadata.version. With no version it is the platform app's original parser output.compiled: the NQL text the statement was printed to when it was saved.ast_metadata: an object withnode_typeand, on rows written since versioning,version. Absent on some older rows.markdown,sourcesandplaceholdersWithContext: present on some rows.
Some rows instead hold a bare parsed statement at the top level (type, nql, columns, from and so on)
with none of these fields.
At most 999 characters, and not blank once surrounding whitespace is trimmed. Null when the query has none.
A human-friendly description of the query. Null when the query has none.
Was this page helpful?