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

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 default to this rule. Since ruleInfoDefault is the default rule, it cannot be deleted.

tag String (UUID)

UUID of a tag that 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.

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

Example: query_type() = 'UI Preview'

engineName String

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

Example: preview

action String

The rule type. When a query is routed to a particular engine, the value is ROUTE. When a query is rejected, the value is REJECT.

Valid Values: 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. See Engine Routing for more information.

Example: query_type() = 'Reflections'

engineName String

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

Example: default-engine

action String

The rule type. When a query is routed to a particular engine, the value is ROUTE. When a query is rejected, the value is REJECT.

Example: ROUTE

rejectMessage String

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

Example: REST API jobs are rejected.

List All Rules

Method and URL

GET /v0/projects/{project_id}/rules

Parameters

project_id Path String (UUID)

Example

Request

curl -X GET "https://api.dremio.cloud/v0/projects/$PROJECT_ID/rules" \
-H "Authorization: Bearer $DREMIO_TOKEN" \
-H 'Content-Type: application/json'

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

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)

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. See 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 is ROUTE. When a query is rejected, the value is REJECT.

Valid Values: 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 to which jobs will be routed. When action is REJECT, leave this parameter empty.

Example: preview

tag Body String (UUID)

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/rules" \
-H "Authorization: Bearer $DREMIO_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": ""
  }
}'

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

Modify a Rule

Method and URL

PUT /v0/projects/{project_id}/rules

Parameters

project_id Path String (UUID)

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

engineName Body String

The name of the engine to which jobs will be routed. 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 is ROUTE. When a query is rejected, the value is REJECT.

Valid Values: 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 (UUID)

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/rules" \
-H "Authorization: Bearer $DREMIO_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": ""
  }
}'

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

Delete a Rule

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)

Example

Request

curl -X PUT "https://api.dremio.cloud/v0/projects/$PROJECT_ID/rules" \
-H "Authorization: Bearer $DREMIO_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": ""
  }
}'

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​

List All Rules​

Parameters​

Example​

Response Status Codes​

Add a Rule​

Parameters​

Example​

Response Status Codes​

Modify a Rule​

Parameters​

Example​

Response Status Codes​

Delete a Rule​

Parameters​

Example​

Response Status Codes​

Engine Rules Attributes

Attributes of the `ruleSet` Object

Attributes of Objects in the `ruleInfos` Array

Attributes of the `ruleInfoDefault` Object

List All Rules

Parameters

Example

Response Status Codes

Add a Rule

Parameters

Example

Response Status Codes

Modify a Rule

Parameters

Example

Response Status Codes

Delete a Rule

Parameters

Example

Response Status Codes