parse_sql

This page explains how to use the parse_sql function in APL.

Introduction

The parse_sql function parses a SQL statement string and returns a structured dictionary representing its components, such as tables, columns, conditions, and clauses. Use it to analyze SQL queries stored in your observability data, validate query structure, or extract specific parts of a SQL statement for further processing.

parse_sql is useful in database monitoring scenarios where SQL queries are captured as strings in audit logs or trace attributes, and you want to understand query patterns, detect anomalies, or inspect query structure at scale.

Usage

Syntax

parse_sql(sql_statement)

Parameters

Name	Type	Required	Description
sql_statement	string	Yes	The SQL statement to parse.

Returns

A dictionary representing the structured data model of the SQL statement, including the statement type, selected columns, source tables, conditions, and ordering clauses.

Use case examples

Parse a SQL query that represents a slow-query log entry to inspect its structure.

Query

print parsed_query = parse_sql('SELECT id, status, uri FROM requests WHERE req_duration_ms > 1000 ORDER BY req_duration_ms DESC')

Run in Playground

Output

{
    "parsed_query": {
        "columns": [
            {
                "colname": "id"
            },
            {
                "colname": "status"
            },
            {
                "colname": "uri"
            }
        ],
        "from": [
            {
                "table": "requests"
            }
        ],
        "order": [
            {
                "direction": "desc",
                "expr": {
                    "colname": "req_duration_ms"
                }
            }
        ],
        "statement": "select",
        "where": {
            "operator": ">",
            "params": [
                {
                    "colname": "req_duration_ms"
                },
                {
                    "value": "1000",
                    "valtype": "integer"
                }
            ]
        }
    }
}

The query parses a slow-query SQL string and returns its structured representation, letting you extract specific clauses with parsed_query.from or parsed_query.columns.

Parse a SQL query that represents a database span to inspect which tables and columns a service queries.

Query

print parsed_query = parse_sql('SELECT trace_id, span_id, duration FROM traces ORDER BY duration DESC')

Run in Playground

Output

{
    "parsed_query": {
        "columns": [
            {
                "colname": "trace_id"
            },
            {
                "colname": "span_id"
            },
            {
                "colname": "duration"
            }
        ],
        "from": [
            {
                "table": "traces"
            }
        ],
        "order": [
            {
                "direction": "desc",
                "expr": {
                    "colname": "duration"
                }
            }
        ],
        "statement": "select"
    }
}

The query parses a database span's SQL string and returns its structured representation so you can programmatically inspect which tables and columns the trace's database operations access.

Parse a SQL statement that contains an authorization filter to verify that the expected WHERE clause is present.

Query

print parsed_query = parse_sql('SELECT id, status FROM logs WHERE status = 401 OR status = 403')

Run in Playground

Output

{
    "parsed_query": {
        "columns": [
            {
                "colname": "id"
            },
            {
                "colname": "status"
            }
        ],
        "from": [
            {
                "table": "logs"
            }
        ],
        "statement": "select",
        "where": {
            "operator": "or",
            "params": [
                {
                    "params": [
                        {
                            "colname": "status"
                        },
                        {
                            "value": "401",
                            "valtype": "integer"
                        }
                    ],
                    "operator": "="
                },
                {
                    "operator": "=",
                    "params": [
                        {
                            "colname": "status"
                        },
                        {
                            "valtype": "integer",
                            "value": "403"
                        }
                    ]
                }
            ]
        }
    }
}

The query parses a SQL string with an OR condition in its WHERE clause. You can then inspect the where field to confirm that the expected authorization filters are present.

format_sql: Converts the dictionary produced by parse_sql back into a SQL string. Use format_sql to normalize or round-trip a parsed query.
parse_json: Parses a JSON string into a dynamic dictionary. Use parse_json when your data contains JSON rather than SQL.
extract: Extracts a substring matching a regular expression from a string. Use extract for simple pattern matching when you don't need full SQL parsing.