On this page

    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

    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, see Engine Routing Rules .

    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, see Engine Routing Rules .

    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.

    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

    project-id

    path

    String (UUID)

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


    name

    query

    String

    The user-defined name for the rule.


    condition

    query

    String

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


    action

    query

    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

    query

    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

    query

    String

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


    tag

    query

    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

    query

    String

    The user-defined name for the rule.


    condition

    query

    String

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


    engineName

    query

    String

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

    Example preview


    action

    query

    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

    query

    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

    query

    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.

    warning:

    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