# Create Vitruvio Query

> All messages shown to the user must be written in Portuguese.

You are creating a new named SQL query inside a Vitruvio repository. Follow these steps in order.

## Step 1 — Confirm you are inside a Vitruvio repo

```bash
ls vitruvio.json 2>/dev/null && echo "OK" || echo "NOT_A_VITRUVIO_REPO"
```

If `NOT_A_VITRUVIO_REPO`, stop and tell the user to `cd` into the correct repo.

## Step 2 — Collect query details

Ask the user (in a single message, only ask what is missing from their original request):

- **Key** — kebab-case unique identifier. Used to reference this query in reports, DBTable components, and scripts.
- **Name** — human-readable label shown in the Vitruvio UI.
- **SQL** — the query itself, or enough context to write it.
- **Connection** — datasource name (default: `vitruvio_producao`). Ask only if the user mentions a specific datasource.

## Step 3 — Create the file

Target path: `queries/<key>.sql`

Rules:
- One `SELECT` per file. No multiple statements, no DDL, no INSERT/UPDATE/DELETE.
- Named bind parameters use `:paramName` syntax — never concatenate user input into SQL.
- Write ANSI SQL where possible. If DB-specific syntax is unavoidable, note it in a comment.
- Keep Oracle and PostgreSQL compatibility in mind — avoid syntax that only works in one.

```sql
SELECT col1,
       col2
  FROM my_table
 WHERE active = 1
   AND id = :id
 ORDER BY col1
```

## Step 4 — Register in vitruvio.json

Read `vitruvio.json`, find or create the `"queries"` array, and add:

```json
{
  "key": "<key>",
  "name": "<name>",
  "source": "queries/<key>.sql",
  "connection": "<connection>"
}
```

Preserve the existing file structure and all other entries. Write the updated `vitruvio.json` back.

## Step 5 — Report

Tell the user:
- File created: `queries/<key>.sql`
- Registered in `vitruvio.json` with key `<key>`
- How it can be used: as a datasource in a report, in a DBTable component, or loaded in a script via `db.executeNamedQuery('<key>', params)`