/api/sql/exec

通过使用带有要执行的 SQL 语句或语句集的 HTTP POST 请求来调用 api/sql/exec 资源，并返回一个响应，该响应包含查询结果集或根据执行的 SQL 语句所影响的行数。

可以使用 curl 提交一个示例的 api/sql/exec 请求，如下所示：

    curl -X POST --data-raw '{ "sql": "SELECT * FROM Statistic" }' http://localhost:8083/api/sql/exec

请注意，在 Windows 系统中，可能需要像下面这样对嵌入的双引号字符进行转义：

    curl -X POST --data-raw "{ \"sql\": \"SELECT * FROM Statistic\" }" http://localhost:8083/api/sql/exec

请求

客户端提交 SQL 代码以执行以及作为 JSON 编码的 HTTP 内容的执行参数。/api/sql/exec 请求还可以指定可选的 max_records、max_array 和 max_sequence 参数。例如：

    {
        "sql": "SELECT * FROM Statistic",
        "max_records": 100,
        "max_array": 10,
        "max_sequence": 10
    }

这些参数分别指定了返回的结果集、数组和序列的最大大小。它们的默认值分别为 100、10 和 10。

sql 参数包含要执行的 SQL 语句。它可能由多个语句组成，语句之间用分号分隔。如果有多个语句，则按顺序执行，一旦出现错误，执行将中止。

如果 SQL 文本以 select（不区分大小写）开头，则将其作为查询执行，并返回结果集。否则，将其作为非查询语句执行，并仅返回受影响的行数。

响应

结果以包含单个数组结果的 JSON 对象形式返回。此数组中每条已执行的 SQL 语句都有一个对应的记录。记录有两种类型，分别为 stmt 和 query，它们在记录的 type 字段中返回。

非查询语句结果记录

这些记录只有两个字段：type（设置为 stmt）和 rows_affected，后者指定了受影响的行数，这是由 SQL 引擎返回的。例如：

    {
        "result":
        [
            ...
            {
                "type": "stmt",
                "rows_affected": 1
            }
            ...
        ]
    }

查询结果记录

这些记录比报表结果更复杂。它们包含类型字段（设置为查询）和数据对象，该数据对象封装了返回的结果集。数据对象由一个头和一个结果集组成。头包含结果集的元数据，其中包括：

结果集大小：结果集的总大小；
字段：一个数组，包含结果集中每个列的名称和类型；

请注意，结果集大小的值可能大于返回的记录数，返回的记录数受 max_records 参数的限制。

结果集字段是一个数组，其每个元素都是一个数组，其中包含与标头中 fields 数组所指定的顺序相同的列值。例如：

    {
        "result":
        [
            ...
            {
                "type": "query",
                "data":
                {
                    "header":
                    {
                        "resultset_size": 4,
                        "fields":
                        [
                            { "name": "i", "type": "Int4" },
                            { "name": "s", "type": "String" }
                        ]
                    },
                    "resultset":
                    [
                        [ 1, "string1" ],
                        [ 2, "string2" ],
                        [ 3, "string3" ],
                        [ 4, "string4" ]
                    ]
                }
            }
            ...
        ]
    }

日期时间字段

对于类型为 datetime 的字段，精度会在结果集的表头中输出。例如，假设有一个名为 DateTimeTable 的表，其中包含一个名为 dt 的单个 datetime 字段。可以使用如下命令提取该表的值：

    curl -X POST http://localhost:8083/api/sql/exec
        {"sql":"SELECT dt FROM DateTimeTable;"}

结果将在输出中显示 dt 的精度，如下所示：

    {
        "result":
        [
            {
                "sql": "SELECT dt FROM TestDateTimeTable;",
                "type": "query",
                "data":
                {
                    "header":
                    {
                        "fields":
                        [
                            {
                                "name": "dt",
                                "type": "DateTime",
                                "precision": 1
            
                            }
                        ]
                    },
                    "resultset":
                    [
                        [100000000]
                    ]
                }
            }
        ]
    }

错误记录

如果在执行语句期间发生错误，则会返回错误记录，并且进一步的执行将被中止。在这种情况下，错误记录将是结果数组中的最后一个记录，并且它是唯一的错误记录。

错误记录包含类型字段（查询或语句，对应失败的 SQL 语句）和错误对象。错误代码和消息从 SQL 引擎原样传递。（错误代码在 sql/exceptions.h 头文件中的 ErrorCode 枚举中定义。）以下是一个错误记录的示例：

    {
        "result":
        [
            ...
            {
                "type": "stmt",
                "error":
                {
                    "code": 3,
                    "message": "Compiler error at position 20: Unknown table inexistent\nDROP TABLE inexistent;\n                 ^\n"
                }
            }
        ]
    }

请求和响应示例

假设要执行以下 SQL 语句：

    CREATE TABLE T(i INT, s STRING);
    INSERT INTO T(i, s) VALUES(1, 'string1'), (2, 'string2'), (3, 'string3'), (4, 'string4');
    SELECT * FROM T;
    DROP TABLE T;

请求体将如下所示：

    {
        "sql": "CREATE TABLE T(i INT, s STRING);\nINSERT INTO T(i, s) 
            VALUES(1, 'string1'), (2, 'string2'), (3, 'string3'), (4, 'string4');\n
            SELECT * FROM T;\nDROP TABLE T;\n"
    }

返回的响应体内容将如下所示：

    {
        "result":
        [
            {
                "type": "stmt",
                "rows_affected": -1
            },
            {
                "type": "stmt",
                "rows_affected": -1
            },
            {
                "type": "query",
                "data":
                {
                    "header":
                    {
                        "resultset_size": 4,
                        "fields":
                        [
                            {
                                "name": "i",
                                "type": "Int4"
                            },
                            {
                                "name": "s",
                                "type": "String"
                            }
                        ]
                    },
                    "resultset":
                    [
                        [
                            3,
                            "string3"
                        ],
                        [
                            2,
                            "string2"
                        ],
                        [
                            1,
                            "string1"
                        ],
                        [
                            4,
                            "string4"
                        ]
                    ]
                }
            },
            {
                "type": "stmt",
                "rows_affected": -1
            }
        ]
    }