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 Rule 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 Rule 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, see Engine Routing Rules .
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.
Enum
ROUTE
,
REJECT
Example
ROUTE
rejectMessage
String
The message displayed to the user if the rule rejects jobs.
Example
REST API jobs are rejected.
ruleInfos
object
ruleInfos is a list of rules in the project.
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, see Engine Routing Rules .
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.
Enum
ROUTE
,
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.
important:
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
query
String
The user-defined name for the rule.
condition
query
String
The routing condition for the rule. You can use SQL syntax to create this condition. For more information, see Engine Routing Rules .
action
query
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.
Enum
ROUTE
,
REJECT
rejectMessage
query
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
query
String
The name of the engine where the jobs will be routed to. When action is REJECT, leave this parameter empty.
tag
query
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
query
String
The user-defined name for the rule.
condition
query
String
The routing condition for the rule. You can use SQL syntax to create this condition. For more information, see Engine Routing Rules .
engineName
query
String
The name of the engine that jobs will be routed to. When action is REJECT, leave this parameter empty.
Example
preview
action
query
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.
Enum
ROUTE
,
REJECT
Example
ROUTE
rejectMessage
query
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
query
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.
warning:
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