Skip to content
Raindrop Developer Hub

Smart SQL

The Smart SQL service provides intelligent SQL query execution capabilities with natural language to SQL conversion and automatic metadata management. It enables users to interact with databases using both direct SQL queries and natural language descriptions.

POST /v1/execute_query

Executes a SQL query or converts natural language to SQL and executes it. Supports both direct SQL execution and AI-powered natural language to SQL conversion. Automatically handles metadata updates and PII detection for data governance.

Features:

  • Direct SQL query execution
  • Natural language to SQL conversion using AI
  • Automatic metadata tracking for schema changes
  • PII detection for security
  • Multiple output formats (JSON, CSV)

Schema Reference

Request Body

smartSqlLocation (object) Required

Details
Description

Smart SQL locator for targeting the correct smart SQL instance

Example
{
  "smartSql": {
    "name": "analytics-sql",
    "version": "v1.2.0",
    "application_name": "data-analytics-app"
  }
}

sqlQuery (string(nullable))

Details
Description

Direct SQL query to execute (mutually exclusive with text_query)

Example
SELECT * FROM users WHERE active = true

textQuery (string(nullable))

Details
Description

Natural language query to convert to SQL (mutually exclusive with sql_query)

Example
Show me all active users from the last month

format (object(nullable))

Details
Description

Desired output format for query results

Example
json
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const response = await client.executeQuery.execute({
  smartSqlLocation: {
    smartSql: { name: 'analytics-sql', version: 'v1.2.0', application_name: 'data-analytics-app' },
  },
});


console.log(response);

Response Examples

{}

POST /v1/get_metadata

Retrieves database schema metadata for a smart SQL instance. Returns table structures, column information, and sample data that can be used for AI context or application development.

Metadata includes:

  • Table names and structures
  • Column names and data types
  • Sample data for AI context
  • Schema versioning information

Schema Reference

Request Body

smartSqlLocation (object) Required

Details
Description

Smart SQL locator for targeting the correct smart SQL instance

Example
{
  "smartSql": {
    "name": "analytics-sql",
    "version": "v1.2.0",
    "application_name": "data-analytics-app"
  }
}

tableName (string(nullable))

Details
Description

Optional table name to filter metadata

Example
users
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const getMetadata = await client.getMetadata.retrieve({
  smartSqlLocation: {
    smartSql: { name: 'analytics-sql', version: 'v1.2.0', application_name: 'data-analytics-app' },
  },
});


console.log(getMetadata.lastUpdated);

Response Examples

{
  "tables": [
    {
      "tableName": "users",
      "columns": [
        {
          "columnName": "user_id",
          "dataType": "INTEGER",
          "sampleData": "123",
          "nullable": true,
          "isPrimaryKey": true
        }
      ],
      "createdAt": "2025-05-05T18:36:43.029Z",
      "updatedAt": "2025-05-05T18:36:43.029Z"
    }
  ],
  "lastUpdated": "2025-05-05T18:36:43.029Z"
}

POST /v1/get_pii_data

Retrieves PII detection results for specific database records. Returns detailed information about detected personally identifiable information for compliance and auditing purposes.

PII information includes:

  • Entity types detected
  • Confidence scores
  • Character positions
  • Detection timestamps

Schema Reference

Request Body

smartSqlLocation (object) Required

Details
Description

Smart SQL locator for targeting the correct smart SQL instance

Example
{
  "smartSql": {
    "name": "analytics-sql",
    "version": "v1.2.0",
    "application_name": "data-analytics-app"
  }
}

tableName (string) Required

Details
Description

Table name to retrieve PII data from

Example
users

recordId (string(nullable))

Details
Description

Optional record identifier to filter PII data

Example
user_123
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const getPiiData = await client.getPiiData.retrieve({
  smartSqlLocation: {
    smartSql: { name: 'analytics-sql', version: 'v1.2.0', application_name: 'data-analytics-app' },
  },
  tableName: 'users',
});


console.log(getPiiData.piiDetections);

Response Examples

{
  "piiDetections": [
    {
      "detectionId": "01jxanr45haeswhay4n0q8340y",
      "tableName": "users",
      "recordId": "user_123",
      "entities": [
        {
          "entityType": "EMAIL",
          "confidenceScore": 0.95,
          "detectedText": "john.doe@example.com",
          "startPosition": 25,
          "endPosition": 46,
          "tokenIndex": 5
        }
      ],
      "detectedAt": "2025-05-05T18:36:43.029Z"
    }
  ]
}

POST /v1/update_metadata

Updates database schema metadata manually. Allows for explicit metadata management when automatic detection is insufficient or needs correction.

Use cases:

  • Manual schema corrections
  • Bulk metadata updates
  • Custom metadata annotations

Schema Reference

Request Body

smartSqlLocation (object) Required

Details
Description

Smart SQL locator for targeting the correct smart SQL instance

Example
{
  "smartSql": {
    "name": "analytics-sql",
    "version": "v1.2.0",
    "application_name": "data-analytics-app"
  }
}

tables (array) Required

Details
Description

Table metadata to update or create

mode (object(nullable))

Details
Description

Update mode: replace (overwrite), merge (preserve existing), or append (only new entries)

Example
UPDATE_MODE_MERGE
 
import Raindrop from '@liquidmetal-ai/lm-raindrop';


const client = new Raindrop();


const updateMetadata = await client.updateMetadata.update({
  smartSqlLocation: {
    smartSql: { name: 'analytics-sql', version: 'v1.2.0', application_name: 'data-analytics-app' },
  },
  tables: [{}],
});


console.log(updateMetadata.success);

Response Examples

{
  "success": true,
  "tablesUpdated": 123
}