Skip to main content

Engines

An engine represents a Dremio Cloud entity that manages compute resources. Each engine has one or more replicas that are created for executing queries. An engine replica is a logical group of executors defined by the engine size. This API allows you to list existing engines and add, modify, enable/disable, and delete engines.

Engine Object
    "id": "e1cb20ff-a234-46f1-9f97-550e2bb5310f",
    "name": "firstEngine",
    "size": "XX_SMALL_V1",
    "activeReplicas": 0,
    "minReplicas": 0,
    "maxReplicas": 10,
    "autoStopDelaySeconds": 300,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 0,
    "state": "ENABLED",
    "cloudTags": [],
    "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
    "statusChangedAt": "Thu Aug 19 14:39:40 UTC 2021",
    "description": "",
    "maxConcurrency": 4

Engine Attributes​

{{< api-section file="data/api/engines.json" data="engineAttributes" >}}

cloudTags​

{{< api-section file="data/api/engines.json" data="cloudTags" >}}

Listing All Engines​

Returns a list of all the engines in the specified project and the metadata for each engine.

Listing All Engines
GET /v0/projects/{project-id}/engines

Parameters​

{{< api-section file="data/api/engines.json" data="listingAllEnginesParameters" >}}

Example Request
curl -X GET 'https://api.dremio.cloud/v0/projects/02d36975-73eb-47ed-9bb5-de73060380f6/engines' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
{
[
  {
    "id": "e1cb20ff-a234-46f1-9f97-550e2bb5310f",
    "name": "firstEngine",
    "size": "XX_SMALL_V1",
    "activeReplicas": 0,
    "minReplicas": 0,
    "maxReplicas": 10,
    "autoStopDelaySeconds": 300,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 0,
    "state": "ENABLED",
    "cloudTags": [],
    "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
    "statusChangedAt": "Thu Aug 19 14:39:40 UTC 2021",
    "description": "",
    "maxConcurrency": 4
  },
  {
    "id": "a99eb46a-8121-4b79-b2ed-917e07f96092",
    "name": "preview",
    "size": "XX_SMALL_V1",
    "activeReplicas": 0,
    "minReplicas": 0,
    "maxReplicas": 1,
    "autoStopDelaySeconds": 180,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 0,
    "state": "ENABLED",
    "cloudTags": [],
    "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
    "statusChangedAt": "Fri Aug 20 03:58:54 UTC 2021",
    "description": "",
    "maxConcurrency": 4
  }
]

Responses​

{{< api-responses file="data/api/engines.json" data="listingAllEnginesResponses" >}}

Adding an Engine​

Add an engine to the cloud account that is associated with the specified project.

Adding an Engine
POST /v0/projects/{project-id}/engines

Parameters​

Engine​

{{< api-section file="data/api/engines.json" data="addingEngineParameters" >}}

cloudTags​

{{< api-section file="data/api/engines.json" data="addingEngineTagParameters" >}}

Example Request
curl -X POST 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines' \
-H 'Authorization: Bearer <personal access token>' \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-d '{
    "name": "newengine",
    "size": "XX_SMALL_V1",
    "minReplicas": 0,
    "maxReplicas": 1,
    "autoStopDelaySeconds": 7200,
    "queueTimeLimitSeconds": 300,
    "runtimeLimitSeconds": 0,
    "drainTimeLimitSeconds": 1800,
    "cloudTags": [
        {
        "key": "tag1",
        "value": "value1"
        }
      ],
      "description": "engine description",
      "maxConcurrency": 2,
      "requestId": "d9904076-01db-11ec-9a03-0242ac130003"
      }'
Example Response
{
  "id": "168acd56-16a0-47df-91f8-5487a8fccfc4"
}

Responses​

{{< api-responses file="data/api/engines.json" data="addingEngineResponses" >}}

Retrieving an Engine​

Get the metadata for an existing engine by providing the project and engine IDs.

Retrieving an Engine
GET /v0/projects/{project-id}/engines/{id}

Parameters​

{{< api-section file="data/api/engines.json" data="retrievingEngineParameters" >}}

Example Request
curl -X GET 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines/168acd56-16a0-47df-91f8-5487a8fccfc4' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
{
  "id": "168acd56-16a0-47df-91f8-5487a8fccfc4",
  "name": "newengine",
  "size": "XX_SMALL_V1",
  "activeReplicas": 0,
  "minReplicas": 0,
  "maxReplicas": 1,
  "autoStopDelaySeconds": 7200,
  "queueTimeLimitSeconds": 300,
  "runtimeLimitSeconds": 0,
  "drainTimeLimitSeconds": 1800,
  "state": "ENABLED",
  "cloudTags": [
    {
      "key": "tag1",
      "value": "value1"
    }
  ],
  "queriedAt": "Thu Jan 01 00:00:00 UTC 2021",
  "statusChangedAt": "Fri Aug 20 17:29:18 UTC 2021",
  "description": "engine description",
  "maxConcurrency": 2
}

Responses​

{{< api-responses file="data/api/engines.json" data="retrievingEngineResponses" >}}

Modifying an Engine​

Modify the engine by providing the project and engine IDs. Parameters that are not provided will be left unchanged. The engine name cannot be modified.

Modifying an Engine
PUT /v0/projects/{project-id}/engines/{id}

Parameters​

{{< api-section file="data/api/engines.json" data="modifyingEngineParameters" >}}

cloudTags​

{{< api-section file="data/api/engines.json" data="modifyingEngineTagParameters" >}}

Example Request
curl -X PUT 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines/168acd56-16a0-47df-91f8-5487a8fccfc4' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json' \
-d '{
      "description": "modified engine description",
      "size": "XX_SMALL_V1",
      "autoStopDelaySeconds": 7200,
      "drainTimeLimitSeconds": 1800,
      "maxConcurrency": 2,
      "maxReplicas": 1,
      "minReplicas": 0,
      "queueTimeLimitSeconds": 300,
      "runtimeLimitSeconds": 0,
      "cloudTags":  [ ]
      }'
Example Response
No response

Responses​

{{< api-responses file="data/api/engines.json" data="modifyingEngineResponses" >}}

Enabling an Engine​

Enable an engine.

Enabling an Engine
PUT /v0/projects/{project-id}/engines/{id}/enable

Parameters​

{{< api-section file="data/api/engines.json" data="enablingEngineParameters" >}}

Example Request
curl -X PUT 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines/168acd56-16a0-47df-91f8-5487a8fccfc4/enable' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
No response

Responses​

{{< api-responses file="data/api/engines.json" data="enablingEngineResponses" >}}

Disabling an Engine​

Disable an engine.

Disabling an Engine
PUT /v0/projects/{project-id}/engines/{id}/disable

Parameters​

{{< api-section file="data/api/engines.json" data="disablingEngineParameters" >}}

Example Request
curl -X PUT 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines/168acd56-16a0-47df-91f8-5487a8fccfc4/disable' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
No response

Responses​

{{< api-responses file="data/api/engines.json" data="disablingEngineResponses" >}}

Deleting an Engine​

Delete an engine by providing the project and engine ID.

Deleting an Engine
DELETE /v0/projects/{project-id}/engines/{id}

Parameters​

{{< api-section file="data/api/engines.json" data="deletingEngineParameters" >}}

Example Request
curl -X DELETE 'https://api.dremio.cloud/v0/projects/c683b988-aa93-439c-a9ac-0d7f72b53d23/engines/168acd56-16a0-47df-91f8-5487a8fccfc4' \
-H 'Authorization: Bearer <personal access token>' \
-H 'Content-Type: application/json'
Example Response
No response

Responses​

{{< api-responses file="data/api/engines.json" data="deletingEngineResponses" >}}