[]
本功能提供标准化数据查询接口，通过将多个业务系统数据源（包括ERP、CRM、供应链等）接入统一数据分析平台Wyn ，完成跨系统数据清洗、关联建模与指标加工，用户可使用接口查询和返回Apache Arrow/JSON格式的高性能数据流，用于二次数据分析。无需重复建设数据管道，即可直接获取可分析的企业级整合数据，打造数据资产共享服务体系。
某零售集团在业务经营中存在以下问题：
业务系统分散：POS系统、电商平台、会员数据库独立运作
数据割裂：门店销售与线上订单无法实时关联分析
开发低效：每新建报表或者大屏需从各系统重新抽取数据，开发周期超2周
用户将各个业务系统的数据接入Wyn，基于统一的业务规则加工数据后，通过API查询和返回加工后的数据，用于企业内所有数据分析场景中，打造全域经营分析。具体数据接入和数据加工参考前面章节，下面介绍如何使用接口查询和返回数据。
下面使用ApifoX工具演示具体操作步骤，下图是一个调用数据源的简单示例。
示例中的 URL 为：http://10.32.210.94:51980/api/v2/data/datasources/5b8080276d502b0031deb393/query?queryType=sql&query=select * from 销售明细&token=F3E82958C368F2FCB52AD3A44698632414E99C1AF578454930E527500B990DF2&format=json，粘贴后路径中Query参数已自动提取，并填充到下方请求参数的Param中。
注意： 使用的Token必须具备查看对应文档的权限。
以下是调用数据集、数据源以及数据模型时分别使用URL格式：
数据集：POST/GET api/v2/data/datasets/{document id}/query
数据源：POST/GET api/v2/data/datasources/{document id}/query
数据模型：POST/GET api/v2/data/data-models/{document id}/query
接下来进一步介绍调用API的细节。
支持POST 和GET 两种方式。
数据集 POST 有效负载格式：
{
"QueryType": "NONE|WAX", //WAX指分析表达式
"Query": "some text like a WAX statement or empty"
"DatasetParameters":{
"Parameter1": "ParameterValue1"(单值),
"Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
},
"Format":Arrow | Json,
"Options":{
"Parameter1":"Value1"
}
}示例： 其中Params中是token
数据集 GET查询参数：
? format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2_1
& $ parameter2=value2_2
&option1=value1
&option2=value2
option1, option2 ...为 选项参数 ，前缀 $ 表示 数据集参数 ，多个值通过多次重复一个参数来表示。关于 option详见本页下方介绍。
示例： token的获取
支持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"
}
}示例： 其中Params中是token
数据源 GET查询参数：
? queryType ="sql"
& query ="query"
& format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2
&option1=value1
&option2=value2
option1, option2 ... 为 选项参数 ，前缀 $ 表示 数据源参数 ，多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。
示例： token的获取
支持POST 和GET 两种方式。
数据模型 POST 有效负载：
{
"Query": "some text like a WAX statement",
"DataSourceParameters": {
"Parameter1": "ParameterValue1"(单值),
"Parameter2": "ParameterValue1,ParameterValue2" (多值使用逗号分隔)
},
"Format":Arrow | Json,
"Options":{
"Parameter1":"Value1"
}
}示例： 其中Params中是token
数据模型GET 查询参数：
? query ="query"
& format =Arrow | Json
& $ parameter1=value1
& $ parameter2=value2
&option1=value1
&option2=value2
option1, option2 ... 为选项参数，前缀$表示数据源参数，多个值通过多次重复一个参数来表示。关于 option 详见本页下方介绍。
示例： token的获取
支持的查询类型：
数据来源 | 查询类型 | |||
|---|---|---|---|---|
None | Sql | WAX(分析表达式) | ||
数据集 | 缓存数据集 | ✓ | ✓ | |
直连数据集 | ✓ | |||
流数据集 | ✓ | |||
推送数据集 | ✓ | |||
数据源 | ✓ | |||
数据模型 | 缓存数据模型 | ✓ | ||
直接数据模型 | ✓ | |||
注意： 当 queryType 设置为 "WAX" 时，对应的query中的 "WAX" 表达式必须返回一个表对象（例如
"query":"Evaluate Filter('Demo销售明细','Demo销售明细'[客户地区]=\"西北\")"）。
不同数据来源支持的查询参数：
数据来源 | 参数 | ||
|---|---|---|---|
数据源参数 | 用户输入参数 | ||
数据集 | 缓存数据集 | ||
直接数据集 | ✓ | ||
流数据集 | |||
推送数据集 | |||
数据源 | ✓ | ||
数据模型 | 缓存数据模型 | ||
直接数据模型 | ✓ | ||
用户上下文和组织上下文参数由于安全原因不能由用户通过参数传递，只能从当前用户的声明中读取。
由于数据源中不同表的参数可能同名，所以特地引入了限定参数名，以便在传递参数时明确该参数适用于哪个表。
1）例如：JSON Web 数据源中有两个端点“endpoint1”和“endpoint2”，每个端点上都存在一个名为 p1 的参数。传递参数时，用户可以指定endpoint1.p1=value1，endpoint2.p1=value2。
2）在 HTTP GET 方法中：
& $ endpoint1.p1=value1
& $ endpoint2.p1=value2
3）在 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 |