Natural Language Query

dataset_nl.query is an intelligent query tool for regular users, supporting natural language to describe data requirements.

Basic Information

• Tool Name: dataset_nl.query
• Category: Natural Language
• Permission: Admin, Business

Core Features

• Natural Language Understanding: Describe query requirements in plain language, no technical knowledge needed
• Smart Chart Generation: Automatically generate trend charts, comparison charts, pie charts
• Multi-step Analysis: Automatically decompose complex problems, intelligently integrate results
• Context Memory: Supports continuous conversation and follow-up questions

Parameters

Parameter	Type	Required	Description
query	string	✅	Natural language query content
session_id	string	❌	Session ID for context association
cursor	string	❌	Pagination cursor
format	string	❌	Output format: table/json/summary
hints	object	❌	Query optimization hints
stream	boolean	❌	Enable streaming response (default true)

hints Parameter

{
  "hints": {
    "prefer_model": "FactSalesQueryModel",
    "prefer_fields": ["customerName", "totalAmount"],
    "time_range": "last_7_days"
  }
}

Query Types

Detail Query

Query customer information
Find enterprise customers in Beijing
Show the last 10 orders

Statistical Query

Count orders by team
Calculate total sales by region
Count products by category

Trend Analysis

Shipment trend for the past week
Sales changes over the last 30 days
Daily order volume this month

→ Automatically generates LINE chart

Comparison Analysis

Compare performance across outlets
Order volume by customer type
Sales comparison by department

→ Automatically generates BAR chart

Proportion Analysis

Sales proportion by region
Customer type distribution
Payment method proportion

→ Automatically generates PIE chart

Usage Examples

Basic Query

{
  "query": "Query sales data for the last week"
}

Query with Session

{
  "query": "Break it down by customer type",
  "session_id": "session_123"
}

Paginated Query

{
  "query": "Query customer list",
  "cursor": "eyJvZmZzZXQiOjEwMH0="
}

MCP Protocol Call

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/call",
  "params": {
    "name": "dataset_nl.query",
    "arguments": {
      "query": "Calculate this month's sales by product category",
      "format": "table"
    }
  }
}

Response Format

Success Response

{
  "type": "result",
  "items": [
    {"category": "Electronics", "totalSales": 125000},
    {"category": "Clothing", "totalSales": 89000}
  ],
  "total": 5,
  "summary": "Found 5 categories, Electronics has highest sales",
  "exports": {
    "charts": [
      {
        "url": "https://chart.example.com/sales.png",
        "type": "BAR",
        "title": "This Month's Sales by Category",
        "format": "PNG",
        "width": 800,
        "height": 600,
        "expiresAt": "2025-01-08T12:00:00Z"
      }
    ]
  },
  "hasNext": false,
  "nextCursor": null
}

Response Fields

Field	Description
type	Response type: result / error / info
items	Data record array
total	Total record count
summary	Result summary
exports.charts	Generated charts array
hasNext	Has next page
nextCursor	Next page cursor

Smart Charts

System automatically selects chart type based on query:

Query Type	Chart Type
Trend Analysis	Line Chart (LINE)
Category Statistics	Bar Chart (BAR)
Proportion Analysis	Pie Chart (PIE)
Correlation Analysis	Scatter Chart (SCATTER)

Chart titles are automatically generated by AI with business meaning:

• "Shipment trend for the past week" → "Weekly Shipment Trend Chart"
• "Statistics by customer type" → "Customer Type Distribution Chart"

Multi-step Analysis

System can automatically decompose complex problems:

Example: "Find the top 10 customers by shipments this month, analyze their annual shipment volume"

1. Query top 10 customers by shipments this month
2. Get these customers' annual order data
3. Generate comparison analysis and charts

Next Steps

• Metadata Tools - Get model and field info
• Query Tools - Structured queries
• Tools Overview - Return to tools list