[]
        
(Showing Draft Content)

数据查询API

本文介绍如何通过 API 来查询站点中的数据源、数据集以及数据模型。

最终返回的数据格式为 Apache Arrow 或 JSON 格式。

HTTP 路由格式

以Postman为例,下面是一个调用数据源的简单示例。

image2022-7-18_14-49-55.png


示例中的 URL 为:http://10.32.5.7:51980/api/v1/datasource/b7d93485-66f2-4356-ada5-0a163579232d/query?queryType=sql&query=select \* from Categories&token=27487CA0BE14CF599444E8553E5E07F78D5D1AB8646302A2715E4802FCB95F08&format=json

注意


请注意使用的Token必须具备查看对应文档的权限。

以下是调用数据集、数据源以及数据模型时分别使用URL格式:

  • 数据集:POST/GET api/v1/dataset/{document id}/query

  • 数据源:POST/GET api/v1/datasource/{document id}/query

  • 数据模型:POST/GET api/v1/datamodel/{document id}/query

接下来进一步介绍细节。

调用数据集

支持POST 和GET 两种方式。

数据集 POST 有效负载格式:

{
    "QueryType": "NONE|WAX", 
    "Query": "some text like a WAX statement or empty"
    "DatasetParameters":{
        "Parameter1": "ParameterValue1"(单值),
        "Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
    },
    "Format":Arrow | Json,
    "Options":{
        "Parameter1":"Value1"
    }
}

示例:

image2022-7-18_15-24-1.png



数据集 GET查询参数:

? format =Arrow | Json

& $ parameter1=value1

& $ parameter2=value2_1

& $ parameter2=value2_2

&option1=value1

&option2=value2

option1, option2 ...为 选项参数 ,前缀 $ 表示 数据集参数 ,多个值通过多次重复一个参数来表示。关于 option详见本页下方介绍。

示例:

image2022-7-18_15-27-44.png

调用数据源

支持POST 和GET 两种方式。

数据源 POST 有效负载:

{
    "QueryType": "sql",
    "Query": "some text like a SQL or native query"
    "DataSourceParameters": {
        "Parameter1": "ParameterValue1"(单值),
        "Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
    },
    "Format":Arrow | Json,
    "Options":{
        "Parameter1":"Value1"
    }
}

示例:

image2022-7-18_16-29-20.png

数据源 GET查询参数:

? queryType ="sql"

& query ="query"

& format =Arrow | Json

& $ parameter1=value1

& $ parameter2=value2

&option1=value1

&option2=value2

option1, option2 ... 为 选项参数 ,前缀 $ 表示 数据源参数 ,多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。


示例

image2022-7-18_17-0-14.png

调用数据模型

支持POST 和GET 两种方式。

数据模型 POST 有效负载:

{
    "Query": "some text like a WAX statement",
    "DataSourceParameters": {
        "Parameter1": "ParameterValue1"(单值),
        "Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
    },
    "Format":Arrow | Json,
    "Options":{
        "Parameter1":"Value1"
    }
}

示例:

image2022-7-18_17-11-29.png


数据模型GET 查询参数:

? query ="query"

& format =Arrow | Json

& $ parameter1=value1

& $ parameter2=value2

&option1=value1

&option2=value2

option1, option2 ... 为选项参数,前缀$表示数据源参数,多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。


示例:

image2022-7-18_17-19-4.png

支持的查询类型以及查询参数

支持的查询类型

数据来源

查询类型

None

Sql

分析表达式

数据集

缓存数据集


直接数据集



流数据集



推送数据集



数据源




数据模型

缓存数据模型



直接数据模型



不同数据来源支持的查询参数

数据来源

参数

数据源参数

用户输入参数

数据集

缓存数据集



直接数据集


流数据集



推送数据集



数据源



数据模型

缓存数据模型



直接数据模型


用户上下文和组织上下文参数由于安全原因不能由用户通过参数传递,只能从当前用户的声明中读取。

数据源参数支持 限定名

由于数据源中不同表的参数可能同名,所以特地引入了限定参数名,以便在传递参数时明确该参数适用于哪个表。

例如:

JSON Web 数据源中有两个端点“endpoint1”和“endpoint2”,每个端点上都存在一个名为 p1 的参数。传递参数时,用户可以指定endpoint1.p1=value1,endpoint2.p1=value2。


在 HTTP GET 方法中:

& $ endpoint1.p1=value1

& $ endpoint2.p1=value2


在 HTTP POST 方法中:

{
    "DataSourceParameters": {
        "endpoint1.p1": "ParameterValue1"(单值),
        "endpoint2.p1": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
    }
}

当然,当用户不使用限定名时,所有具有相同名称的参数将共享相同的参数值。

Option 选项参数

参数名

可选参数值

默认值

说明

UnknownTypeHandle

Ignore, Error, CastToString

Ignore

在结果集的形成过程中,当需要声明列的类型时,如何处理不支持的类型。

Ignore :忽略该列; Error :抛出异常; CastToString :将列转换为字符串。

MissParameterHandle

Default, Error

Default

查询数据时,如何处理数据中定义但用户未传递的参数。 Default :使用默认值; Error :抛出异常。

注意 :出于安全和隐私原因,此选项仅适用于非用户和非组织上下文参数,用户和组织上下文参数不能使用默认值。

RowLimit

Positive Integer

Unspecified

对于数据集的查询,是否限制结果的行数。

支持的数据类型

由于 Apache Arrow 都需要声明列的类型。但是由于各种语言在实现上的差异,即某些类型在某种语言中没有对应的实现,我们会为用户提供一些选项来决定如何处理这些类型,包括忽略、抛出错误和转换为字符串类型。

无论是 Arrow 还是Json 格式,内部都是通过C# 实现,所以请参考C# 的支持类型。

Arrow Type

Arrow Type

C# Type

示例

Boolean

Boolean

true

Int8

sbyte

1

Int16

Int16

1

Int32

Int32

1

Int64

Int64

1

UInt8

byte

1

UInt16

UInt16

1

UInt32

UInt32

1

UInt64

UInt64

1

Float

Float

1f

Double

Double

1d

Decimal128

Decimal

1m

Decimal256

Decimal

1m

Date32

*DateOnly (.net 6 only)

2000-01-01

Date64

DateTime

2000-01-01 00:00:00

Timestamp

DateTimeOffset

2000-01-01 00:00:00 +00:00

Binary

byte, byte[]

1, [0,1]

Utf8

string

"hello"

  • Arrow的字段可以设置为nullable,表示所有nullable和null类型。

C# types for Json

C# Type

Example

Nullable


Boolean

true

byte

1

byte[]

[1]

char

1

DateTime

2000-01-01 00:00:00

DateTimeOffset

2000-01-01 00:00:00 +00:00

decimal

1m

double

1d

float

1f

Guid

00000000-0000-0000-0000-000000000000

int

1

long

1l

BigInteger

1

sbyte

1

short

1

string

"hello"

TimeSpan

00:00:00

uint

1

ulong

1

Uri

HTTP://www.example.com

ushort

1