> For the complete documentation index, see [llms.txt](https://docs.stackai.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stackai.com/integrations/catalog/apache-druid.md).

# Apache Druid

Run SQL and native queries against Apache Druid and manage ingestion tasks.

### Connectors

Choose the connector that matches your authentication method. The options below use the names shown in StackAI.

| Connector    | Authentication |
| ------------ | -------------- |
| Apache Druid | Credentials    |

#### Apache Druid

Connect to an Apache Druid Router. Leave the credentials empty for a Router without authentication, or provide the username and password accepted by its HTTP Basic authenticator.

**Set up in Apache Druid**

1. Prepare the Apache Druid account or service that the workflow will access. Grant access to the required resources and operations.
2. **Router Base URL:** Enter the Router origin without an API path, for example <https://druid.example.com:8888>. It must be reachable from your StackAI backend. Localhost is not supported. Private addresses require a BYOC/on-prem deployment with private connectivity. Use HTTPS when sending credentials. The Router must proxy management requests to the Overlord for ingestion actions.

**Set up in StackAI**

1. Open **Settings → Connections**, add a connection, and select **Apache Druid**.
2. Enter the credentials and connection details in the fields below.
3. Save the connection and check its connection status. Select this saved connection when configuring an action or feature that uses it.

**Connection fields**

| StackAI field   | Required                 | What to enter                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| --------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Router Base URL | Yes                      | Enter the Router origin without an API path, for example <https://druid.example.com:8888>. It must be reachable from your StackAI backend. Localhost is not supported. Private addresses require a BYOC/on-prem deployment with private connectivity. Use HTTPS when sending credentials. The Router must proxy management requests to the Overlord for ingestion actions. [Provider instructions](https://druid.apache.org/docs/latest/design/router/). |
| Username        | Optional / as applicable | Optional. Leave empty for a Router without authentication. Otherwise use a username and password accepted by the Router's HTTP Basic authenticator. Ask your Druid administrator for credentials with permission for the actions and datasources you use. [Provider instructions](https://druid.apache.org/docs/latest/development/extensions-core/druid-basic-security/).                                                                               |
| Password        | Optional / as applicable | Optional. The password for the username above, as configured in the Router's Basic authenticator.                                                                                                                                                                                                                                                                                                                                                        |

#### Verify the connection

Check that the connection is healthy. Then run a read operation against a resource the connected account can access. A successful connection check confirms authentication; it does not guarantee permission for every action.

If access is denied, check the credential or OAuth permissions, the selected account or environment, and access to the specific resource. Update expired credentials or reconnect after permissions change.

### Use an action

1. Add the required **Apache Druid** action to the workflow.
2. Select a connection when the action requests one.
3. Complete the required fields. Use the reference picker when a value comes from another workflow step.
4. Run the workflow and inspect the action’s output. Check the result before using it in a later step.

### Actions

#### List Datasources

List the datasources currently available for queries.

**Inputs**

No input fields are required in this catalog entry.

**Outputs**

| Field       | Type          | Description                 |
| ----------- | ------------- | --------------------------- |
| Datasources | string\_array | Queryable datasource names. |

#### Execute SQL Query

Run a synchronous SQL query and return structured result rows.

**Inputs**

| Field             | Type     | Required | Description                                                                                   |
| ----------------- | -------- | -------- | --------------------------------------------------------------------------------------------- |
| SQL statement     | textarea | Yes      | The Druid SQL statement to run. Put values in the SQL parameters field, not in the statement. |
| SQL parameters    | textarea | No       | Optional typed parameter values as a JSON array.                                              |
| Timeout (seconds) | integer  | No       | Maximum query runtime, from 1 to 300 seconds. Default: 30.                                    |
| Query context     | textarea | No       | Optional Druid query context settings as JSON.                                                |

**Outputs**

| Field               | Type        | Description                                                       |
| ------------------- | ----------- | ----------------------------------------------------------------- |
| Rows                | dict\_array | Structured query result rows.                                     |
| Diagnostic query ID | string      | Druid's identifier for this request, for support and log lookups. |

#### Execute Native Query

Run a native JSON query for Druid-specific analytics.

**Inputs**

| Field             | Type     | Required | Description                                                |
| ----------------- | -------- | -------- | ---------------------------------------------------------- |
| Native query      | textarea | Yes      | The complete native Druid query as JSON.                   |
| Timeout (seconds) | integer  | No       | Maximum query runtime, from 1 to 300 seconds. Default: 30. |

**Outputs**

| Field        | Type        | Description                         |
| ------------ | ----------- | ----------------------------------- |
| Query result | dict\_array | The structured native query result. |

#### Submit Ingestion Task

Submit a reviewed ingestion task to an Apache Druid datasource. The task runs asynchronously.

**Inputs**

| Field                     | Type     | Required | Description                                                                                                                   |
| ------------------------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| Task specification (JSON) | textarea | Yes      | The complete native task specification to run, as JSON. Submitting a task requires DATASOURCE WRITE on the target datasource. |

**Outputs**

| Field   | Type   | Description                                   |
| ------- | ------ | --------------------------------------------- |
| Task ID | string | The task ID for the submitted ingestion task. |

#### Submit Async SQL Query

Start a long-running asynchronous SQL query or SQL ingestion job.

**Inputs**

| Field              | Type            | Required | Description                                                                                                                                                                                                                      |
| ------------------ | --------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SQL statement      | textarea        | Yes      | The Druid SQL statement to run, as SELECT, INSERT, or REPLACE.                                                                                                                                                                   |
| Read only          | boolean         | Yes      | Reject INSERT and REPLACE statements. Default: true.                                                                                                                                                                             |
| SQL parameters     | textarea        | No       | Optional typed parameter values as a JSON array.                                                                                                                                                                                 |
| Result destination | select (string) | No       | Keep Task report for ordinary results. Choose Durable storage only when your Druid administrator has enabled durable storage for multi-stage query results. Available values: Task report, Durable storage. Default: taskReport. |
| Query context      | textarea        | No       | Optional multi-stage query (MSQ) context settings as JSON.                                                                                                                                                                       |

**Outputs**

| Field         | Type   | Description                                   |
| ------------- | ------ | --------------------------------------------- |
| Query ID      | string | The query ID for this asynchronous SQL query. |
| Initial state | string | The initial asynchronous query state.         |

#### Get Async SQL Query Status

Check the current state and result metadata for an asynchronous SQL query.

**Inputs**

| Field                     | Type    | Required | Description                                                          |
| ------------------------- | ------- | -------- | -------------------------------------------------------------------- |
| Query ID                  | string  | Yes      | The query ID returned by Submit Async SQL Query.                     |
| Include execution details | boolean | No       | Include stage counters and warnings in the response. Default: false. |

**Outputs**

| Field        | Type   | Description                                               |
| ------------ | ------ | --------------------------------------------------------- |
| Query state  | string | Current query state.                                      |
| Query status | object | Structured query state, schema, and result-page metadata. |

#### Get Async SQL Query Results

Fetch bounded result pages from a successful asynchronous SQL query.

**Inputs**

| Field            | Type    | Required | Description                                                                                                          |
| ---------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
| Query ID         | string  | Yes      | The query ID returned by Submit Async SQL Query after it reaches SUCCESS.                                            |
| Starting page ID | integer | No       | Fetch result pages at or above this page ID. Use 0 to start. Minimum: 0. Default: 0.                                 |
| Maximum pages    | integer | No       | The maximum number of result pages to fetch in this call. Choose from 1 to 20. Minimum: 1. Maximum: 20. Default: 10. |

**Outputs**

| Field        | Type        | Description                                                    |
| ------------ | ----------- | -------------------------------------------------------------- |
| Rows         | dict\_array | Structured rows collected from the fetched result pages.       |
| Next page ID | integer     | The ID of the next page that was not fetched, if there is one. |

#### Cancel Async SQL Query

Request cancellation of an asynchronous SQL query.

**Inputs**

| Field    | Type   | Required | Description                                      |
| -------- | ------ | -------- | ------------------------------------------------ |
| Query ID | string | Yes      | The query ID returned by Submit Async SQL Query. |

**Outputs**

| Field                 | Type    | Description                                                                                                     |
| --------------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| Cancellation accepted | boolean | True when Druid accepted the cancellation. False when the query had already finished and nothing was cancelled. |

#### Get Ingestion Task Status

Check the current state and execution details for one ingestion task.

**Inputs**

| Field   | Type            | Required | Description                                                                               |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| Task ID | select (string) | Yes      | The task ID returned by Submit Ingestion Task. Options load from the selected connection. |

**Outputs**

| Field       | Type   | Description                                                            |
| ----------- | ------ | ---------------------------------------------------------------------- |
| Task state  | string | The task state reported by Druid, such as RUNNING, SUCCESS, or FAILED. |
| Task status | object | Structured ingestion task state and execution details.                 |

#### Get Ingestion Task Report

Get ingestion statistics, errors, and availability details for one task.

**Inputs**

| Field   | Type            | Required | Description                                                                               |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| Task ID | select (string) | Yes      | The task ID returned by Submit Ingestion Task. Options load from the selected connection. |

**Outputs**

| Field       | Type | Description                                                        |
| ----------- | ---- | ------------------------------------------------------------------ |
| Task report | dict | Structured ingestion statistics, errors, and availability details. |

#### Cancel Ingestion Task

Request shutdown of one running Apache Druid ingestion task.

**Inputs**

| Field   | Type            | Required | Description                                                                               |
| ------- | --------------- | -------- | ----------------------------------------------------------------------------------------- |
| Task ID | select (string) | Yes      | The task ID returned by Submit Ingestion Task. Options load from the selected connection. |

**Outputs**

| Field   | Type   | Description                                   |
| ------- | ------ | --------------------------------------------- |
| Task ID | string | The task ID that Druid accepted for shutdown. |

### Important behavior

Actions that create, update, send, or delete data can change the connected service. Review their inputs before running them. A retry can repeat an operation; consider this when configuring retries for actions that change data.

The catalog lists the fields and capabilities available in the supplied provider definition. Availability can also depend on your deployment and organization’s Feature Access settings.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.stackai.com/integrations/catalog/apache-druid.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
