> For the complete documentation index, see [llms.txt](https://docs.kira.thiennguyen.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kira.thiennguyen.dev/user-guide/smart-query.md).

# Smart Query (AI)

Smart Query is an **optional** feature that turns a natural-language prompt into SQL — and into table filters — so you can ask for what you want instead of hand-writing every query. It's powered by the [`claude` CLI](https://docs.claude.com/en/docs/claude-code) running locally on your machine.

{% hint style="info" %}
Smart Query is **off by default** and opt-in. Nothing AI-related runs until you enable it.
{% endhint %}

## Prerequisites

* The **`claude` CLI** installed and available on your `PATH` (or point Kira at it explicitly).

## Enabling it

Set the following in your [configuration](/getting-started/configuration.md#top-level-fields):

| Setting         | Purpose                                                                    |
| --------------- | -------------------------------------------------------------------------- |
| `aiEnabled`     | Set to `true` to turn Smart Query on.                                      |
| `claudeBinPath` | Optional. Absolute path to the `claude` binary if it isn't on your `PATH`. |
| `aiModel`       | Optional. Model alias passed to `claude --model`. Defaults to `sonnet`.    |

## Using it

With Smart Query enabled, the [SQL editor](/user-guide/databases.md#the-sql-editor) and table views can:

* **Generate SQL** from a plain-language description of what you want.
* **Generate a table filter** from a description, instead of writing the predicate by hand.

Kira gives the model the context it needs (such as the relevant schema) so the generated query targets your actual tables.

## Privacy

Smart Query invokes the `claude` CLI locally. Review your own organization's policy before sending schema or query context to an AI model, and keep `aiEnabled` off if that's not appropriate for the data you work with.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kira.thiennguyen.dev/user-guide/smart-query.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.