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 Objects in the `ruleInfos` Array

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.

Method and URL

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": "",
    }
}

Response Status Codes

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.

Method and URL

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": ""
    }
}'

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

415 Unsupported Media Type

Modifying a Rule

Modify a rule.

Method and URL

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

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": ""
    }
}

Response Status Codes

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.

Method and URL

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": ""
    }
}

Response Status Codes

200 OK

400 Bad Request

401 Unauthorized

404 Not Found

Engine Rules Attributes​

Attributes of the ruleSet Object​

Attributes of Objects in the ruleInfos Array​

Attributes of the ruleInfoDefault Object​

Listing All Rules​

Parameters​

Response Status Codes​

Adding a Rule​

Parameters​

Response Status Codes​

Modifying a Rule​

Parameters​

Response Status Codes​

Deleting a Rule​

Parameters​

Response Status Codes​

Engine Rules Attributes

Attributes of the `ruleSet` Object

Attributes of Objects in the `ruleInfos` Array

Attributes of the `ruleInfoDefault` Object

Listing All Rules

Parameters

Response Status Codes

Adding a Rule

Parameters

Response Status Codes

Modifying a Rule

Parameters

Response Status Codes

Deleting a Rule

Parameters

Response Status Codes