Upload schema_tool.txt

schema_tool.txt

@@ -0,0 +1,179 @@
+openapi: 3.0.1
+info:
+  title: SQL Executor for Dual Databases
+  description: |
+    Execute read-only SQL queries on two specialized databases and return structured JSON results:
+    - pubchemlite: Compound basic information database (core table: pubchemlite_exposomics_20251226)
+    - invitrodb_v4_3: In vitro toxicity experiment database (core tables: assay, chemical, mc0, assay_component)
+    (Adapted for local/server Flask API, only SELECT queries supported, write/modify operations prohibited)
+  version: 1.0.0
+servers:
+  - url: http://192.168.0.179:5000
+    description: Main API Server
+paths:
+  /execute_sql:
+    post:
+      summary: Execute SELECT query on specified database
+      operationId: executeSqlPost
+      description: |
+        Execute read-only SELECT queries on pubchemlite or invitrodb_v4_3 database.
+        Notes:
+        1. Only SELECT operation is allowed (INSERT/UPDATE/DELETE/DROP are prohibited);
+        2. For fields with special characters (e.g. pred_CCS_A2_[M+H]+ in pubchemlite), escape []/+ with backslash (\) or use backticks (`);
+        3. Avoid Python format characters (%, A, s, d) in SQL to prevent parsing errors;
+        4. Add LIMIT clause to avoid large result sets (recommended LIMIT 100).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                db_identifier:
+                  type: string
+                  description: Target database identifier (case-sensitive)
+                  enum: [pubchemlite, invitrodb_v4_3]
+                  example: "pubchemlite"
+                  x-validation: "Must be one of the specified enum values"
+                sql:
+                  type: string
+                  description: |
+                    Valid MySQL SELECT query (only):
+                    ## pubchemlite (core table: pubchemlite_exposomics_20251226)
+                    Key fields:
+                    - Basic info: Identifier, CompoundName, MolecularFormula, SMILES, XLogP
+                    - Literature/Patent: PubMed_Count, Patent_Count
+                    - Toxicity/Property: SafetyInfo, ToxicityInfo, MonoisotopicMass
+                    - Predicted CCS: pred_CCS_A2_[M+H]+, pred_CCS_A2_[M+Na]+, pred_CCS_A2_[M-H]- (escape special chars!)
+                    
+                    ## invitrodb_v4_3 (core tables)
+                    - assay: aid, assay_name, organism, tissue, ncbi_taxon_id
+                    - chemical: chid, casn, chnm (chemical name), dsstox_substance_id
+                    - mc0: m0id, acid, spid, conc (concentration μM), rval (response value)
+                    - assay_component: acid, assay_component_name (toxicity type)
+                  examples:
+                    pubchemlite_example:
+                      summary: Query compound basic info (with escaped special field)
+                      value: "SELECT Identifier, CompoundName, `pred_CCS_A2_[M+H]+` FROM pubchemlite_exposomics_20251226 WHERE PubMed_Count > 5 LIMIT 10"
+                    invitrodb_example:
+                      summary: Query human in vitro toxicity data
+                      value: "SELECT c.chnm, a.assay_name, m.conc, m.rval FROM chemical c JOIN mc0 m ON c.dsstox_substance_id = m.dsstox_substance_id JOIN assay a ON m.aid = a.aid WHERE a.ncbi_taxon_id = 9606 LIMIT 10"
+              required:
+                - db_identifier
+                - sql
+              x-error-tips: |
+                1. Missing required parameters: Ensure both db_identifier and sql are provided;
+                2. Invalid db_identifier: Only pubchemlite/invitrodb_v4_3 are allowed;
+                3. SQL syntax error: Check field/table names and special character escaping.
+      responses:
+        '200':
+          description: Query executed successfully (returns array of records)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    enum: [success, error]
+                    description: Execution status
+                  data:
+                    type: array
+                    items:
+                      type: object
+                      description: Query results (key = field name, value = field value)
+                      additionalProperties: true
+                  message:
+                    type: string
+                    description: Error message (empty if success)
+                examples:
+                  pubchemlite_response:
+                    summary: pubchemlite query success
+                    value:
+                      status: "success"
+                      data: [
+                        {
+                          "Identifier": "CID12345",
+                          "CompoundName": "Aspirin",
+                          "MolecularFormula": "C9H8O4",
+                          "pred_CCS_A2_[M+H]+": 181.05
+                        }
+                      ]
+                      message: ""
+                  invitrodb_response:
+                    summary: invitrodb_v4_3 query success
+                    value:
+                      status: "success"
+                      data: [
+                        {
+                          "chnm": "Aspirin",
+                          "assay_name": "Cell Viability Assay",
+                          "conc": 10.0,
+                          "rval": 25.8
+                        }
+                      ]
+                      message: ""
+        '400':
+          description: Bad Request (client-side error)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    default: "error"
+                  message:
+                    type: string
+                examples:
+                  invalid_db_identifier:
+                    summary: Incorrect database identifier
+                    value:
+                      status: "error"
+                      message: "Parameter error: db_identifier only supports pubchemlite/invitrodb_v4_3"
+                  special_char_error:
+                    summary: Unescaped special characters in SQL
+                    value:
+                      status: "error"
+                      message: "SQL parsing error: pred_CCS_A2_[M+H]+ needs escaping (recommended: `pred_CCS_A2_[M+H]+` or pred_CCS_A2_\\[M+H\\]+)"
+                  format_char_conflict:
+                    summary: Python format character conflict
+                    value:
+                      status: "error"
+                      message: "Request processing failed: unsupported format character 'A' (please avoid %/A/s/d format characters in SQL)"
+                  cross_db_field:
+                    summary: Cross-database field query
+                    value:
+                      status: "error"
+                      message: "SQL syntax error: CompoundName field does not exist in invitrodb_v4_3 database (this field is only supported in pubchemlite)"
+        '500':
+          description: Server Error (database/server-side error)
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                    default: "error"
+                  message:
+                    type: string
+                examples:
+                  db_connection_failed:
+                    summary: Database connection timeout
+                    value:
+                      status: "error"
+                      message: "Database connection failed: pubchemlite database connection timeout, please check database configuration"
+                  table_not_exist:
+                    summary: Table does not exist in target database
+                    value:
+                      status: "error"
+                      message: "Database execution error: assay table does not exist in pubchemlite database (this table is only supported in invitrodb_v4_3)"
+                  sql_timeout:
+                    summary: SQL query timeout
+                    value:
+                      status: "error"
+                      message: "SQL execution timeout: please add LIMIT to restrict returned rows (recommended LIMIT 100)"
+    parameters: []
+components:
+  schemas: {}