# Query

> Run StackQL queries against cloud and SaaS providers. Accepts raw SQL or natural language questions. Translates natural language into StackQL SQL using the provider schema. Supports all StackQL operations: SELECT, INSERT, UPDATE, DELETE, and EXEC.

- Skill: `stackql/query` (Agent Skill)
- Install (CLI): `npx skillmds@latest add stackql/query`
- Raw SKILL.md: https://api.skillmd.com/api/skills/stackql/query/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: stackql (https://skillmd.com/u/stackql)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/stackql/query

---


You are helping the user query cloud infrastructure and SaaS resources using StackQL.

Input: `$@`

Follow these steps in order.

## Step 1 - Check StackQL is installed

```bash
command -v stackql
```

If not found, delegate to `/stackql-skills:install-stackql` and then continue.

## Step 2 - Resolve auth

Check if there is an auth configuration available. Look for:

1. A `.stackqlrc` file in the current directory or home directory
2. Environment variables for common providers (e.g., `GOOGLE_CREDENTIALS`, `AWS_ACCESS_KEY_ID`, `AZURE_CLIENT_ID`, `GITHUB_TOKEN`)

Build the `--auth` JSON string from what's available. If no credentials are found for the provider referenced in the query, suggest using `/stackql-skills:auth-setup <provider>`.

## Step 3 - Identify the provider and check it's pulled

Extract the provider name from the query (e.g., `google` from `google.compute.instances`).

```bash
stackql exec "SHOW PROVIDERS;" --output json
```

If the provider is not installed, delegate to `/stackql-skills:pull-provider <provider>` and then continue.

## Step 4 - Generate SQL if needed

If the input is natural language (not valid StackQL SQL), generate the appropriate query:

1. First, explore the relevant resources to understand the schema:

```bash
stackql exec "SHOW SERVICES IN <provider>;" --output json
```

Then narrow down to the relevant service and resource:

```bash
stackql exec "SHOW RESOURCES IN <provider>.<service>;" --output json
stackql exec "DESCRIBE <provider>.<service>.<resource>;" --output json
```

2. Use the schema to generate the correct StackQL SQL. Key patterns:

**Read (SELECT):**
```sql
SELECT id, name, status
FROM <provider>.<service>.<resource>
WHERE region = 'us-east-1';
```

**Create (INSERT):**
```sql
INSERT INTO <provider>.<service>.<resource> (project, zone, name, ...)
SELECT 'my-project', 'us-central1-a', 'my-resource', ...;
```

**Modify (UPDATE):**
```sql
UPDATE <provider>.<service>.<resource>
SET <field> = <value>
WHERE <identifiers>;
```

**Remove (DELETE):**
```sql
DELETE FROM <provider>.<service>.<resource>
WHERE <identifiers>;
```

**Lifecycle (EXEC):**
```sql
EXEC <provider>.<service>.<resource>.<method>
@param1 = 'value1', @param2 = 'value2';
```

Important: StackQL requires `WHERE` clauses for provider-specific parameters like `project`, `region`, `zone`, `subscriptionId`, etc. Check the `DESCRIBE` output for required parameters.

## Step 5 - Confirm destructive operations

If the generated query is an INSERT, UPDATE, DELETE, or EXEC operation, show the query to the user and ask for confirmation before executing.

> This will execute the following against your cloud environment:
> ```sql
> <QUERY>
> ```
> Proceed?

Do NOT execute destructive operations without explicit user confirmation.

## Step 6 - Execute the query

```bash
stackql exec "<QUERY>" --auth="${AUTH}" --output json
```

For queries that may return large result sets, add a practical limit or use `--output csv` for more compact output.

For multi-line queries, use a heredoc:

```bash
stackql exec --auth="${AUTH}" --output json <<'SQL'
<QUERY>
SQL
```

## Step 7 - Handle errors

- **Provider not found**: delegate to `/stackql-skills:pull-provider <provider>`
- **Authentication error**: suggest `/stackql-skills:auth-setup <provider>`
- **Resource not found**: use `/stackql-skills:explore <provider>` to help find the correct resource path
- **Required parameter missing**: check `DESCRIBE` output and add missing WHERE clause parameters
- **Syntax or API error**: use `/stackql-skills:stackql-docs <error keywords>` to search for guidance
- **Timeout**: suggest increasing `--apirequesttimeout` or narrowing the query scope

## Step 8 - Present results

Show the query output to the user. For JSON output, format it clearly.

For natural language questions, provide a brief interpretation of the results.

If the result set is large, summarize key findings and offer to drill down further.

Suggest related queries the user might find useful based on the results.