Engine Rules
Engine rules are used to route jobs to a specific engine. For more information on the types of rules that are supported, see the engine routing topic.
Engine Rules Object{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "Reflections",
"condition": "query_type() = 'Reflections'",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}
Engine Rules Attributes
ruleSet
object
The set of rules applicable to a project.
object
Provides a list of all the rules in the project.
object
The default rule that is automatically generated when a project and its default execution engine are created. Jobs that do not have an applicable rule will default to this rule.
Warning: Since ruleInfoDefault is the default rule, it cannot be deleted.
tag
String
This tag routes JDBC queries to a particular session. When the JDBC connection property ROUTING_TAG = is set, the specified tag value is associated with all queries executed within that connection’s session.
Example fdbc007c-6994-41c7-a578-e7bd0150d31
ruleInfoDefault
name
String
The user-defined name for the default rule.
Example All Other Queries
condition
String
The routing condition for the rule. You can use SQL syntax to create this condition.
For more information, read Engine Routing.
Example query_type() = 'Reflections'
engineName
String
The name of the engine that jobs will be routed to.
Example default-engine
action
String
The rule type. When a query is routed to a particular engine, the value will be ROUTE. When a query is rejected, the value will be REJECT.
EnumROUTE, REJECT
Example ROUTE
rejectMessage
String
The message displayed to the user if the rule rejects jobs.
Example REST API jobs are rejected.
ruleInfos
Individual Rule Object
name
String
The user-defined name for the rule.
Example UI Previews
condition
String
The routing condition for the rule. You can use SQL syntax to create this condition.
For more information, read Engine Routing.
Example query_type() = 'UI Preview'
engineName
String
The name of the engine that jobs will be routed to.
Example preview
action
String
The rule type. When a query is routed to a particular engine, the value will be ROUTE. When a query is rejected, the value will be REJECT.
EnumROUTE, REJECT
Example ROUTE
rejectMessage
String
The message displayed to the user if the rule rejects jobs.
Example This job has been rejected because we no longer use ODBC.
Listing All Rules
Returns a list of all the rules in a project and the metadata for each rule.
Listing All RulesGET /v0/projects/{project-id}/rules
Parameters
project-id
path
String (UUID)
Unique identifier of the project that you want to list rules for.
curl -X GET 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/rules' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "Reflections",
"condition": "query_type() = 'Reflections'",
"engineName": "firstEngine",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "test-rule",
"condition": "query_type() IN ('UI Run')",
"engineName": "test-engine",
"action": "ROUTE",
"rejectMessage": ""
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "firstEngine",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": "",
}
}
Responses
200
OK
401
Unauthorized
404
Not found
Adding a Rule
Add a rule.
When adding a rule, include the existing rules that you want to retain in the request, otherwise they will be deleted.
PUT /v0/projects/{project-id}/rules
Parameters
project-id
path
String (UUID)
Unique identifier of the project that you want to list rules for.
name
body
String
The user-defined name for the rule.
condition
body
String
The routing condition for the rule. You can use SQL syntax to create this condition.
For more information, read Engine Routing.
action
body
String
The rule type. When a query is routed to a particular engine, the value will be ROUTE. When a query is rejected, the value will be REJECT.
EnumROUTE, REJECT
rejectMessage
body
String
The message displayed to the user if the rule rejects jobs. This parameter is required but can be left empty when action is REJECT. You can also leave this attribute empty if action is ROUTE.
engineName
body
String
The name of the engine where the jobs will be routed to. When action is REJECT, leave this parameter empty.
tag
body
String
This tag is a form of concurrency control to avoid lost updates to the rule. This tag routes JDBC queries to a particular session. When the JDBC connection property ROUTING_TAG = is set, the specified tag value is associated with all queries executed within that connection’s session.
curl -X PUT 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/rules' \
-H 'Authorization: Bearer <personal access token>' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "add-new-rule",
"condition": "query_type() IN ('UI Run')",
"engineName": "test-engine",
"action": "ROUTE",
"rejectMessage": ""
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}
{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "add-new-rule",
"condition": "query_type() IN ('UI Run')",
"engineName": "test-engine",
"action": "ROUTE",
"rejectMessage": "",
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}'
Responses
200
OK
401
Unauthorized
404
Not found
415
Unsupported Media Type
Modifying a Rule
Modify a rule.
Modifying a RulePUT /v0/projects/{project-id}/rules
Parameters
project-id
path
String (UUID)
Unique identifier of the project that you want to list rules for.
name
body
String
The user-defined name for the rule.
condition
body
String
The routing condition for the rule. You can use SQL syntax to create this condition.
For more information, read Engine Routing.
engineName
body
String
The name of the engine that jobs will be routed to. When action is REJECT, leave this parameter empty.
Example preview
action
body
String
The rule type. When a query is routed to a particular engine, the value will be ROUTE. When a query is rejected, the value will be REJECT.
EnumROUTE, REJECT
Example ROUTE
rejectMessage
body
String
The message displayed to the user if the rule rejects jobs. This parameter is required but can be left empty when action is REJECT. You can also leave this attribute empty if action is ROUTE.
tag
body
String
This tag is a form of concurrency control to avoid lost updates to the rule. This tag routes JDBC queries to a particular session. When the JDBC connection property ROUTING_TAG = is set, the specified tag value is associated with all queries executed within that connection’s session.
curl -X PUT 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/rules'\
-H 'Authorization: Bearer <personal access token>' \
-H "Content-Type:application/json" \
-H "Accept: application/json"
-d '{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "modify-a-rule",
"condition": "query_type() IN ('UI Run', 'JDBC')",
"engineName": "test-engine",
"action": "ROUTE",
"rejectMessage": ""
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}'
{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
{
"name": "modify-a-rule",
"condition": "query_type() IN ('UI Run', 'JDBC')",
"engineName": "test-engine",
"action": "ROUTE",
"rejectMessage": ""
}
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}
Responses
200
OK
400
Bad Request
401
Unauthorized
404
Not found
415
Unsupported Media Type
Deleting a Rule
To delete a rule, you can use the PUT command to update the list of rules by omitting the rule that you want removed.
Since ruleInfoDefault is the default rule, it cannot be deleted.
PUT /v0/projects/{project-id}/rules
Parameters
project-id
path
String (UUID)
Unique identifier of the project that you want to delete rules for.
curl -X PUT 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/rules'\
-H 'Authorization: Bearer <personal access token>' \
-H "Content-Type:application/json" \
-H "Accept: application/json"
-d '{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}'
{
"ruleSet": {
"ruleInfos": [
{
"name": "UI Previews",
"condition": "query_type() = 'UI Preview'",
"engineName": "preview",
"action": "ROUTE",
"rejectMessage": ""
},
],
"ruleInfoDefault": {
"name": "All Other Queries",
"condition": "",
"engineName": "default",
"action": "ROUTE",
"rejectMessage": ""
},
"tag": ""
}
}
Responses
200
OK
400
Bad Request
401
Unauthorized
404
Not found