configure the nl2sql service

Users often phrase queries in natural language — "Which exemplary students are in Class 3, Grade 1?" or "What are the top 5 causes for closed cases in 2024?" — but your data lives in SQL tables. The NL2SQL service bridges this gap by translating natural language queries into SQL statements, so users get accurate answers without knowing SQL.

This page walks you through creating a service configuration that covers your table schema, learning samples, and business term definitions.

How it works

A complete NL2SQL configuration has three components, each targeting a different reason a query might fail:

Component	What it does	When to add it
Basic table information	Describes each table and column — names, types, sample values, value mappings, and table joins — so the model understands your data structure	Required for every configuration
Learning samples	Pairs a natural language question with the correct SQL so the model learns query patterns unique to your data	Add examples for complex queries, or to correct SQL that the service generated incorrectly
Custom rules	Maps business terms and internal concepts to their SQL conditions so the model resolves domain-specific vocabulary	Add rules when users ask questions using terms the model would not otherwise recognize

Tip: Field descriptions directly affect SQL accuracy. A column named amt_ttl_pre_dsc gives the model no context; a description like "Total amount before discount" lets it generate correct filters and aggregations. Write descriptions as if explaining the column to a new team member.

Prerequisites

Before you begin, ensure that you have:

Access to the AI Search Open Platform
The business data tables you want to expose to natural language queries

Step 1: Create a service configuration

In the AI Search Open Platform, go to Model Service > Service Configuration and click Create.
Keep the default values for Service Category and Configuration Type.
Enter a Configuration Name that reflects your use case — for example, student_info_analysis for student data analytics.
Click Save and Next.

Step 2: Define your data tables

Configure the tables the NL2SQL service queries against. Provide a basic table configuration and, if your queries span multiple tables, a table join configuration.

Basic table configuration

List each table and its columns in the following JSON format:

[
  {
    "table": "schools",
    "columns": [
      {
        "column": "class",
        "description": "Class",
        "type": "string",
        "example": ["Class 3, Grade 1", "Accelerated Class"],
        "value_mapping": []
      },
      {
        "column": "school",
        "description": "School",
        "type": "string",
        "example": ["High School B in City A", "AA No. 5 High School"],
        "value_mapping": []
      }
    ]
  },
  {
    "table": "students",
    "columns": [
      {
        "column": "id",
        "description": "Student ID",
        "type": "int",
        "example": [1, 2],
        "value_mapping": [
          [1, "Zhang San"],
          [2, "Li Si"]
        ]
      },
      {
        "column": "class",
        "description": "Class",
        "type": "string",
        "example": ["Class 3, Grade 1", "Accelerated Class"],
        "value_mapping": []
      }
    ]
  }
]

Naming constraints

Both table and column names must:

Start with a lowercase letter
Contain only lowercase letters, numbers, and underscores (_)
Not exceed 30 characters

Supported `type` values

text, string, int8, uint8, int16, uint16, int32, int, uint32, int64, uint64, float, double, location, date, time, timestamp

Table join configuration (if applicable)

Specify join conditions as equality expressions between columns of two tables:

["students.class=schools.class"]

Click Next when done.

Step 3: Add learning samples and custom rules

Use this step to improve accuracy for your specific queries.

Learning samples

Add question-SQL pairs for queries that are complex or that the model answers incorrectly. Write each question the way a user would naturally ask it.

[
  {
    "query": "Which class is Zhang San in?",
    "sql": "SELECT class FROM students WHERE name = 'Zhang San'"
  }
]

Custom rule mapping

Map business terms and internal concepts to their SQL conditions. For example, if your organization defines "exemplary students" as students with an ID of 10 or lower:

[
  {
    "key": "Exemplary student",
    "value": "students.id <= 10"
  },
  {
    "key": "Student athlete",
    "value": "students.id > 11"
  }
]

With this rule in place, a query like "Which exemplary students are in Class 3, Grade 1?" resolves correctly without the user needing to know the underlying ID range.

Step 4: Activate the configuration

Click OK, then click Activate Now. You are redirected to the service configuration list.
The activation status changes to Activating while the system validates your configuration format.
When the status changes to Activated, the service is ready to use.

Test and iterate

Open the Experience Center and run natural language queries against your tables.

If a query returns unexpected SQL:

Compare the generated SQL against what you expected.
Add the question and the correct SQL as a learning sample in Step 3.
Re-activate the configuration and test again.

Repeat until the service produces consistent results for your key query patterns.

What's next

To call the NL2SQL service from your application, see the NL2SQL API.