Simulate an NQL query against access rules
curl --request POST \
--url https://api-dev.narrative.io/v2/nql/simulate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"nql": "SELECT r.\"email\" FROM acme.\"draft_rule\" r JOIN company_data.\"2001\" c ON r.\"email\" = c.\"email\"",
"data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
"context": {
"access_rules": [
{
"access_rule_id": 4211,
"placeholder_owner_slug": "seller"
},
{
"access_rule_id": 4212,
"placeholder_owner_slug": "acme"
},
{
"access_rule": {
"name": "draft_rule",
"nql": "SELECT t.\"email\" FROM company_data.\"11370\" t",
"query_policy": {
"default": {
"projection": {
"mode": "allow"
}
}
}
},
"placeholder_owner_slug": "acme"
}
]
}
}
'import requests
url = "https://api-dev.narrative.io/v2/nql/simulate"
payload = {
"nql": "SELECT r.\"email\" FROM acme.\"draft_rule\" r JOIN company_data.\"2001\" c ON r.\"email\" = c.\"email\"",
"data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
"context": { "access_rules": [
{
"access_rule_id": 4211,
"placeholder_owner_slug": "seller"
},
{
"access_rule_id": 4212,
"placeholder_owner_slug": "acme"
},
{
"access_rule": {
"name": "draft_rule",
"nql": "SELECT t.\"email\" FROM company_data.\"11370\" t",
"query_policy": { "default": { "projection": { "mode": "allow" } } }
},
"placeholder_owner_slug": "acme"
}
] }
}
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({
nql: 'SELECT r."email" FROM acme."draft_rule" r JOIN company_data."2001" c ON r."email" = c."email"',
data_plane_id: 'f79cbdae-4848-47ca-95e8-69588364d185',
context: {
access_rules: [
{access_rule_id: 4211, placeholder_owner_slug: 'seller'},
{access_rule_id: 4212, placeholder_owner_slug: 'acme'},
{
access_rule: {
name: 'draft_rule',
nql: 'SELECT t."email" FROM company_data."11370" t',
query_policy: {default: {projection: {mode: 'allow'}}}
},
placeholder_owner_slug: 'acme'
}
]
}
})
};
fetch('https://api-dev.narrative.io/v2/nql/simulate', 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/nql/simulate",
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([
'nql' => 'SELECT r."email" FROM acme."draft_rule" r JOIN company_data."2001" c ON r."email" = c."email"',
'data_plane_id' => 'f79cbdae-4848-47ca-95e8-69588364d185',
'context' => [
'access_rules' => [
[
'access_rule_id' => 4211,
'placeholder_owner_slug' => 'seller'
],
[
'access_rule_id' => 4212,
'placeholder_owner_slug' => 'acme'
],
[
'access_rule' => [
'name' => 'draft_rule',
'nql' => 'SELECT t."email" FROM company_data."11370" t',
'query_policy' => [
'default' => [
'projection' => [
'mode' => 'allow'
]
]
]
],
'placeholder_owner_slug' => 'acme'
]
]
]
]),
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/nql/simulate"
payload := strings.NewReader("{\n \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\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/nql/simulate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/v2/nql/simulate")
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 \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"denied_access_rules": [
{
"index": 0,
"access_rule_id": 4211,
"query_table": "narrative.rosetta_stone",
"violations": [
{
"type": "join_required",
"required_join_keys": [
[
{
"attribute": "email",
"form": "raw"
}
]
],
"reason": "The query must join this access rule with your company's data on one of the keys its policy requires."
}
]
},
{
"index": 2,
"access_rule_name": "draft_rule",
"query_table": "acme.draft_rule",
"violations": [
{
"type": "field_usage",
"field": "email",
"usage": "projection",
"reason": "Field email cannot be selected."
},
{
"type": "field_usage",
"field": "phone",
"usage": "projection",
"operator": "sha256",
"reason": "Field phone can be selected only through a listed operator, and sha256 is not listed."
}
]
}
]
}NQL
Simulate an NQL query against access rules
Check which of a chosen set of access rules would deny a SELECT or MERGE statement, without running
it. Nothing is stored and no data is read: no job is created and no credits are charged.
The statement runs as the caller’s company, in the role of a buyer, against the listed access rules
only. An entry is a stored access rule that the caller’s company owns or can query, or an inline access
rule defined in the request. Each access rule moves, with the datasets it reads, to a placeholder company
named by its placeholder_owner_slug, and the statement reads it as
<placeholder_owner_slug>.<access_rule_name> or through narrative.rosetta_stone. The placeholder
company exists only for this request. Its slug can be the slug of a real company, such as the access
rule’s real owner, and that company’s data is never involved.
The statement reads the caller’s own active datasets only through company_data: by id, by name, or all
of them through company_data.rosetta_stone. The caller’s own slug is not a namespace in a simulation.
Views and derived mappings are not available, and opt-out datasets and dataset statistics are not loaded.
Query policies are evaluated before opt-out and sampling would apply, so neither changes which access
rules are denied. The policies are checked by the same query policy evaluation a normal query goes
through.
The response lists, per access rule and query table, the violations that denied it. A listed access rule that is not in the list was not denied: its policy allowed the statement, or the statement did not read it.
Requires a token with read access to subscriptions.
POST
/
v2
/
nql
/
simulate
Simulate an NQL query against access rules
curl --request POST \
--url https://api-dev.narrative.io/v2/nql/simulate \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"nql": "SELECT r.\"email\" FROM acme.\"draft_rule\" r JOIN company_data.\"2001\" c ON r.\"email\" = c.\"email\"",
"data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
"context": {
"access_rules": [
{
"access_rule_id": 4211,
"placeholder_owner_slug": "seller"
},
{
"access_rule_id": 4212,
"placeholder_owner_slug": "acme"
},
{
"access_rule": {
"name": "draft_rule",
"nql": "SELECT t.\"email\" FROM company_data.\"11370\" t",
"query_policy": {
"default": {
"projection": {
"mode": "allow"
}
}
}
},
"placeholder_owner_slug": "acme"
}
]
}
}
'import requests
url = "https://api-dev.narrative.io/v2/nql/simulate"
payload = {
"nql": "SELECT r.\"email\" FROM acme.\"draft_rule\" r JOIN company_data.\"2001\" c ON r.\"email\" = c.\"email\"",
"data_plane_id": "f79cbdae-4848-47ca-95e8-69588364d185",
"context": { "access_rules": [
{
"access_rule_id": 4211,
"placeholder_owner_slug": "seller"
},
{
"access_rule_id": 4212,
"placeholder_owner_slug": "acme"
},
{
"access_rule": {
"name": "draft_rule",
"nql": "SELECT t.\"email\" FROM company_data.\"11370\" t",
"query_policy": { "default": { "projection": { "mode": "allow" } } }
},
"placeholder_owner_slug": "acme"
}
] }
}
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({
nql: 'SELECT r."email" FROM acme."draft_rule" r JOIN company_data."2001" c ON r."email" = c."email"',
data_plane_id: 'f79cbdae-4848-47ca-95e8-69588364d185',
context: {
access_rules: [
{access_rule_id: 4211, placeholder_owner_slug: 'seller'},
{access_rule_id: 4212, placeholder_owner_slug: 'acme'},
{
access_rule: {
name: 'draft_rule',
nql: 'SELECT t."email" FROM company_data."11370" t',
query_policy: {default: {projection: {mode: 'allow'}}}
},
placeholder_owner_slug: 'acme'
}
]
}
})
};
fetch('https://api-dev.narrative.io/v2/nql/simulate', 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/nql/simulate",
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([
'nql' => 'SELECT r."email" FROM acme."draft_rule" r JOIN company_data."2001" c ON r."email" = c."email"',
'data_plane_id' => 'f79cbdae-4848-47ca-95e8-69588364d185',
'context' => [
'access_rules' => [
[
'access_rule_id' => 4211,
'placeholder_owner_slug' => 'seller'
],
[
'access_rule_id' => 4212,
'placeholder_owner_slug' => 'acme'
],
[
'access_rule' => [
'name' => 'draft_rule',
'nql' => 'SELECT t."email" FROM company_data."11370" t',
'query_policy' => [
'default' => [
'projection' => [
'mode' => 'allow'
]
]
]
],
'placeholder_owner_slug' => 'acme'
]
]
]
]),
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/nql/simulate"
payload := strings.NewReader("{\n \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\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/nql/simulate")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api-dev.narrative.io/v2/nql/simulate")
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 \"nql\": \"SELECT r.\\\"email\\\" FROM acme.\\\"draft_rule\\\" r JOIN company_data.\\\"2001\\\" c ON r.\\\"email\\\" = c.\\\"email\\\"\",\n \"data_plane_id\": \"f79cbdae-4848-47ca-95e8-69588364d185\",\n \"context\": {\n \"access_rules\": [\n {\n \"access_rule_id\": 4211,\n \"placeholder_owner_slug\": \"seller\"\n },\n {\n \"access_rule_id\": 4212,\n \"placeholder_owner_slug\": \"acme\"\n },\n {\n \"access_rule\": {\n \"name\": \"draft_rule\",\n \"nql\": \"SELECT t.\\\"email\\\" FROM company_data.\\\"11370\\\" t\",\n \"query_policy\": {\n \"default\": {\n \"projection\": {\n \"mode\": \"allow\"\n }\n }\n }\n },\n \"placeholder_owner_slug\": \"acme\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"denied_access_rules": [
{
"index": 0,
"access_rule_id": 4211,
"query_table": "narrative.rosetta_stone",
"violations": [
{
"type": "join_required",
"required_join_keys": [
[
{
"attribute": "email",
"form": "raw"
}
]
],
"reason": "The query must join this access rule with your company's data on one of the keys its policy requires."
}
]
},
{
"index": 2,
"access_rule_name": "draft_rule",
"query_table": "acme.draft_rule",
"violations": [
{
"type": "field_usage",
"field": "email",
"usage": "projection",
"reason": "Field email cannot be selected."
},
{
"type": "field_usage",
"field": "phone",
"usage": "projection",
"operator": "sha256",
"reason": "Field phone can be selected only through a listed operator, and sha256 is not listed."
}
]
}
]
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
application/json
The statement to check: a SELECT, including WITH and UNION selects, or a MERGE into one of the
caller's datasets. INSERT, UPDATE and DELETE cannot read access rules, so they, CREATE MATERIALIZED VIEW and EXPLAIN return 422.
The statement runs as the caller's company, in the role of a buyer. It reads a listed access rule as
<placeholder_owner_slug>.<access_rule_name>, or through narrative.rosetta_stone. It reads the
caller's own datasets only through company_data: by id, by name, or through
company_data.rosetta_stone. The caller's own slug is not a namespace in a simulation.
The data plane the statement is compiled for. Every listed access rule, stored or inline, must be on this data plane, and the statement reads the caller's datasets only from it.
The access rules the statement runs against. Apart from the caller's own datasets, the statement sees only these access rules.
Show child attributes
Show child attributes
Response
The statement compiled. denied_access_rules can be empty, which means no listed access rule denied the
statement. A listed access rule that is not in denied_access_rules was not denied by its policy: it allowed
the query or no table in the query reached it.
The access rules whose query policy denied the statement. A listed access rule that is not in
denied_access_rules was not denied: its policy allowed the statement, or the statement did not read it.
One entry per access rule and query table it was denied on, in the order of context.access_rules.
When the statement reads the same table more than once, such as in a self-join, each read that is
denied has its own entry.
An access rule denied on one query table. Set access_rule_id for a stored access rule and
access_rule_name for an inline one.
- Option 1
- Option 2
Show child attributes
Show child attributes