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

The set of rules applicable to a project.

Provides a list of all the rules in the project.

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.

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

The user-defined name for the default rule.

Example All Other Queries

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'

The name of the engine that jobs will be routed to.

Example default-engine

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

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

Example REST API jobs are rejected.

ruleInfos

ruleInfos is a list of rules in the project.

Individual Rule Object

The user-defined name for the rule.

Example UI Previews

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'

The name of the engine that jobs will be routed to.

Example preview

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

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

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

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.

Adding a Rule

PUT /v0/projects/{project-id}/rules

Parameters

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

The user-defined name for the rule.

The routing condition for the rule. You can use SQL syntax to create this condition. For more information, see Engine Routing Rules .

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

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.

The name of the engine where the jobs will be routed to. When action is REJECT, leave this parameter empty.

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

Modifying a Rule

Modify a rule.

Modifying a Rule

PUT /v0/projects/{project-id}/rules

Parameters

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

The user-defined name for the rule.

The routing condition for the rule. You can use SQL syntax to create this condition. For more information, see Engine Routing Rules .

The name of the engine that jobs will be routed to. When action is REJECT, leave this parameter empty.

Example preview

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

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.

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

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.

Deleting a Rule

PUT /v0/projects/{project-id}/rules

Parameters

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

Was this page helpful?

Glad to hear it! Thank you for your feedback. Sorry to hear that. Thank you for your feedback.