> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemod.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Smart (Jev-powered) queries

Smart queries count files that match a natural-language description of a code characteristic. Use them when you want a file-count signal for security smells, environment-variable usage, missing error handling, or similar characteristics before you have an exact ast-grep rule or JSSG metric.

Prefer a different source when you need:

* Exact syntax matches → [ast-grep YAML](/enterprise/insights/ast-grep-queries)
* Custom metrics or programmatic analysis → [JSSG](/enterprise/insights/jssg-queries)
* Package inventory → [Dependencies](/enterprise/insights/dependency-queries)

Smart is an Insights query source over indexed repository snapshots. It is not a grep search and does not return line matches or code snippets.

<Steps>
  <Step title="Choose Smart as the query source">
    In a timeseries, single-number, or table widget, open the query source selector and choose **Smart**.
  </Step>

  <Step title="Describe the characteristic">
    Enter a prompt such as "Find files that read or depend on environment variables", or start from **Examples** (security issue finder, environment variable usage, missing error handling).
  </Step>

  <Step title="Optionally run interpret">
    Click **Run** to draft match rules, probability, globs, and group-by from your prompt. **Run** does not execute analysis. If you edit the prompt while interpret is running, Codemod discards the draft result.
  </Step>

  <Step title="Tune probability and match rules">
    Set **Probability** to Low (60%), Medium (85%, default), or High (90%). Only files at or above that confidence count as matches. Optionally add **Match rules** for "Count as a match when" and "Do not match when".
  </Step>

  <Step title="Select repositories and breakdowns">
    Choose repositories, optional include and exclude globs, and group-by dimensions. Save the widget. Smart widgets show **Analyzing code** with progress such as `N of M checks` while file judgments run.
  </Step>
</Steps>

| Configuration         | Description                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Prompt**            | Natural-language description of the file characteristic (up to 4,000 characters). You can bind a dashboard **String** template variable instead of a fixed prompt.                      |
| **Probability**       | Minimum match confidence: Low `60%`, Medium `85%` (default), or High `90%`                                                                                                              |
| **Match rules**       | Optional include and exclude criteria that refine what counts as a match                                                                                                                |
| **Select**            | File count only                                                                                                                                                                         |
| **Repository**        | One or more repositories, or a repository template variable                                                                                                                             |
| **Group by**          | `file path`, `language`, `repository`, `codeowner`, `directory` (depth 1–5), or a semantic category. Available for table and timeseries widgets; single-number widgets ignore grouping. |
| **Semantic category** | Built-in **OWASP 2025** preset, or a **Custom category…** with 2–50 labels. Used when you group by that category.                                                                       |
| **File path filter**  | Include and exclude globs together (Smart supports both in one filter)                                                                                                                  |
| **Snapshot base**     | A specific date or commit hash to analyze at a point in time, available for single number and table widgets                                                                             |
| **Query alias**       | A label for the query result, available for timeseries and table widgets                                                                                                                |

<Tip>
  Codemod Wish can help add or edit widgets on a dashboard. Smart queries follow the live dashboard schema (`type: "smart"`). There is no separate CLI or MCP command for Smart queries.
</Tip>

## Behavior to expect

* Analysis can continue in the background if a widget times out. Refresh the widget to pick up progress; completed file judgments stay cached.
* Files that are too large to analyze are skipped and reported as partial results.
* Changing the prompt or match rules invalidates cached judgments. Changing **Probability**, globs, or group-by reuses existing judgments for the same matcher.

## Example recipes

* **Security breakdown** — prompt for insecure patterns, group by the **OWASP 2025** semantic category in a table widget.
* **Environment usage** — prompt for environment-variable reads, group by file path.
* **Error-handling trend** — prompt for operations that can fail without handling, use a timeseries widget over your dashboard time range.

## Related

* [JSSG (JS ast-grep) queries](/enterprise/insights/jssg-queries)
* [ast-grep YAML queries](/enterprise/insights/ast-grep-queries)
* [Package dependency queries](/enterprise/insights/dependency-queries)
* [Template variables](/enterprise/insights#template-variables)