Product features: data connections and predefined queries

In user language: after a workspace admin configures a data connection (MySQL / PostgreSQL / SQL Server / SQLite), members can ask a work agent in Messages to query business data (mostly read-only) and, within grants, run controlled changes (insert/update/delete, optionally with approval). This page covers whether predefined queries are required, table-preview row limits, how they relate to table notes in workspace skills, and how to configure for speed and accuracy.

Entry: Workspace collaboration → Assistant capability packs → Data connections (full-page manage, same as the knowledge base).

Enable prerequisites (all required):

1. Platform: ops turn on data_source_tool.enabled in mindlink.json (see Server configuration).
2. Workspace: admin enables Data connections in Assistant capability packs (if off or expired, chat cannot query).
3. Member: authorized for the matching data resource under Who can use (read; changes also need insert/update/delete).

---

Charts / reports from a sample screenshot

When the workspace has Data integration and the member may query:

• Numbers: trust data-connection query results (the assistant runs predefined queries, etc.).
• Attached image: usually layout, colors, leader-line positions only — do not copy headcount or percentages from the picture into a formal report.
• Exception: you explicitly say “digitize this screenshot / copy numbers from the picture”, or there is no usable connection, then numbers on the picture may be used.

If the metric is unclear (include contractors? which org level to roll up?), the assistant should ask one clarifying round, then produce charts or reports in a row — avoid repeating confirmations.

---

Add a data connection in chat (workspace admin)

With Data integration enabled and the platform data-connection switch on, a workspace admin can describe or paste connection info to the help agent (floating lower right or Messages) or a work agent. The system:

1. Parses parameters (MySQL/PostgreSQL/SQL Server: host, port, database, user, password; SQLite: file path)
2. Tests the connection
3. Saves it as a data connection in this workspace
4. Optionally generates a query skill for later Q&A in Messages

Example (replace placeholders):

Please add a new data connection from the following:
database:
host: 183.234.85.86
port: 3306
username: root
password: ****
dbname: caretop

SQLite example:

Please add a SQLite data connection, file path: D:/code/mindlink/examples/hr-multi-tenant/server/data/hrms.db

SQL Server example:

Please add a SQL Server data connection:
host: 192.168.1.10
port: 1433
username: app_ro
password: ****
dbname: HRDB

You must select a workspace in the top bar first. Supported: MySQL/MariaDB, PostgreSQL, SQL Server, SQLite. On failure it asks you to check the info; you can also fill manually at Workspace collaboration → Assistant capability packs → Data connections.

---

Manage existing data connections in chat (workspace admin)

Besides new connection, admins can view, change, turn on/off, delete Data integration config in natural language with the help agent (floating window recommended while you stay on the settings page) or a work agent. For example:

If info is missing it asks (connection name, member, query id). Unrelated questions stay ordinary chat. To add a new connection, paste host, database, account, and password.

---

What members can do

In chat, the agent uses controlled tools on authorized data connections:

Photos and binary fields: image columns (BLOB) such as employee photos become downloadable attachments. Chat can show photo links; Word/PPT can embed the same attachment id.

The agent cannot improvise arbitrary SQL in chat. Conditioned queries must go through a predefined query; writes must go through a change definition.

How to ask more accurately

The model can misunderstand, so asking numbers is not “write SQL on the spot”. In chat:

1. When you ask, the platform matches your original words to already configured predefined queries (the assistant does not have to browse tables first).
2. On a match it runs the saved SQL; the reply first lists what was queried and under which conditions so you can see a wrong match.
3. If one step was wrong, change that step and ask again — no need to start over.
4. If nothing matches, it still follows propose → confirm → save → run and will not change the database on its own.

Clear name, description, parameter names on each predefined query reduce mistakes more than another model round. Mechanism: docs/core-mechanisms/数据连接问数准确性.md.

Work agent saving predefined queries

Only workspace admins can add, update, or delete predefined queries in Messages via a work agent (e.g. after exploring table structure, freeze SQL for reuse by query id). Say “save this query as xxx”, “delete a query on connection xxx”, etc.

Ordinary members cannot change query config; they can only query within grants (table preview, run predefined queries). Without admin identity the tool says “only workspace admins can manage predefined queries”.

#### Add a query in chat (no match)

When the user wants stats, duplicate check, filter by condition, look up an ID number, and query.list has no matching query, the agent should suggest → confirm → save → run, not conclude “exists / does not / how many” from table preview:

Ordinary members cannot save queries: give a SQL suggestion and ask them to contact a workspace admin or configure it in the Data integration form.

Also required:

#### Who may “manage predefined queries”?

Read vs change queries are separate: ticking Read under Who can use only means they can run existing predefined queries and table preview — not add or edit query definitions.

#### Three config entries (all admin)

#### Admin note (shared config)

Predefined queries live on the whole data connection and apply to members in the workspace already authorized to see that query. Changing or deleting a query affects every ask that depends on that query id. Maintain core metrics in Data integration, Save after changes (and Generate skill if you need the notes in sync).

---

Row and column policies (which rows and columns)

When the assistant is embedded in an existing business system (e.g. Human Resources), querying cannot rely only on “a skill says do not overreach” — configure row and column policies on the data connection; they are enforced at query time.

In the UI: open Data connections → edit a saved connection → Row and column policies.

Test

Save the data connection first, then test under Row and column policies. Pick a predefined query (or fill a table name), tick “also trial-run against the database”, then Enter in the account, table name, or any test-parameter box (IME Enter while picking a character does not fire).

Whose account to fill for simulated identity (business-system login, not a Cadau workspace member):

Cadau does not look up “who this manager’s reports are” in the business system. In a real embed, the report list comes with login identity; here you fill report numbers yourself, or change them in test parameters.

Several parameters: as many boxes as the query declares. Account-like parameters (account, login) prefill the login above; a manager’s employee-number parameters prefill “report numbers”. An empty box uses the policy’s expanded forced parameters.

Fill parameters with variables (same spelling as in the policy). You can fill a real DB value, or a whole box as a variable; trial-run expands from the current simulated identity:

Both spellings work: {{host_actor.external_user_id}} or a whole box host_actor.external_user_id. Occasional appearance in a sentence is not replaced. Unknown variable names expand empty. “Parameters actually used” shows expanded values.

Example: query has account and empNo: account = {{host_actor.external_user_id}}, empNo = a real number or host_actor.managed_employee_ids.

Whether to also change predefined queries: hiding columns (salary) does not require it. To narrow rows by person, the query SQL must already have matching filter parameters; if not, generating a policy auto-fills, or tap Fill predefined queries from policy. Fills are new queries (or only the ones the policy names) — other unnamed old queries are not rewritten.

Save the data connection first, then set policies. Embed scenes should also: require current login identity; if no rule matches, deny access.

Member grants (Who can use) decide “can they use this connection”; row and column policies decide “which rows and columns they see when they do”. Configure both.

---

Table preview and row limits

Table preview takes the first N rows (database default order), no filter. Good for recognizing fields and seeing samples — not a substitute for conditioned queries or full-table stats.

Note: a truncated tool result in chat may be the context character limit (unrelated to the SQL row cap). For more rows or aggregates, configure a predefined query instead of repeatedly raising table-preview limit.

A predefined query’s max_rows when empty uses the same default/cap; a single query can set max_rows in JSON (still not above the platform cap).

---

Are predefined queries required?

No.

With a connection, allowed tables, and member grants, the agent can see table structure and preview table data.

Predefined queries are an enhancement for common “ask numbers” scenes: freeze common SQL, then fetch by query id in chat instead of exploring from zero each time.

---

Predefined queries vs table notes in a skill

They cannot replace each other; they work together.

• A skill saying “employees has dept_name, status” helps the agent know which table to look at.
• “Which R&D employees are active” still needs a predefined query; table preview only shows the first unfiltered sample rows.

After saving a data connection, use Generate skill to write each predefined query’s purpose and parameters into a workspace skill so the agent picks the right query. If a skill was already generated, saving again when predefined queries changed auto-syncs the skill body; no backend restart.

---

Is more, more detailed queries always better?

No. Cover common phrasings and write each one clearly — do not pile similar entries.

Table preview fits: “what does this table roughly look like”, “what are the fields called”. Predefined queries fit: filter by condition, joins, aggregates, fixed business metrics.

---

When the workspace has several data connections

By default the agent in chat sees all data connections you are authorized for and picks from your question — more connections mean more chance of the wrong database or wrong predefined query.

Suggested combination (coarse to fine):

Typical: an HR assistant binds only the HR database and HR query skills; a finance assistant only finance — same workspace, different agents, each queries its own database.

Full notes: Skills and agents · Available data and skills.

---

Practical configuration tips

1. Queries by business scene — one per common phrasing (e.g. “active employees by department”, “orders in the last 30 days”), not one mechanical query per table.
2. Write names and descriptions — when to use it, which parameters.
3. Generate skill after save — so the agent knows which query; later query changes must Save (“Parse from document” only fills the form; save writes the store).
4. Parse from document — on the data-connection form tap Parse from document, paste business notes or Markdown (may include SQL); AI adds or updates predefined queries and merges with existing entries.
5. Narrow with data resources — in Data integration → Data resources / Who can use, let different roles see only related tables and queries.
6. Several connections: configure Available data and skills on a dedicated agent — see When the workspace has several data connections.
7. Samples: table preview; real asks: predefined queries.
8. Tap a card to edit on a full page — you can look at the query and tell the help assistant to add columns or change filters. Fill parameters and trial-run against the database (uses the current query, no need to save it first). Tap Done to write it back to this group, then Save the data connection.

---

Predefined query groups

Workspace admins can split predefined queries into several groups (no group-count cap), e.g. base metrics, a feature module, a customer customization.

Existing connections auto-land in a “Base” group; behavior matches the past. Save after changes.

If a software vendor generates JSON from this system’s list queries and feature modules then imports, see Vendor-generated predefined queries.

---

Predefined query JSON fields (admin)

On the Data connections form, each group is a JSON array. Main fields:

UI “?” help, Parse from document, and Smart check can generate or correct queries from Markdown/text; an AI service must be configured.

Smart check (data-connection form)

After Smart check, the system checks each predefined query in the currently selected group editor (many entries take longer — expected):

Note: save the connection to persist. Fullscreen edit and parse-from-document panels similar; long-task overlay sits on top of the page.

Common SQL placeholder mistakes

Example:

{
  "id": "staff_by_name",
  "name": "Employees by name",
  "sql": "SELECT empId, empName FROM eaemp WHERE empName = ?",
  "params": [{ "name": "empName", "type": "string", "required": true }],
  "max_rows": 100
}

---

Controlled data changes (optional)

Besides read-only queries, admins can configure insert / update / delete under Change definitions, and tick insert / update / delete for members under Who can use (read is separate).

Typical: a member describes data to register/change in Messages → the agent calls the matching change id → if approval is required it becomes a to-do, then writes the database after pass.

Changes, like read queries, are constrained by data resources and Who can use; without permission the agent should explain and stop.

---

Who can configure and use

Workspace admins can access all turned-on data connections by default; ordinary members only query the range ticked under Who can use. A turned-off connection can still be edited on the Data connections page, but chat cannot query it until it is turned on again.

---

Common questions

What’s the difference between turning a connection off and deleting it? Off: chat can’t query or change data through it; settings and grants stay, and you can turn it back on. Delete removes the connection and related access, and can’t be undone.

Can I skip predefined queries and only use table notes in a skill? Enough for “see samples, recognize structure”. For filters, stats, or a fixed metric, still configure predefined queries.

If a skill contains a full SELECT, does the agent run it? No. A skill is documentation; execution must go through a controlled tool (table preview or predefined query).

Does lots of queries always make chat faster? Not necessarily. Coverage and clear descriptions help more; too many similar queries can slow picking or pick wrong.

Why only a few hundred rows in table preview? A platform cap to protect the database and chat performance (default 200, max 500, configurable). For full volume or stats, configure a predefined query; do not answer “is there a duplicate name” or “how many in total” from the first N preview rows.

Smart check failed or is slow? Many entries call AI one by one — wait for the bar. On timeout, retry later or split into fewer entries. An AI service must be configured; SQL must use ? and params, not @param.

Is “no duplicate names” from table preview in chat reliable? No. Table preview is unfiltered first-N samples, not the whole database. Configure a predefined query (e.g. group-by name) or follow suggest → confirm → save → run above.

After exporting a skill or app, the other side has no predefined queries? The export pack tries to include used predefined-query definitions (not database accounts). On import, if the target workspace lacks a same-named query, a workspace admin can write them onto a data connection, or import first and fill Data integration by hand. If target tables differ, after write use Smart check or a real query.run.

Do I restart the backend after changing predefined queries? No. After Save on the data-connection form, the next message’s query.run uses the latest SQL. If you ever tapped Generate skill, the skill body also updates on save; without a generated skill the agent still sees the latest query ids in the tool list — only the docs may be thinner.

Changed a query but the agent still uses the old one? Common: ① form edited without Save; ② new query id not in the member’s data resource grant; ③ the agent still cites old context — send a new message or start a new conversation.

Several connections, the agent always queries the wrong database? First narrow what members see with Who can use; then on a dedicated assistant Overview → Available data and skills name connections (tick Only the resources above if needed); and Generate skill so it is clear which predefined query to use.

Can any member change predefined queries in chat? No. Only workspace admins can add/change/delete predefined queries in chat or the Data integration form. Ordinary members with data-resource read can only run existing queries.

Does read permission include changing queries? No. Read is for querying; changing query definitions needs admin. If a member says “save this query” in chat, the agent should say an admin must do it, or guide to Data integration / the help agent.

Can ordinary members change predefined-query JSON on the web form? No. The Data integration form is Save-able only by workspace admins.

---

Related docs

• Skills and agents · Available data and skills — limit or prefer data connections and skills per agent
• How to write workspace skills — query-type skills with predefined queries
• Script execution and member grants — another capability-pack grant model
• Server configuration — platform master switch (ops)
• Workspace capability packs — capability packs and data_source_invoke gating (implementation)