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.

ruleInfos

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.

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.

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​

rule

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

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

401

Unauthorized

404

Not found

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.

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.

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.

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

401

Unauthorized

404

Not found

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.

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.

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