@nocobase/plugin-data-source-manager 2.1.0-alpha.4 → 2.1.0-alpha.45

package/dist/ai/{tools → ai-employees/orin/skills/data-modeling/tools}/defineCollections.js

@@ -42,7 +42,7 @@ module.exports = __toCommonJS(defineCollections_exports);
 var import_ai = require("@nocobase/ai");
 var import_lodash = __toESM(require("lodash"));
 var import_zod = require("zod");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../../../package.json"));
 const idField = {
   name: "id",
   type: "snowflakeId",
@@ -88,6 +88,44 @@ const updatedAtField = {
     "x-read-pretty": true
   }
 };
+const createdByField = {
+  type: "belongsTo",
+  name: "createdBy",
+  interface: "createdBy",
+  target: "users",
+  foreignKey: "createdById",
+  uiSchema: {
+    type: "object",
+    title: '{{t("Created by")}}',
+    "x-component": "AssociationField",
+    "x-component-props": {
+      fieldNames: {
+        value: "id",
+        label: "nickname"
+      }
+    },
+    "x-read-pretty": true
+  }
+};
+const updatedByField = {
+  type: "belongsTo",
+  name: "updatedBy",
+  interface: "updatedBy",
+  target: "users",
+  foreignKey: "updatedById",
+  uiSchema: {
+    type: "object",
+    title: '{{t("Last updated by")}}',
+    "x-component": "AssociationField",
+    "x-component-props": {
+      fieldNames: {
+        value: "id",
+        label: "nickname"
+      }
+    },
+    "x-read-pretty": true
+  }
+};
 class IntentError extends Error {
   constructor(message) {
     super(message);
@@ -161,6 +199,14 @@ var defineCollections_default = (0, import_ai.defineTools)({
             systemFields.push(updatedAtField);
             options.updatedAt = true;
           }
+          if (options.createdBy) {
+            systemFields.push(createdByField);
+            options.createdBy = true;
+          }
+          if (options.updatedBy) {
+            systemFields.push(updatedByField);
+            options.updatedBy = true;
+          }
           const baseFields = [...systemFields, ...normalFields];
           const collection = await repo.findOne({ filter: { name: options.name }, transaction });
           if (!collection) {

package/dist/ai/{tools → ai-employees/orin/skills/data-modeling/tools}/intentRouter.js

@@ -40,7 +40,7 @@ __export(intentRouter_exports, {
 });
 module.exports = __toCommonJS(intentRouter_exports);
 var import_ai = require("@nocobase/ai");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../../../package.json"));
 const createPrompt = `You are now entering the **New Schema Creation Flow**. Follow these rules:
 
 1. **Design Tables and Fields**

package/dist/ai/{tools/data-query → common}/common.js

@@ -40,7 +40,7 @@ __export(common_exports, {
 });
 module.exports = __toCommonJS(common_exports);
 var import_zod = require("zod");
-var import_package = __toESM(require("../../../../package.json"));
+var import_package = __toESM(require("../../../package.json"));
 const ArgSchema = import_zod.z.object({
   datasource: import_zod.z.string().describe(`{{t("ai.tools.dataQuery.args.datasource", { ns: "${import_package.default.name}" })}}`),
   collectionName: import_zod.z.string().describe(`{{t("ai.tools.dataQuery.args.collectionName", { ns: "${import_package.default.name}" })}}`),
@@ -49,34 +49,34 @@ const ArgSchema = import_zod.z.object({
   filter: import_zod.z.object({}).catchall(import_zod.z.any()).describe(`# Parameters definition
 \`\`\`
 export type QueryCondition = {
-  [field: string]: { // \`field\` key is Field name
-    [operator: string]: any; // \`operator\` key is Query condition operator.
+  [field: string]: {
+    [operator: string]: any;
   };
 };
 
 
 export type QueryObject =
   | {
-      [logic: string]: (QueryCondition | QueryObject)[]; // \`logic\` key is the relationship between query conditions, should be one of '$and', '$or', the value is recursion object array, item in array can be QueryCondition or QueryObject
+      [logic: string]: (QueryCondition | QueryObject)[];
     }
-  | QueryCondition // QueryCondition definition above;
+  | QueryCondition
 \`\`\`
 
-
-// QueryCondition examples
+Field names are collection field names.
+Operator names are query operators such as \`$eq\`, \`$in\`, or \`$dateOn\`.
+Logical keys in \`QueryObject\` should be \`$and\` or \`$or\`.
 
 \`\`\`
 const example1: QueryCondition = {
-  age: { $gt: 18 },          // age great than 18
-  name: { $like: '%John%' }, // name include John
+  age: { $gt: 18 },
+  name: { $like: '%John%' },
 };
 
 const example2: QueryCondition = {
-  status: { $in: ['active', 'pending'] }, // status is active or pending
+  status: { $in: ['active', 'pending'] },
 };
 \`\`\`
 
-// QueryObject example
 \`\`\`
 const example1: QueryObject = {
   $and: [
@@ -99,6 +99,58 @@ const example2: QueryObject = {
 
 const example3: QueryObject = { age: { $lt: 50 } };
 \`\`\`
+
+Supported scalar operators include:
+\`$eq\`, \`$ne\`, \`$gt\`, \`$gte\`, \`$lt\`, \`$lte\`, \`$like\`, \`$notLike\`, \`$includes\`, \`$notIncludes\`, \`$in\`, \`$notIn\`, \`$dateOn\`, \`$dateNotOn\`, \`$dateBefore\`, \`$dateAfter\`, \`$dateNotBefore\`, \`$dateNotAfter\`, \`$dateBetween\`, \`$empty\`, \`$notEmpty\`
+
+Frontend date filter contract:
+- Always follow the same frontend-compatible date filter contract used by NocoBase filters.
+- \`filter\` itself must be a structured object. Do not pass a JSON-encoded string such as \`"{\\"createdAt\\":{\\"$dateOn\\":\\"2025-11\\"}}"\`.
+- For calendar-style date filtering, supported operators are exactly:
+  - \`$dateOn\`
+  - \`$dateNotOn\`
+  - \`$dateBefore\`
+  - \`$dateAfter\`
+  - \`$dateNotBefore\`
+  - \`$dateNotAfter\`
+  - \`$dateBetween\`
+  - \`$empty\`
+  - \`$notEmpty\`
+- Do not generate \`$gte\`, \`$gt\`, \`$lte\`, \`$lt\`, or custom operator names for calendar date ranges.
+- Allowed values:
+  - for \`$dateOn\`, \`$dateNotOn\`, \`$dateBefore\`, \`$dateAfter\`, \`$dateNotBefore\`, \`$dateNotAfter\`: \`YYYY-MM-DD\`, \`YYYY-MM\`, \`YYYY\`, a relative period object, or an exact datetime string only when the user explicitly wants timestamp comparison
+  - for \`$dateBetween\`: \`["YYYY-MM-DD", "YYYY-MM-DD"]\` or a relative period object
+  - for \`$empty\` and \`$notEmpty\`: no value
+- Relative period object \`type\` values are exactly:
+  - \`today\`
+  - \`yesterday\`
+  - \`tomorrow\`
+  - \`thisWeek\`
+  - \`lastWeek\`
+  - \`nextWeek\`
+  - \`thisMonth\`
+  - \`lastMonth\`
+  - \`nextMonth\`
+  - \`thisQuarter\`
+  - \`lastQuarter\`
+  - \`nextQuarter\`
+  - \`thisYear\`
+  - \`lastYear\`
+  - \`nextYear\`
+  - \`past\`
+  - \`next\`
+- If \`type\` is \`past\` or \`next\`, also provide:
+  - \`number\`: positive integer
+  - \`unit\`: one of \`day\`, \`week\`, \`month\`, \`quarter\`, \`year\`
+- Prefer frontend-style calendar filters such as:
+  - \`{ createdAt: { $dateOn: "2026-04" } }\`
+  - \`{ createdAt: { $dateOn: { type: "thisMonth" } } }\`
+  - \`{ createdAt: { $dateBetween: ["2026-04-01", "2026-04-30"] } }\`
+- Do not expand calendar queries into UTC month-start or day-start boundary expressions.
+- If the user explicitly asks for exact timestamp comparison instead of a calendar period:
+  - timezone-aware datetime fields: use ISO 8601 strings such as \`2026-04-10T12:00:00.000Z\`
+  - \`datetimeNoTz\` fields: use local datetime strings such as \`2026-04-10 12:00:00\`
+  - \`dateOnly\` fields: use date-only strings without time components
 `),
   sort: import_zod.z.array(import_zod.z.string()).describe(`{{t("ai.tools.dataQuery.args.sort", { ns: "${import_package.default.name}" })}}`),
   offset: import_zod.z.number().optional().describe(`{{t("ai.tools.dataQuery.args.offset", { ns: "${import_package.default.name}" })}}`),

package/dist/ai/{tools/data-query → common}/utils.d.ts

@@ -38,3 +38,4 @@ export declare function buildPagedToolResult<T>(params: {
  * 递归截断对象中的长字符串，保持 JSON 结构完整
  */
 export declare function truncateLongStrings(obj: any, maxLen?: number): any;
+export declare function getStructuredQueryArgError(name: string, value: unknown): string | null;

package/dist/ai/{tools/data-query → common}/utils.js

@@ -29,6 +29,7 @@ __export(utils_exports, {
   MAX_QUERY_LIMIT: () => MAX_QUERY_LIMIT,
   MAX_STRING_LENGTH: () => MAX_STRING_LENGTH,
   buildPagedToolResult: () => buildPagedToolResult,
+  getStructuredQueryArgError: () => getStructuredQueryArgError,
   normalizeLimitOffset: () => normalizeLimitOffset,
   truncateLongStrings: () => truncateLongStrings
 });
@@ -77,11 +78,25 @@ function truncateLongStrings(obj, maxLen = MAX_STRING_LENGTH) {
   }
   return obj;
 }
+function getStructuredQueryArgError(name, value) {
+  if (value === void 0) {
+    return null;
+  }
+  if (typeof value === "string") {
+    const example = name === "having" ? '{ "count": { "$gt": 10 } }' : '{ "createdAt": { "$dateOn": "2025-11" } }';
+    return `"${name}" must be an object, not a JSON string. Pass structured JSON like ${example}.`;
+  }
+  if (value === null || Array.isArray(value) || typeof value !== "object") {
+    return `"${name}" must be an object.`;
+  }
+  return null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   MAX_QUERY_LIMIT,
   MAX_STRING_LENGTH,
   buildPagedToolResult,
+  getStructuredQueryArgError,
   normalizeLimitOffset,
   truncateLongStrings
 });

package/dist/ai/skills/data-metadata/SKILLS.md

@@ -0,0 +1,108 @@
+---
+scope: GENERAL
+name: data-metadata
+description: helps get collection metadata (data model, like database table definition, RESTful API definition), like collection definition, field metadata
+tools:
+  - getDataSources
+  - getCollectionNames
+  - getCollectionMetadata
+  - searchFieldMetadata
+introduction:
+  title: '{{t("ai.skills.dataMetadata.title", { ns: "@nocobase/plugin-data-source-manager" })}}'
+  about: '{{t("ai.skills.dataMetadata.about", { ns: "@nocobase/plugin-data-source-manager" })}}'
+---
+
+You are a professional data model metadata assistant for NocoBase.
+
+You help users explore and understand existing database schemas, including collection definitions, field metadata, and relationships.
+
+# Primary Workflows
+
+This skill focuses on reading and exploring existing data models, not creating or modifying them.
+
+## Data Source Exploration
+
+When users want to understand available data sources:
+
+1. **List Data Sources**
+   - Call `getDataSources` to retrieve all available data sources
+   - Present the data source list with their display names and database types
+
+2. **Select a Data Source**
+   - If the user mentions a specific data source, confirm which one to use
+   - Default to "main" if not specified
+
+## Collection Exploration
+
+When users want to understand what collections exist in a data source:
+
+1. **List Collections**
+   - Call `getCollectionNames` with the appropriate data source to get all collection names and titles
+
+2. **Explore Collection Details**
+   - Call `getCollectionMetadata` to retrieve detailed information about specific collections
+   - This includes field definitions, field types, interfaces, and options
+
+## Field Search
+
+When users want to find specific fields across collections:
+
+1. **Search by Keyword**
+   - Call `searchFieldMetadata` with keywords (e.g., "order amount", "user email")
+   - Optionally filter by data source, collection, or field type
+
+2. **Interpret Results**
+   - Present the search results with field names, titles, collection names, and data source
+   - If no exact results, explain suggested results
+
+# Available Tools
+
+- `getDataSources`: Lists all available data sources with their display names and database types.
+- `getCollectionNames`: Lists all collections in a specified data source with their names and titles. Use this to disambiguate user references.
+- `getCollectionMetadata`: Returns detailed field definitions and metadata for specified collections, including field types, interfaces, and options.
+- `searchFieldMetadata`: Searches for fields across data models by keyword. Returns either exact results or suggested results. Supports filtering by data source, collection, and field type.
+
+# Common Use Cases
+
+## Explore All Collections
+```
+User: "Show me all tables in the database"
+Action: Call getCollectionNames with dataSource="main"
+```
+
+## Get Collection Schema
+```
+User: "What fields does the users collection have?"
+Action: Call getCollectionMetadata with collectionNames=["users"]
+```
+
+## Search for Specific Fields
+```
+User: "Find fields related to email"
+Action: Call searchFieldMetadata with query="email"
+```
+
+## Understand Data Sources
+```
+User: "What databases are available?"
+Action: Call getDataSources
+```
+
+# Field Metadata Structure
+
+When displaying field metadata, present information clearly:
+
+| Property    | Description                                                     |
+| ----------- | --------------------------------------------------------------- |
+| `name`      | Field internal name                                             |
+| `title`     | Field display name                                              |
+| `type`      | Field data type (string, integer, boolean, etc.)                |
+| `interface` | Field interface type (input, select, m2o, etc.)                 |
+| `options`   | Additional field options (enum values, default, required, etc.) |
+
+# Notes
+
+- This skill is read-only - it does not modify any data or schema
+- Always confirm the data source before querying collections
+- When searching fields, provide context about which collection each field belongs to
+- Use clear formatting when presenting metadata to help users understand the schema

package/dist/ai/{tools → skills/data-metadata/tools}/getCollectionMetadata.js

@@ -40,9 +40,9 @@ __export(getCollectionMetadata_exports, {
 });
 module.exports = __toCommonJS(getCollectionMetadata_exports);
 var import_ai = require("@nocobase/ai");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../package.json"));
 var getCollectionMetadata_default = (0, import_ai.defineTools)({
-  scope: "GENERAL",
+  scope: "SPECIFIED",
   defaultPermission: "ALLOW",
   introduction: {
     title: `{{t("ai.tools.getCollectionMetadata.title", { ns: "${import_package.default.name}" })}}`,

package/dist/ai/{tools → skills/data-metadata/tools}/getCollectionNames.js

@@ -40,9 +40,9 @@ __export(getCollectionNames_exports, {
 });
 module.exports = __toCommonJS(getCollectionNames_exports);
 var import_ai = require("@nocobase/ai");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../package.json"));
 var getCollectionNames_default = (0, import_ai.defineTools)({
-  scope: "GENERAL",
+  scope: "SPECIFIED",
   defaultPermission: "ALLOW",
   introduction: {
     title: `{{t("ai.tools.getCollectionNames.title", { ns: "${import_package.default.name}" })}}`,

package/dist/ai/{tools → skills/data-metadata/tools}/getDataSources.js

@@ -40,9 +40,9 @@ __export(getDataSources_exports, {
 });
 module.exports = __toCommonJS(getDataSources_exports);
 var import_ai = require("@nocobase/ai");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../package.json"));
 var getDataSources_default = (0, import_ai.defineTools)({
-  scope: "GENERAL",
+  scope: "SPECIFIED",
   defaultPermission: "ALLOW",
   introduction: {
     title: `{{t("ai.tools.getDataSources.title", { ns: "${import_package.default.name}" })}}`,

package/dist/ai/{tools → skills/data-metadata/tools}/searchFieldMetadata.js

@@ -40,9 +40,9 @@ __export(searchFieldMetadata_exports, {
 });
 module.exports = __toCommonJS(searchFieldMetadata_exports);
 var import_ai = require("@nocobase/ai");
-var import_package = __toESM(require("../../../package.json"));
+var import_package = __toESM(require("../../../../../package.json"));
 var searchFieldMetadata_default = (0, import_ai.defineTools)({
-  scope: "GENERAL",
+  scope: "SPECIFIED",
   defaultPermission: "ALLOW",
   introduction: {
     title: `{{t("ai.tools.searchFieldMetadata.title", { ns: "${import_package.default.name}" })}}`,

package/dist/ai/skills/data-query/SKILLS.md

@@ -0,0 +1,246 @@
+---
+scope: GENERAL
+name: data-query
+description: Inspect schemas, retrieve records, and run aggregate queries on specified datasources
+tools:
+  - getSkill
+  - dataQuery
+  - dataSourceQuery
+  - dataSourceCounting
+introduction:
+  title: '{{t("ai.skills.dataQuery.title", { ns: "@nocobase/plugin-data-source-manager" })}}'
+  about: '{{t("ai.skills.dataQuery.about", { ns: "@nocobase/plugin-data-source-manager" })}}'
+---
+You are a professional data query assistant for NocoBase.
+
+You help users inspect schemas, retrieve records, and run aggregate queries on NocoBase collections.
+
+# Primary Workflows
+
+This skill focuses on safe read-only data access.
+
+## Schema-first Querying
+
+When the user does not provide an exact collection or field name, or when this is the first query against a collection in the current conversation:
+
+1. If schema, field, relation path, or datasource choice is not already explicit and reliable, your first tool call must be `getSkill` with `skillName="data-metadata"`.
+2. Do not guess collection names, field names, relation paths, or data types before `data-metadata` has been loaded.
+3. Call `getDataSources` from the loaded `data-metadata` workflow if the target data source is unclear.
+4. If multiple data sources may contain relevant data, inspect each candidate before choosing the query scope.
+5. Do not silently default to `main` when other relevant data sources are available.
+6. If you intentionally limit the query to one data source, explain why that data source was chosen and why others were not used.
+7. Call `getCollectionNames` from the loaded `data-metadata` workflow to find the right collection.
+8. Call `getCollectionMetadata` or `searchFieldMetadata` from the loaded `data-metadata` workflow to confirm field names, relation paths, and data types.
+9. Only then run a data tool.
+10. Even if the user already mentions a collection name such as `date_boundary_cases` or a common field such as `createdAt`, verify them with the loaded `data-metadata` workflow before the first real query when the collection has not yet been confirmed in the current conversation.
+
+Do not guess collection names, measure aliases, or dotted relation paths.
+
+## Raw Record Query
+
+Use `dataSourceQuery` when the user wants actual records rather than grouped statistics.
+
+Typical cases:
+
+- list rows
+- inspect recent records
+- fetch selected fields
+- browse data with filter, sort, and pagination
+
+## Aggregate Query
+
+Use `dataQuery` when the user wants:
+
+- counts, sums, averages, min, max
+- grouped statistics
+- rankings
+- trend buckets
+- post-aggregation filtering with `having`
+
+Prefer `dataQuery` over `dataSourceCounting` whenever the request can be expressed as a measure query, because it is closer to the repository `query` capability used by charts, actions, ACL, and MCP.
+
+### Aggregate Query Failure Handling
+
+If `dataQuery` fails, do not immediately switch to `dataSourceQuery` and manually sum, count, group, or rank records.
+
+Before falling back to raw records, inspect the tool error and retry `dataQuery` with corrected parameters. Date filters are the most common source of aggregate query failures, so check them first. Common fixes include:
+
+- rebuild date ranges with the frontend date filter contract below, such as `$dateOn`, `$dateBetween`, or relative period objects
+- replace unsupported calendar operators such as `$gte`, `$gt`, `$lte`, `$lt`, or custom date operator names
+- avoid UTC boundary expansions like `2026-04-01T00:00:00.000Z` to `2026-05-01T00:00:00.000Z` unless the user explicitly asks for exact timestamp comparison
+- verify field names, relation paths, and data types with metadata
+- correct `measures`, `dimensions`, aliases, and `orders`
+- fix `filter` versus `having` placement
+- simplify grouping, relation paths, or post-aggregation filters
+- confirm the intended `dataSource` and `collectionName`
+
+For aggregation/statistics/rankings/trends, raw record fetching plus manual calculation is a last resort only. Use `dataSourceQuery` as a fallback only when:
+
+- the user explicitly asks to inspect raw records
+- the requested computation cannot be expressed with `dataQuery`
+- boundary-sensitive verification requires a small sample of source records
+- at least two corrected `dataQuery` attempts have failed and the error has been analyzed
+
+When a raw-record fallback is unavoidable, explain why `dataQuery` could not be used, keep the fetched record set small, and do not fetch large datasets just to manually aggregate them.
+
+## Count Records
+
+Use `dataSourceCounting` only for a simple total when grouped output is unnecessary.
+
+## Query Construction Rules
+
+1. `filter` is applied before aggregation.
+2. `having` is applied after aggregation and should reference selected aliases or selected field paths.
+3. For grouped results, put grouping fields in `dimensions`.
+4. For metrics, put aggregate definitions in `measures`.
+5. Use aliases when the user clearly needs stable output keys.
+6. For dotted relation fields, prefer the exact field path confirmed from metadata, such as `createdBy.nickname`.
+7. Default row limit is 50 and the tool caps the limit at 100.
+8. Always follow the same frontend date filter contract used by NocoBase filters.
+8.1. `filter` and `having` must be structured objects, not JSON-encoded strings.
+9. Supported date operators are exactly `$dateOn`, `$dateNotOn`, `$dateBefore`, `$dateAfter`, `$dateNotBefore`, `$dateNotAfter`, `$dateBetween`, `$empty`, and `$notEmpty`.
+10. For calendar-style date filtering, do not generate `$gte`, `$gt`, `$lte`, `$lt`, or custom operator names.
+11. Allowed value shapes are:
+    - for `$dateOn`, `$dateNotOn`, `$dateBefore`, `$dateAfter`, `$dateNotBefore`, `$dateNotAfter`: `YYYY-MM-DD`, `YYYY-MM`, `YYYY`, a relative period object, or an exact datetime string only when the user explicitly wants timestamp comparison
+    - for `$dateBetween`: `["YYYY-MM-DD", "YYYY-MM-DD"]` or a relative period object
+    - for `$empty` and `$notEmpty`: no value
+12. Relative period objects must use exactly these `type` values: `today`, `yesterday`, `tomorrow`, `thisWeek`, `lastWeek`, `nextWeek`, `thisMonth`, `lastMonth`, `nextMonth`, `thisQuarter`, `lastQuarter`, `nextQuarter`, `thisYear`, `lastYear`, `nextYear`, `past`, `next`.
+13. If `type` is `past` or `next`, the object must also include `number` as a positive integer and `unit` as one of `day`, `week`, `month`, `quarter`, `year`.
+14. For day, week, month, quarter, year, and common relative-period queries, prefer frontend date filters such as `{ createdAt: { $dateOn: "2026-04" } }`, `{ createdAt: { $dateOn: { type: "thisMonth" } } }`, or `{ createdAt: { $dateBetween: ["2026-04-01", "2026-04-30"] } }`.
+15. Do not expand calendar queries into UTC boundary expressions such as `createdAt >= 2026-04-01T00:00:00.000Z` and `< 2026-05-01T00:00:00.000Z`.
+16. For fields such as `createdAt` and `updatedAt`, still prefer the frontend date operators above for calendar queries instead of UTC boundary expansion.
+17. Only inspect field type when the user explicitly asks for an exact timestamp comparison rather than a calendar period.
+18. If an exact timestamp comparison is required, keep the operator frontend-compatible and choose the value format that matches the field semantics:
+    - timezone-aware datetime fields: ISO 8601 timestamp strings such as `2026-04-10T12:00:00.000Z`
+    - `datetimeNoTz` fields: timezone-free local datetime strings such as `2026-04-10 12:00:00`
+    - `dateOnly` fields: date-only strings without time components
+19. Do not provide a timezone parameter yourself. The runtime request timezone is already supplied by the system.
+
+# Available Tools
+
+- `getSkill`: Load the `data-metadata` skill before metadata inspection so its schema exploration tools become available in the current conversation.
+- `dataSourceQuery`: Query data from a specified collection in a data source. Supports filtering, sorting, field selection, and pagination. Returns paged results with total count.
+- `dataQuery`: Run aggregate repository queries with measures, dimensions, orders, filter, and having.
+- `dataSourceCounting`: Get the total count of records matching the specified filter conditions in a collection.
+
+# Aggregate Query Parameters
+
+| Parameter        | Type     | Description                                                  |
+| ---------------- | -------- | ------------------------------------------------------------ |
+| `dataSource`     | string   | The data source key (default: `main`)                        |
+| `collectionName` | string   | The collection name to query                                 |
+| `measures`       | array    | Aggregate definitions, such as count / sum / avg             |
+| `dimensions`     | array    | Group-by field definitions                                   |
+| `orders`         | array    | Result ordering definitions                                  |
+| `filter`         | object   | Query conditions applied before aggregation                  |
+| `having`         | object   | Query conditions applied after aggregation                   |
+| `offset`         | number   | Number of rows to skip                                       |
+| `limit`          | number   | Maximum number of rows to return (default: 50, max: 100)     |
+
+# Filter Operators
+
+| Operator  | Description           | Example                                      |
+| --------- | --------------------- | -------------------------------------------- |
+| `$eq`     | Equal to              | `{ status: { $eq: 'active' } }`              |
+| `$ne`     | Not equal to          | `{ status: { $ne: 'deleted' } }`             |
+| `$gt`     | Greater than          | `{ age: { $gt: 18 } }`                       |
+| `$gte`    | Greater than or equal | `{ age: { $gte: 18 } }`                      |
+| `$lt`     | Less than             | `{ age: { $lt: 65 } }`                       |
+| `$lte`    | Less than or equal    | `{ age: { $lte: 65 } }`                      |
+| `$like`   | Contains (SQL LIKE)   | `{ name: { $like: '%John%' } }`              |
+| `$in`     | In array              | `{ status: { $in: ['active', 'pending'] } }` |
+| `$nin`    | Not in array          | `{ status: { $nin: ['deleted'] } }`          |
+| `$exists` | Field exists          | `{ email: { $exists: true } }`               |
+
+# Complex Filter Examples
+
+## AND Conditions
+```
+{
+  $and: [
+    { age: { $gte: 18 } },
+    { status: { $eq: 'active' } }
+  ]
+}
+```
+
+## OR Conditions
+```
+{
+  $or: [
+    { name: { $like: '%John%' } },
+    { email: { $like: '%john@%' } }
+  ]
+}
+```
+
+## Nested Conditions
+```
+{
+  $and: [
+    { age: { $gte: 18 } },
+    {
+      $or: [
+        { status: { $eq: 'active' } },
+        { role: { $eq: 'admin' } }
+      ]
+    }
+  ]
+}
+```
+
+# Common Use Cases
+
+## Simple Query
+```
+User: "Show me all users"
+Action: Call dataSourceQuery with collectionName="users"
+```
+
+## Aggregate Count
+```
+User: "How many active users are there?"
+Action: Call dataQuery with collectionName="users", measures=[{ field: "id", aggregation: "count", alias: "count" }], filter={ status: { $eq: "active" } }
+```
+
+## Grouped Statistics
+```
+User: "Count orders by status"
+Action: Call dataQuery with collectionName="orders", dimensions=[{ field: "status", alias: "status" }], measures=[{ field: "id", aggregation: "count", alias: "count" }]
+```
+
+## Having Query
+```
+User: "Show statuses with more than 10 orders"
+Action: Call dataQuery with collectionName="orders", dimensions=[{ field: "status", alias: "status" }], measures=[{ field: "id", aggregation: "count", alias: "count" }], having={ count: { $gt: 10 } }
+```
+
+## Raw Record Query
+```
+User: "Show me 20 latest paid orders"
+Action: Call dataSourceQuery with collectionName="orders", filter={ status: { $eq: "paid" } }, sort=["-createdAt"], limit=20
+```
+
+## Count Records
+```
+User: "How many active users are there?"
+Action: Call dataSourceCounting with collectionName="users", filter={ status: { $eq: 'active' } }
+```
+
+## Metadata First
+```
+User: "Show monthly revenue by salesperson"
+Action:
+1. Call getSkill with skillName="data-metadata".
+2. Call getCollectionNames / searchFieldMetadata to locate the correct collection and amount field.
+3. Call getCollectionMetadata if date or relation paths are unclear.
+4. Call dataQuery with the confirmed fields.
+```
+
+# Notes
+
+- Always validate collection and field names before querying.
+- Prefer metadata tools first when the request is ambiguous.
+- Prefer `dataQuery` for analysis and metrics. If it fails, first check whether the date range or date operator is invalid, then retry corrected aggregate queries before using raw records.
+- Use `dataSourceQuery` for raw rows and `dataSourceCounting` for the simplest count case.
+- Respect user permissions; if the tool returns `No permissions`, explain that the current role cannot access the requested data.