阿里云首页 云原生多模数据库 Lindorm 相关技术圈

SQL接口应用指南

本文介绍时序引擎提供的基于HTTP协议的通用SQL接口的定义和用法。

对于任意非Java编程语言的应用开发,可以使用下述API直接向时序引擎发送SQL语句;对于Java语言的应用开发,建议基于JDBC Driver构建时序引擎的应用程序。

请求路径与方法

请求路径

请求方法

描述

/api/v2/sql

POST

发送并执行SQL语句

请求内容

请求上述 API 时,直接将 SQL语句写入HTTP请求的请求体即可,并且建议在请求头设置 Content-Typetext/plain。 以Python代码为例,在Python代码中向 /api/v2/sql传送一条SQL语句的做法示例如下:

import urllib2

reqheaders={'Content-Type':'text/plain'}
req=urllib2.Request('http://ld-xxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql', 'SHOW TABLES', reqheaders)
response=urllib2.urlopen(req).read()
注意

时序引擎遵循SQL-92标准,支持将半角分号(;)作为SQL语句的终止符。但是在调用 /api/v2/sql 传递SQL语句时,不能在结尾加上分号,否则会引发解析错误。

支持的查询参数

/api/v2/sql 支持的URL查询参数如下所示:

名称

描述

database

SQL执行时的默认Database。

当指定的SQL中写入或查询的时序表名未显式指定所属数据库名时,时序引擎默认会在该参数指定的database中搜寻操作对象的表名。

未指定该查询参数时,引擎会默认在名为 default 的Database中搜寻表名

chunked

是否流式返回结果数据。默认为false。

当指定为true时,查询结果数据会以多个json块的方式返回,每个json块最多包含chunk_size行数据。在解析结果数据时,只需要逐个解析json块即可。每个json块的结构参考响应内容部分描述。

chunk_size

指定流式返回结果时每次返回的最大行数。chunked=true时生效,默认为1000。

用户认证信息指定

当Lindorm时序引擎开启用户鉴权时,通过 /api/v2/sql 发送SQL请求时需要向HTTP请求头中填入用户认证信息。目前 /api/v2/sql 遵循的是 BASIC AUTH 认证方式,编码后的认证信息需要指定在HTTP请求头的 Authorization 字段中。

基本认证凭据的格式如下:

BASIC {BASE64编码的认证信息}

其中需要被BASE64编码的认证信息明文为${用户名}:${对应的用户密码} (中间一定以冒号相隔)。

说明

各编程语言编码并填充BASIC AUTH认证信息的方法,请查询所用语言的相关类库的使用文档,不在此罗列。

响应内容

查询成功的HTTP响应码为200,响应内容为JSON格式数据。说明如下:

名称

类型

描述

columns

Array

字符串数组

表示返回结果集中列名。

metadata

Array

字符串数组

表示返回结果集中每一列的数据类型名称。可能返回的数据类型请参见数据类型

rows

Array

数组的数组

表示返回结果集的行的集合。其中的每一个数组代表着一行数据,每行数据中的具体数据与columns中返回的列一一对应。

SQL执行出错时的响应消息中的HTTP响应码为400,响应消息体是一个JSON格式数据,其包含的字段说明如下:

名称

类型

描述

code

int

错误码

sqlstate

String

sqlstate

message

String

错误详情

说明

关于错误码对应的具体错误,请参考Lindorm TSDB的 常见错误码参考 文档。

示例

以下示例通过常用的curl命令,展示了如果通过该HTTP接口对Lindorm时序引擎执行SQL。

  • 创建名为DB1的Database。

    curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql -d 'CREATE DATABASE DB1'

  • 在DB1下创建名为SENSOR的时序数据表。

    curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1 -d 'CREATE TABLE SENSOR (device_id VARCHAR TAG,region VARCHAR TAG,time TIMESTAMP,temperature DOUBLE,humidity DOUBLE)'

    或者

    curl -X POST http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql -d 'CREATE TABLE DB1.SENSOR (device_id VARCHAR TAG,region VARCHAR TAG,time TIMESTAMP,temperature DOUBLE,humidity DOUBLE)'

  • 当用户鉴权开关开启时,以一个名为 tsdbuser 的用户查询上述SENSOR时序表。

    curl -X POST -u tsdbuser:password http://ld-xxxxxxxxx-proxy-tsdb-pub.lindorm.rds.aliyuncs.com:8242/api/v2/sql?database=DB1 -d 'SELECT device_id, region, time, MAX(temperature) as max_t FROM SENSOR WHERE time >= 1619076780000 AND time <= 1619076800000 SAMPLE BY 20s'
    说明

    本示例中假定已事先对用户 tsdbuser 赋予了时序表SENSOR的相关权限。