Skip to main content

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.

Attributes of the ruleSet Object

ruleInfos Array of Object

Provides a list of all the rules in the project.


ruleInfoDefault 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. 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

Attributes of the ruleInfos 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. Read Engine Routing for more information.

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.

Attributes of the ruleInfoDefault Object

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. Read Engine Routing for more information.

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.

Example: ROUTE


rejectMessage String

The message displayed to the user if the rule rejects jobs.

Example: REST API jobs are rejected.

Listing All Rules

Returns a list of all the rules in a project and the metadata for each rule.

Listing All Rules
GET /v0/projects/{project-id}/rules

Parameters

project-id Path   String (UUID)

Unique identifier of the project that you want to list rules for.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6/rules

Example Request
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'
Example Response
{
"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

400   Bad Request

401   Unauthorized

Adding a Rule

Add a rule.

note

When adding a rule, include the existing rules that you want to retain in the request, otherwise they will be deleted.

Adding a Rule
PUT /v0/projects/{project-id}/rules

Parameters

project-id Path   String (UUID)

Unique identifier of the project that you want to list rules for.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6


name Body   String

The user-defined name for the rule.

Example: UI Previews


condition Body   String

The routing condition for the rule. You can use SQL syntax to create this condition. Read Engine Routing for more information.

Example: query_type() = 'UI 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.

Enum: ROUTE, 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.

Example: preview


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.

Example Request
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": ""
}
}
Example Response
{
"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

400   Bad Request

401   Unauthorized

415   Unsupported Media Type

Modifying a Rule

Modify a rule.

Modifying a Rule
PUT /v0/projects/{project-id}/rules

Parameters

project-id Path   String (UUID)

Unique identifier of the project that you want to list rules for.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6


name Body   String

The user-defined name for the rule.

Example: UI Previews


condition Body   String

The routing condition for the rule. You can use SQL syntax to create this condition. Read Engine Routing for more information.


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.

Enum: ROUTE, 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.

Example Request
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": ""
}
}'
Example Response
{
"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.

caution

Since ruleInfoDefault is the default rule, it cannot be deleted.

Deleting a Rule
PUT /v0/projects/{project-id}/rules

Parameters

project-id Path   String (UUID)

Unique identifier of the project that you want to delete rules for.

Example: 02d36975-73eb-47ed-9bb5-de73060380f6

Example Request
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": ""
}
}'
Example Response
{
"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