Validate Query Context

Type: Procedure

Analyze a SQL query against governance policies before execution. Parses the SQL to identify referenced tables and columns, checks each against the governance catalog, and returns a compliance report with parser diagnostics and agent-ready next steps. Optionally provide intent parameters to also run authorization checks.

Use Cases

• An AI agent validates a generated SQL query before running it
• A code review bot checks data access patterns in SQL scripts
• A developer tests whether their query touches PII or restricted columns
• An automated pipeline validates queries at build time, before deployment

Input Parameters

Parameter	Type	Required	Description
sql	string	Yes	The SQL query to validate. Supports SELECT, INSERT, UPDATE, DELETE, MERGE, and CTAS statements.
operation	string	No	The intended operation type (e.g., read, export, transform). When provided, triggers authorization evaluation in addition to compliance checking.
intended_use	string	No	Canonical intended-use label. Used for authorization when an operation is provided or inferred.
actor_role	string	No	The role executing the query. Defaults to the session role. Used for authorization evaluation.
destination	object	No	Destination metadata for embedded transfer authorization.
consumer_jurisdiction	string	No	Consumer jurisdiction for embedded transfer authorization.

When operation and intended_use are provided, the response includes a decision object equivalent to calling authorize-use for each table referenced in the query.

Output Schema

Field	Type	Description
status	string	OK if no violations found, WARNING if advisory issues detected
compliant	boolean	true if no enforced policy violations were found
validation_id	string	Unique identifier for the validation trace. Use with explain-why.
tables_accessed	array	List of fully qualified table names referenced in the query
sql_findings	array	SQL-level findings (e.g., SELECT * usage, missing WHERE clause)
sql_findings[].type	string	Finding type: info, warning, violation
sql_findings[].message	string	Description of the finding
columns_accessed	array	Column-level governance details
columns_accessed[].table	string	Fully qualified table name
columns_accessed[].column	string	Column name
columns_accessed[].governed	boolean	Whether this column has governance rules
columns_accessed[].is_pii	boolean	Whether this column is classified as PII
columns_accessed[].sensitivity	string	Column sensitivity level
columns_accessed[].masking	object	Masking configuration (same schema as inspect-data-meaning)
policies_evaluated	array	Policies that were checked during validation
summary	string	Human-readable compliance summary
decision	object	Authorization decision (only present when operation and intended_use are provided). Same schema as authorize-use response.
extraction_method	string	Current parser strategy used for table and column extraction.
parser_confidence	number	Confidence in SQL extraction. Low confidence means the query should not be executed without review.
unsupported_patterns	array	SQL patterns that require conservative handling.
ambiguous_columns	array	Column names that could not be mapped to one table confidently.
unknown_tables	array	Referenced tables that are not governed by Metatate.
table_column_map	object	Per-table confident column mapping used for embedded authorization.
agent_action	object	Compact machine-actionable guidance for agents and pipelines.

Example Response

{
  "status": "success",
  "data": {
    "status": "WARNING",
    "compliant": true,
    "tables_accessed": [
      "ANALYTICS_DB.CORE.CUSTOMERS"
    ],
    "sql_findings": [
      {
        "type": "warning",
        "message": "Query accesses 3 PII columns: EMAIL, PHONE, SSN. Ensure masking is applied."
      },
      {
        "type": "info",
        "message": "Table ANALYTICS_DB.CORE.CUSTOMERS has sensitivity level 'confidential'."
      }
    ],
    "columns_accessed": [
      {
        "table": "ANALYTICS_DB.CORE.CUSTOMERS",
        "column": "CUSTOMER_ID",
        "governed": true,
        "is_pii": false,
        "sensitivity": "internal",
        "masking": {
          "enabled": false,
          "type": "none"
        }
      },
      {
        "table": "ANALYTICS_DB.CORE.CUSTOMERS",
        "column": "EMAIL",
        "governed": true,
        "is_pii": true,
        "sensitivity": "confidential",
        "masking": {
          "enabled": true,
          "type": "partial"
        }
      },
      {
        "table": "ANALYTICS_DB.CORE.CUSTOMERS",
        "column": "SSN",
        "governed": true,
        "is_pii": true,
        "sensitivity": "restricted",
        "masking": {
          "enabled": true,
          "type": "hash"
        }
      }
    ],
    "policies_evaluated": [
      "pol_customer_pii_001",
      "pol_audit_001"
    ],
    "summary": "Query is compliant but accesses PII columns with active masking. Non-exempt roles will see masked values."
  },
  "errors": []
}

SQL Examples

Validate a query

CALL METATATE_APP.CORE.VALIDATE_QUERY_CONTEXT(
  OBJECT_CONSTRUCT(
    'sql', 'SELECT customer_id, email, ssn FROM analytics_db.core.customers WHERE region = ''US'''
  )
);

Validate with authorization check

CALL METATATE_APP.CORE.VALIDATE_QUERY_CONTEXT(
  OBJECT_CONSTRUCT(
    'sql', 'SELECT * FROM analytics_db.core.customers LIMIT 1000',
    'operation', 'export',
    'intended_use', 'Export customer list for marketing campaign',
    'actor_role', 'MARKETING_ANALYST'
  )
);

Validate a JOIN query

CALL METATATE_APP.CORE.VALIDATE_QUERY_CONTEXT(
  OBJECT_CONSTRUCT(
    'sql', 'SELECT c.email, o.total_amount FROM analytics_db.core.customers c JOIN analytics_db.core.orders o ON c.customer_id = o.customer_id WHERE o.total_amount > 10000'
  )
);

Validate an INSERT statement

CALL METATATE_APP.CORE.VALIDATE_QUERY_CONTEXT(
  OBJECT_CONSTRUCT(
    'sql', 'INSERT INTO analytics_db.staging.customer_export SELECT customer_id, name, email FROM analytics_db.core.customers',
    'operation', 'transform',
    'intended_use', 'Staging data for downstream ETL pipeline'
  )
);

JSON Request / Response (API)

Request:

{
  "method": "tools/call",
  "params": {
    "name": "validate-query-context",
    "arguments": {
      "sql": "SELECT customer_id, email FROM analytics_db.core.customers WHERE region = 'US'",
      "operation": "read",
      "intended_use": "Customer engagement analysis"
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"status\":\"success\",\"data\":{\"status\":\"WARNING\",\"compliant\":true,\"tables_accessed\":[\"ANALYTICS_DB.CORE.CUSTOMERS\"],\"sql_findings\":[{\"type\":\"warning\",\"message\":\"Query accesses PII column: EMAIL. Masking is active.\"}],\"columns_accessed\":[{\"table\":\"ANALYTICS_DB.CORE.CUSTOMERS\",\"column\":\"CUSTOMER_ID\",\"governed\":true,\"is_pii\":false,\"sensitivity\":\"internal\",\"masking\":{\"enabled\":false,\"type\":\"none\"}},{\"table\":\"ANALYTICS_DB.CORE.CUSTOMERS\",\"column\":\"EMAIL\",\"governed\":true,\"is_pii\":true,\"sensitivity\":\"confidential\",\"masking\":{\"enabled\":true,\"type\":\"partial\"}}],\"policies_evaluated\":[\"pol_customer_pii_001\"],\"summary\":\"Query is compliant. EMAIL column is masked for non-exempt roles.\",\"decision\":{\"decision\":\"ALLOW\",\"confidence\":0.95,\"summary\":\"Read access for customer engagement analysis is permitted.\"}},\"errors\":[]}"
    }
  ]
}

Try it in the app

Open Metatate and navigate to the Test Tools tab to run validate-query-context interactively. Paste any SQL query and see a formatted compliance report with highlighted findings.