# How AskTable works

How AskTable understands questions, queries data, and produces verifiable results.

使用指南 · 模块: product · 使用者 · 部署形态：资料未说明 · 已确认产品版本：资料未说明 · 来源：现有文档

AskTable queries and analyzes data within the user's permissions and retains the process used to query, calculate, and produce results.

## The complete journey of a question

**Retrieve semantics**

After you send a question, the agent first **searches your data semantics**: table structures, field descriptions, business documents, skills, and historical SQL.

It first determines what it can “see” and what it should answer.

**Clarify definitions**

If the question lacks a time range, granularity, or metric definition, the agent asks you first (requires [user clarification](https://docs.asktable.com/en/agent/capabilities) to be enabled). With clarification disabled, it makes reasonable assumptions from the available semantics and states them in its conclusions.

**Generate and validate SQL**

Generated SQL is validated first: only reads are allowed; writes, DDL, and `SELECT *` are rejected. Permissions are also applied at this stage:

- Row-level filters are inserted directly into WHERE
- Fields you cannot see are excluded from the query
- Training samples are filtered by visible tables during retrieval

In other words, **permissions take effect before query execution**, rather than hiding data after it has been queried.

**Execute and return results**

The data source executes the SQL. Results become data artifacts, shown as query results in the interface with row and column counts. The agent calls chart generation when charts are needed, and Python execution for complex calculations.

**Record sources**

Results retain the SQL actually executed and the data sources used, so you can expand them to verify the process or change conditions and rerun. The complete execution trace for that turn is written to the agent's [audit logs](https://docs.asktable.com/en/agent/logs-feedbacks).

## How results stay reliable

Language models can make things up. AskTable's approach is to prevent that:

| Mechanism                    | What it does                                                                                                                                                    |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Numbers must come from tools | For questions about specific data, numbers in the answer must come from read-only SQL tools or code sandbox execution. The model cannot supply them from memory |
| Report failures              | Failed tool calls return the actual error instead of falling back to a “rough estimate”; the original error is visible in the interface                         |
| Traceability                 | Expand each conclusion to see the SQL actually executed, data source, and duration; change conditions and rerun                                                 |
| Ask when uncertain           | With user clarification enabled, the agent confirms missing conditions instead of assuming a definition for the user                                            |

## How permissions restrict access

Permissions **rewrite queries during SQL generation**:

| Layer                     | How it works                                                                                                                                                      |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Row-level filtering       | Based on your current role, filters are inserted directly into the SQL `WHERE` clause to restrict visible rows at the data layer                                  |
| Field visibility          | Fields you are not authorized to view are excluded during semantic retrieval. The model **does not know they exist**, so prompts cannot persuade it to query them |
| Training sample retrieval | Historical question–SQL samples are filtered by visible tables during retrieval, preventing examples from leaking hidden structures                               |
| Entry-point identity      | Requests from Feishu, embedded pages, and APIs have their identity and scope established at the entry point before entering this workflow                         |

See [Permissions and data scopes](https://docs.asktable.com/en/permissions) for the three configuration locations and their precedence.

## Object model

```text
Project
├── Data sources        Queryable databases, files, or workbooks
├── Data agents         User-facing entry points for data questions
│   ├── Skills          Reusable analysis methods
│   ├── Business documents and preferences   Persistent analysis context
│   └── Channels / scheduled tasks / embedding   External entry points
├── Analysis canvases   Node-based in-depth analysis workflows
├── Data dashboards     Pages of refreshable results for ongoing monitoring
├── People / roles / policies   Members, data scopes, and row-level conditions
└── Result assets       Saved data tables and charts
```

A project is the isolation unit, and all resources belong to a project. A data agent packages data sources, skills, capability switches, and permissions into a ready-to-use assistant. Business users interact with it without needing to know which databases are connected underneath.

## Data semantics are the source of accuracy

AskTable does not inherently know your business. It uses the following information to understand terms such as “revenue” and “active users”:

| Semantic source    | Purpose                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Field descriptions | Explain a field's business meaning, with precedence: manual > native database description > AI-generated                         |
| Semantic types     | Mark primary keys, foreign keys, email addresses, regions, and similar types to help determine joins and groupings               |
| Field visibility   | Determine whether a field is visible to the AI                                                                                   |
| Masking types      | Apply type-specific masking to names, phone numbers, national ID numbers, bank card numbers, and email addresses                 |
| AI indexes         | Map abbreviations in questions to actual field values                                                                            |
| Training sets      | Provide examples of questions paired with correct SQL for retrieval                                                              |
| Business documents | Define metrics, business rules, and industry terminology; see [Business documents](https://docs.asktable.com/en/agent/documents) |

**When business definitions are wrong, improving data semantics is more effective than rephrasing the question.**

## Boundaries

- **Read-only.** No writes, DDL, or `SELECT *`.
- **No invented numbers.** Questions about specific data must obtain results through tool calls; tool failures are reported honestly.
- **No cross-project access.** All resources are isolated within their project.
- **Self-hosted deployments can run entirely offline.** Models can use internal self-hosted services too, keeping data within your security boundary.

## Next steps

- Connect your own data: [Connect data sources](https://docs.asktable.com/en/data/connect)
- Help AI understand your business definitions: [Table and field descriptions](https://docs.asktable.com/en/data/semantics)
- Control who can see what: [Permissions and data scopes](https://docs.asktable.com/en/permissions)
- Inspect each execution: [Logs and user feedback](https://docs.asktable.com/en/agent/logs-feedbacks)