REST API#

Important#

REST APIs interact with the services of APIServer and OpenMLDB, so the APIServer module must be properly deployed to be used effectively. APIServer is an optional module during installation and deployment. Refer to APIServer Deployment.
At this stage, APIServer is mainly used for functional testing, not recommended for performance testing, nor recommended for the production environment. The default deployment of APIServer does not have a high availability mechanism at present and introduces additional network and codec overhead.

JSON Body#

In interactions with the APIServer, the request body is in JSON format and supports some extended formats. Note the following points:

Numeric values exceeding the maximum value for integers or floating-point numbers will result in parsing failure, for example, a double type with the value 1e1000.
Non-numeric floating-point numbers: When passing data, support for NaN, Infinity, -Infinity, and their abbreviations Inf, -Inf is provided (note that these are unquoted and not strings, and other variant notations are not supported). When returning data, support is provided for NaN, Infinity, and -Infinity (variant notations are not supported). If you want to convert these to null, you can configure write_nan_and_inf_null.
Integer numbers can be passed as floating-point numbers, for example, 1 can be read as a double.
Floating-point numbers may have precision loss, for example, 0.3 will not strictly equal 0.3 when read but rather 0.30000000000000004. We do not reject precision loss, so consider whether you need to handle it from the business perspective. Values passed that exceed float max but do not exceed double max will become Inf when read.
true/false, null are not case-sensitive and only support lowercase.
The timestamp type currently does not support passing in year-month-day strings; it only supports passing in numeric values, for example, 1635247427000.
For the date type, please pass in a year-month-day string without any spaces in between.

Data Insertion#

Request url: http://ip:port/dbs/{db_name}/tables/{table_name}

http method: PUT

request body:

  {
       "value": [
        [v1, v2, v3]
      ]
  } 

Currently, it only supports inserting one piece of data.
The data should be arranged in strict accordance with the schema.

Sample request data:

curl http://127.0.0.1:8080/dbs/db/tables/trans -X PUT -d '{
"value": [
    ["bb",24,34,1.5,2.5,1590738994000,"2020-05-05"]
]}'

Response:

{
    "code":0,
    "msg":"ok"
}

Real-Time Feature Computing#

Request url: http://ip:port/dbs/{db_name}/deployments/{deployment_name}

http method: POST

request body:

Array format:

{
    "input": [["row0_value0", "row0_value1", "row0_value2"], ["row1_value0", "row1_value1", "row1_value2"], ...],
    "need_schema": false,
    "write_nan_and_inf_null": false
}

JSON format:

{
    "input": [
      {"col0":"row0_value0", "col1":"row0_value1", "col2":"row0_value2", "foo": "bar"}, 
      {"col0":"row1_value0", "col1":"row1_value1", "col2":"row1_value2"}, 
      ...
    ]
}

It can support multiple rows, and its results correspond to the array of data.data fields in the returned response one by one.
need_schema can be set to true, and the schema with output results will be returned. For optional parameter, the default is false.
write_nan_and_inf_null can be set to true, it is an optional parameter, and the default is false. If set to true, when there are NaN, Inf, or -Inf in the output data, they will be converted to null.
When the input is in array format/ JSON format, the returned result is also in array format/ JSON format. The input requested at a time only supports one format. Please do not mix formats.
Input data in JSON format can have redundant columns.

Sample Request Data

Example 1: Array format

curl http://127.0.0.1:8080/dbs/demo_db/deployments/demo_data_service -X POST -d'{
        "input": [["aaa", 11, 22, 1.2, 1.3, 1635247427000, "2021-05-20"]]
    }'

Response:

{
    "code":0,
    "msg":"ok",
    "data":{
        "data":[["aaa",11,22]]
    }
}

Example 2: JSON format

curl http://127.0.0.1:8080/dbs/demo_db/deployments/demo_data_service -X POST -d'{"input": [{"c1":"aaa", "c2":11, "c3":22, "c4":1.2, "c5":1.3, "c6":1635247427000, "c7":"2021-05-20", "foo":"bar"}]}'

Response:

{
    "code":0,
    "msg":"ok",
    "data":{
        "data":[{"c1":"aaa","c2":11,"w1_c3_sum":22}]
    }
}

Query#

Request url: http://ip:port/dbs/{db_name}

http method: POST

request bpdy:

{
    "mode": "",
    "sql": "",
    "input": {
        "schema": [],
        "data": []
    },
    "write_nan_and_inf_null": false
}

Request parameters:

Parameters	Type	Requirement	Description
mode	String	Yes	Set to `offsync` , `offasync`, `online`
sql	String	Yes
input	Object	No
schema	Array	No	Support data types (case insensitive): `Bool`, `Int16`, `Int32`, `Int64`, `Float`, `Double`, `String`, `Date and Timestamp`
data	Array	No	Schema and data must both exist

Sample Request Data

Example 1: General query

{
  "mode": "online",
  "sql": "select 1"
}

Response:

{
  "code":0,
  "msg":"ok",
  "data": {
    "schema":["Int32"],
    "data":[[1]]
  }
}

Example 2: Parametric query

{
  "mode": "online",
  "sql": "SELECT c1, c2, c3 FROM demo WHERE c1 = ? AND c2 = ?",
  "input": {
    "schema": ["Int32", "String"],
    "data": [1, "aaa"]
  }
}

Response:

{
    "code":0,
    "msg":"ok",
    "data": {
      "schema": ["Int32", "String", "Float"],
      "data": [[1, "aaa", 1.2], [1, "aaa", 3.4]]
    }
}

Query Deployment Information#

Request url: http://ip:port/dbs/{db_name}/deployments/{deployment_name}

http method: GET

Response:

{
  "code": 0,
  "msg": "ok",
  "data": {
    "name": "",
    "procedure": "",
    "input_schema": [

    ],
    "input_common_cols": [
      
    ],
    "output_schema": [

    ],
    "output_common_cols": [
      
    ],
    "dbs": [

    ],
    "tables": [

    ]
  }
}

Acquire All Library Names#

Request url: http://ip:port/dbs

http method: GET

Response:

{
  "code": 0,
  "msg": "ok",
  "dbs": [

  ]
}

Acquire All Table Names#

Request url: http://ip:port/dbs/{db}/tables

http method: GET

Response:

{
  "code": 0,
  "msg": "ok",
  "tables": [
    {
      "name": "",
      "table_partition_size": 8,
      "tid": ,
      "partition_num": 8,
      "replica_num": 2,
      "column_desc": [
        {
          "name": "",
          "data_type": "",
          "not_null": false
        }
      ],
      "column_key": [
        {
          "index_name": "",
          "col_name": [

          ],
          "ttl": {
            
          }
        }
      ],
      "added_column_desc": [
        
      ],
      "format_version": 1,
      "db": "",
      "partition_key": [
        
      ],
      "schema_versions": [
        
      ]
    }
  ]
}

Refresh APIServer Metadata Cache#

After performing operations such as creating or deleting tables, deployments, etc., there may be some latency in metadata synchronization. If you find that the APIServer cannot locate newly created tables or deployments, please try refreshing the cache first.

Request address: http://ip:port/refresh

Request method: POST

Response:

{
    "code":0,
    "msg":"ok"
}

REST API

Contents

REST API#

Important#

JSON Body#

Data Insertion#

Real-Time Feature Computing#

Query#

Query Deployment Information#

Acquire All Library Names#

Acquire All Table Names#

Refresh APIServer Metadata Cache#