[]
本文介绍如何通过 API 来查询站点中的数据源、数据集以及数据模型。
最终返回的数据格式为 Apache Arrow 或 JSON 格式。
以Postman为例,下面是一个调用数据源的简单示例。
示例中的 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"
}
}
示例:
数据集 GET查询参数:
? format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2_1
& $ parameter2=value2_2
&option1=value1
&option2=value2
option1, option2 ...为 选项参数 ,前缀 $ 表示 数据集参数 ,多个值通过多次重复一个参数来表示。关于 option详见本页下方介绍。
示例:
支持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"
}
}
示例:
数据源 GET查询参数:
? queryType ="sql"
& query ="query"
& format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2
&option1=value1
&option2=value2
option1, option2 ... 为 选项参数 ,前缀 $ 表示 数据源参数 ,多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。
示例
支持POST 和GET 两种方式。
数据模型 POST 有效负载:
{
"Query": "some text like a WAX statement",
"DataSourceParameters": {
"Parameter1": "ParameterValue1"(单值),
"Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
},
"Format":Arrow | Json,
"Options":{
"Parameter1":"Value1"
}
}
示例:
数据模型GET 查询参数:
? query ="query"
& format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2
&option1=value1
&option2=value2
option1, option2 ... 为选项参数,前缀$表示数据源参数,多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。
示例:
数据来源 | 查询类型 | |||
---|---|---|---|---|
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" (多值使用逗号分隔)
}
}
当然,当用户不使用限定名时,所有具有相同名称的参数将共享相同的参数值。
参数名 | 可选参数值 | 默认值 | 说明 |
---|---|---|---|
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 |