Instruct on ClickHouse

Signed-off-by: Zhaoyuan (Ryan) Fu <[email protected]>

Author: fuzhaoyuan

.gitignore

@@ -109,4 +109,6 @@ Dockerfile.local
 security.properties
 *.crt
 *.key
-*~
+*~
+# MCP server configuration with credentials
+src/main/resources/application-mcp.properties

src/main/java/org/cbioportal/infrastructure/ai/tools/DatabaseQueryTools.java

@@ -37,11 +37,21 @@ public DatabaseQueryTools(@Qualifier("clickhouseDataSource") DataSource dataSour
               + "Use this to retrieve cancer genomics data including studies, patients, samples, mutations, and clinical information. "
               + "Only SELECT queries are allowed for security. "
               + "The database contains base tables and optimized derived tables (*_derived). "
+              + "CRITICAL - ClickHouse Syntax Requirements: "
+              + "1. Column names are CASE-SENSITIVE and stored in LOWERCASE (use 'cancer_study_id' NOT 'CANCER_STUDY_ID'). "
+              + "2. Table names are lowercase (use 'cancer_study' NOT 'CANCER_STUDY'). "
+              + "3. Always use lowercase in WHERE, JOIN, and SELECT clauses. "
+              + "4. If unsure about column names, use 'SELECT * FROM table LIMIT 1' first to see actual column names. "
               + "Returns formatted query results with clear explanations.")
   public String queryDatabase(
       @ToolParam(
               description =
-                  "SQL SELECT query to execute. Example: 'SELECT * FROM cancer_study LIMIT 10'")
+                  "SQL SELECT query to execute using ClickHouse syntax. "
+                      + "IMPORTANT: Use lowercase for ALL column and table names! "
+                      + "Examples: "
+                      + "'SELECT * FROM cancer_study LIMIT 10' (discover columns), "
+                      + "'SELECT cancer_study_id, name, type_of_cancer_id FROM cancer_study LIMIT 5' (specific columns), "
+                      + "'SELECT p.stable_id, s.stable_id FROM patient p JOIN sample s ON p.internal_id = s.patient_id LIMIT 5' (with JOIN)")
           String query,
       @ToolParam(
               description = "Maximum number of rows to return (optional, default: 100, max: 1000)",
@@ -96,20 +106,26 @@ public String queryDatabase(
         if (errorMsg.contains("Table") && errorMsg.contains("doesn't exist")) {
           return "Error: The specified table doesn't exist. "
               + "Use the listTables tool to see available tables, "
-              + "or check the table name spelling.";
-        } else if (errorMsg.contains("Unknown column")) {
+              + "or check the table name spelling (remember: use lowercase).";
+        } else if (errorMsg.contains("Unknown column") || errorMsg.contains("Unknown identifier")) {
           return "Error: Unknown column in the query. "
-              + "Use the getTableSchema tool to see available columns for the table.";
-        } else if (errorMsg.contains("syntax")) {
-          return "Error: SQL syntax error. Please check the query structure. "
+              + "ClickHouse column names are CASE-SENSITIVE and stored in lowercase! "
+              + "Use 'SELECT * FROM table LIMIT 1' to see actual column names, "
+              + "or use the getTableSchema tool. "
+              + "Example: use 'cancer_study_id' instead of 'CANCER_STUDY_ID'.";
+        } else if (errorMsg.contains("syntax") || errorMsg.contains("bad SQL grammar")) {
+          return "Error: SQL syntax error. "
+              + "Common issue: ClickHouse requires lowercase column names! "
+              + "Use 'SELECT * FROM table LIMIT 1' first to see the correct column names. "
               + "Error details: "
               + errorMsg;
         }
       }
 
       return "Error executing query: "
           + errorMsg
-          + "\nTip: Use getTableSchema to verify table structure before querying.";
+          + "\n\nClickHouse Reminder: Column names are case-sensitive and stored in lowercase. "
+          + "Try 'SELECT *' first to see actual column names.";
     }
   }
 

src/main/java/org/cbioportal/infrastructure/ai/tools/DatabaseSchemaTools.java

@@ -34,7 +34,9 @@ public class DatabaseSchemaTools {
           "Get the schema definition (CREATE TABLE statement) for a specific database table. "
               + "Use this tool when you need to understand the structure, columns, data types, or relationships "
               + "of a table before writing a query. "
-              + "Tables are available in the ClickHouse database. Many tables also exist in MySQL with the same structure.")
+              + "IMPORTANT: This shows the original MySQL schema definition. "
+              + "In ClickHouse, column names are stored in LOWERCASE. "
+              + "When querying, always use lowercase column names (e.g., 'cancer_study_id' not 'CANCER_STUDY_ID').")
   public String getTableSchema(
       @ToolParam(
               description =
@@ -65,7 +67,12 @@ public String getTableSchema(
             tableName);
       }
 
-      return String.format("Schema for table '%s' (ClickHouse database):\n\n%s", tableName, schema);
+      return String.format(
+          "Schema for table '%s' (ClickHouse database):\n\n%s\n\n"
+              + "⚠️  IMPORTANT: In ClickHouse, all column names are stored in LOWERCASE.\n"
+              + "When writing queries, use lowercase column names (e.g., 'cancer_study_id' not 'CANCER_STUDY_ID').\n"
+              + "The schema above shows the original MySQL definition with uppercase, but queries must use lowercase.",
+          tableName, schema);
 
     } catch (Exception e) {
       logger.error("Error retrieving schema for table: {}", tableName, e);

src/main/resources/application-mcp.properties

@@ -22,9 +22,9 @@ spring.ai.mcp.server.version=1.0.0
 # =====================================================
 # ClickHouse Database Configuration
 # =====================================================
-spring.datasource.clickhouse.url=
-spring.datasource.clickhouse.username=
-spring.datasource.clickhouse.password=
+spring.datasource.clickhouse.url=jdbc:ch:https://YOUR_CLICKHOUSE_HOST:8443/YOUR_DATABASE?zeroDateTimeBehavior=convertToNull
+spring.datasource.clickhouse.username=YOUR_USERNAME
+spring.datasource.clickhouse.password=YOUR_PASSWORD
 spring.datasource.clickhouse.driver-class-name=com.clickhouse.jdbc.ClickHouseDriver
 
 # Connection pool settings for fast startup