# Data Explorer

## Get Data Explorer Query

`TOOL discourse_get_query`

Get full details of a Data Explorer query including SQL and parameters. Requires admin API key.

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (argument, integer, required) - Query ID
  Type: integer
  
  Query ID
  
  exclusiveMinimum: 0

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_get_query",
    "arguments": {
        "id": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_get_query",
  "arguments": {
    "id": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_get_query", arguments={
  "id": 0
})
```


## Run Data Explorer Query

`TOOL discourse_run_query`

Execute a Data Explorer query with parameters. Returns columns, rows, result_count, duration_ms. Queries run in read-only transactions with 10-second timeout. Requires admin API key.

Authentication: no security requirement declared for this operation.

Request body: application/json (required)

Type: object

- `id` (required)
  Type: integer
  
  Query ID to run

- `params` (optional)
  Type: object
  
  Query parameters as key-value pairs
  
  Additional properties: 
    Type: any

- `limit` (optional)
  Type: integer | string
  
  Maximum number of rows to return (default: query default, use 'ALL' for unlimited)
  
  anyOf:
    Type: integer
    
    exclusiveMinimum: 0
  
    Type: string
    
    const: "ALL"

- `explain` (optional)
  Type: boolean
  
  Include query execution plan in response

Additional properties: false

Declared MCP annotations:

```json
{
  "readOnlyHint": true,
  "destructiveHint": false,
  "idempotentHint": true,
  "openWorldHint": true
}
```

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_run_query",
    "arguments": {
        "id": 0,
        "params": {},
        "limit": 0,
        "explain": true
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_run_query",
  "arguments": {
    "id": 0,
    "params": {},
    "limit": 0,
    "explain": true
  }
});
```

### Python

```python
result = await session.call_tool("discourse_run_query", arguments={
  "id": 0,
  "params": {},
  "limit": 0,
  "explain": true
})
```


## Create Data Explorer Query

`TOOL discourse_create_query`

Create a new saved Data Explorer query. Requires admin API key and write access.

Authentication: no security requirement declared for this operation.

Parameters:

- `name` (argument, string, required) - Query name
  Type: string
  
  Query name
  
  minLength: 1
  
  maxLength: 255

- `sql` (argument, string, required) - SQL query. Declare parameters in comments: -- [params]\n-- int :user_id
  Type: string
  
  SQL query. Declare parameters in comments: -- [params]\n-- int :user_id
  
  minLength: 1

- `description` (argument, string, optional) - Query description
  Type: string
  
  Query description

- `group_ids` (argument, Array<integer>, optional) - Group IDs allowed to run this query (empty = admin only)
  Type: Array<integer>
  
  Group IDs allowed to run this query (empty = admin only)
  
  Items:
    Type: integer

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_create_query",
    "arguments": {
        "name": "string",
        "sql": "string",
        "description": "string",
        "group_ids": [
          0
        ]
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_create_query",
  "arguments": {
    "name": "string",
    "sql": "string",
    "description": "string",
    "group_ids": [
      0
    ]
  }
});
```

### Python

```python
result = await session.call_tool("discourse_create_query", arguments={
  "name": "string",
  "sql": "string",
  "description": "string",
  "group_ids": [
    0
  ]
})
```


## Update Data Explorer Query

`TOOL discourse_update_query`

Update an existing Data Explorer query. Only provided fields are updated. Requires admin API key and write access.

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (argument, integer, required) - Query ID to update
  Type: integer
  
  Query ID to update
  
  exclusiveMinimum: 0

- `name` (argument, string, optional) - New query name
  Type: string
  
  New query name
  
  minLength: 1
  
  maxLength: 255

- `sql` (argument, string, optional) - New SQL query
  Type: string
  
  New SQL query
  
  minLength: 1

- `description` (argument, string, optional) - New query description
  Type: string
  
  New query description

- `group_ids` (argument, Array<integer>, optional) - New group IDs allowed to run this query
  Type: Array<integer>
  
  New group IDs allowed to run this query
  
  Items:
    Type: integer

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_update_query",
    "arguments": {
        "id": 0,
        "name": "string",
        "sql": "string",
        "description": "string",
        "group_ids": [
          0
        ]
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_update_query",
  "arguments": {
    "id": 0,
    "name": "string",
    "sql": "string",
    "description": "string",
    "group_ids": [
      0
    ]
  }
});
```

### Python

```python
result = await session.call_tool("discourse_update_query", arguments={
  "id": 0,
  "name": "string",
  "sql": "string",
  "description": "string",
  "group_ids": [
    0
  ]
})
```


## Delete Data Explorer Query

`TOOL discourse_delete_query`

Soft-delete a Data Explorer query. The query can be restored by an admin. Requires admin API key and write access.

Authentication: no security requirement declared for this operation.

Parameters:

- `id` (argument, integer, required) - Query ID to delete
  Type: integer
  
  Query ID to delete
  
  exclusiveMinimum: 0

## Examples

### JSON-RPC

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "discourse_delete_query",
    "arguments": {
        "id": 0
      }
  }
}
```

### TypeScript

```typescript
const result = await client.callTool({
  "name": "discourse_delete_query",
  "arguments": {
    "id": 0
  }
});
```

### Python

```python
result = await session.call_tool("discourse_delete_query", arguments={
  "id": 0
})
```