1. 内容概述

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

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

2. HTTP 路由格式

以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

以下是调用数据集、数据源以及数据模型时分别使用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

接下来进一步介绍细节。

3. 调用数据集

支持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 详见本页下方介绍。

示例：

4. 调用数据源

支持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 详见本页下方介绍。

示例

5. 调用数据模型

支持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 详见本页下方介绍。

示例：

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

支持的查询类型

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

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

数据源参数支持 限定名

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

例如：

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 选项参数

支持的数据类型

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

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

Arrow Type

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

 C# types for Json