AssetDB Saved Query Management
Relevant source files
The following files were used as context for generating this wiki page:
AssetDB Saved Query Management provides a suite of tools for discovering, retrieving, creating, and archiving SQL queries within the Stacklet AssetDB data warehouse. This system integrates with the Redash API to allow users to persist complex cloud asset analytics for reuse and sharing.
The management lifecycle includes searching existing queries via tags or content, inspecting query definitions and parameters, and performing write operations such as saving new drafts or archiving obsolete entries. Write operations like assetdb_query_save and assetdb_query_archive are conditionally enabled based on server settings.
Sources: CLAUDE.md:65-74, stacklet/mcp/assetdb/tools.py:46-53
Architecture and Components
The system utilizes a client-server architecture where the AssetDBClient acts as the intermediary between the Model Context Protocol (MCP) tools and the Redash API.
Data Flow for Query Management
The following diagram illustrates the interaction between the MCP tools, the internal client, and the Redash backend.
The flow demonstrates how MCP tools invoke methods on the AssetDBClient, which uses StackletCredentials to authenticate against the Redash endpoint.
Sources: stacklet/mcp/assetdb/redash.py:27-44, stacklet/mcp/assetdb/tools.py:108-115
Key Components
| Component | Description |
|---|---|
AssetDBClient | Manages HTTP sessions, authentication via identity tokens, and request routing to Redash endpoints. |
QueryUpsert | A Pydantic model that defines the schema for creating or updating queries, including name, SQL text, tags, and parameters. |
ToolQueryList | Encapsulates paginated search results for query discovery. |
FastMCP Tools | Expose query management functions as tools reachable by the LLM or agent. |
Sources: stacklet/mcp/assetdb/redash.py:27-40, stacklet/mcp/assetdb/models.py:151-177, stacklet/mcp/assetdb/tools.py:126-140
Query Discovery and Retrieval
The system provides tools to browse and inspect the query repository. The assetdb_query_list tool supports pagination, keyword searching, and tag filtering.
Search and Filtering
Users search through saved queries using the search parameter, which matches against query names, descriptions, and SQL content. Filtering by tags requires all provided tags to match.
async def list_queries(
self,
page: int = 1,
page_size: int = 25,
search: str | None = None,
tags: list[str] | None = None,
) -> QueryListResponse:
params: dict[str, Any] = {"page": page, "page_size": page_size}
if search:
params["q"] = search
if tags:
params["tags"] = tags
result = await self._make_request("GET", "api/queries", params=params)
return QueryListResponse(**result)
Sources: stacklet/mcp/assetdb/redash.py:102-125, stacklet/mcp/assetdb/tools.py:84-106
Detailed Inspection
The assetdb_query_get tool retrieves the full Query model, including its SQL structure and parameter definitions. This is a critical step before execution to ensure required parameters are identified.
Sources: stacklet/mcp/assetdb/tools.py:143-157, stacklet/mcp/assetdb/models.py:73-100
Query Mutation Operations
Mutation operations (save and archive) are restricted by feature flags in the server configuration.
Configuration Settings
| Environment Variable | Default | Purpose |
|---|---|---|
STACKLET_MCP_ASSETDB_ALLOW_SAVE | false | Enables assetdb_query_save for creating/updating queries. |
STACKLET_MCP_ASSETDB_ALLOW_ARCHIVE | false | Enables assetdb_query_archive for hiding queries. |
Sources: CLAUDE.md:154-155, stacklet/mcp/assetdb/tools.py:48-53
Saving and Updating Queries
The assetdb_query_save tool performs an "upsert" operation. If a query_id is provided, the tool updates the existing entry; otherwise, it creates a new query. New queries default to a is_draft=True status.
Archiving Queries
Archiving is an idempotent operation that sets the query's status to archived. This removes associated visualizations and alerts and hides the query from standard listings. The operation is performed via a DELETE request to the query's endpoint.
Sources: stacklet/mcp/assetdb/tools.py:208-223, stacklet/mcp/assetdb/redash.py:287-296
Parameterized Query Management
AssetDB support for parameterized queries allows dynamic execution using the {{parameter_name}} syntax. Query management involves defining these parameters in the options field of the query.
Parameter Structure
Parameters are stored within the options dictionary. The system supports various types, including text, number, date, and query (dropdown).
| Field | Type | Description |
|---|---|---|
name | string | The identifier used in the SQL template (e.g., {{name}}). |
type | string | The data type (text, number, query, etc.). |
queryId | integer | Used for type: "query" to reference a source query for dropdown values. |
Sources: stacklet/mcp/assetdb/sql_info.md:58-90, stacklet/mcp/assetdb/models.py:90-92
Parameter Discovery Workflow
- Call
assetdb_query_get: Inspect theoptions.parameterslist to find required inputs. - Execute Source Query: If a parameter is of type
query, execute the query ID specified inqueryIdto retrieve validvalueoptions. - Submit Result Request: Pass the discovered values to
assetdb_query_result.
Sources: stacklet/mcp/assetdb/sql_info.md:92-113
Summary
AssetDB Saved Query Management enables long-term persistence and organization of cloud analytics. By leveraging the Redash API, it provides robust search, detailed metadata inspection, and controlled write capabilities. The system emphasizes safety through configurable permissions and encourages parameterization to create dynamic, reusable analytical tools.