All Products
Search
Document Center

Development Edition of OpenSearch API V3

Last Updated: Sep 10, 2021

Latest version

  • Latest API version: V3

  • Last update: 2017-07-11

2017-07-11

  • The group parameter of applications is changed to the type parameter.

  • The type of advanced applications is changed to enhanced.

Version:

development

Parameters

Parameter

Type

Description

Example

auto_switch

Boolean

Specifies whether to enable automatic switching after data is imported to a standard application.

true

cluster_name

String

cluster

"example"

description

String

The description of the application. Format: .{0,60}

"App description"

fetch_fields

Array

The fields to be displayed in query results.

["id","name"]

group[name]

String

The name of the application. Format: ^(?!ops_)[a-zA-z]\w*$

"my_app_name"

group[versions]

Array

All versions of the application.

["10001","10002"]

id

String

The ID of the application. Format: ^\d{1,10}$.

"10001"

index_task[progress]

Integer

The progress of the task on a scale of 1 to 100.

42

quota[doc_size]

Number

The storage capacity for documents in the application. Unit: GB. The minimum value of this parameter is 0.2.

0.3

quota[qps]

Integer

The maximum number of queries per second. Unit: count per second. The minimum value of this parameter is 5.

6

quota_reviewing_task[data][doc_size]

Number

The storage capacity for documents in the application. Unit: GB. The minimum value of this parameter is 0.2.

0.3

quota_reviewing_task[data][qps]

Integer

The maximum number of queries per second. Unit: count per second. The minimum value of this parameter is 5.

6

quota_reviewing_task[id]

String

The ID of the task.

"1001"

quota_reviewing_task[message]

String

The remarks in approval results.

"The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."

realtime_shared

Boolean

Specifies whether to share real-time streams. This parameter is unavailable if the data source of a standard application is a relational database such as a MySQL database.

true

schema[indexes][filter_fields]

Array

The array of attribute fields.

["field"]

schema[indexes][search_fields]

Object

The array of index fields.

{"default":{"fields":["text_field"],"analyzer":"chn_standard"}}

schema[route_field]

Nullable string

The routing field, which is used in combination with the cluster_name parameter.

"test_field"

schema[tables]

Object

The schema of the application.

{"main":{"fields":{"id":{"type":"INT","name":"id","primary_key":true}}}}

status

Integer

The status of the application. The following states are supported: 1: Normal; 5: Suspended; 6: Frozen; 8: Being initialized; 9: Invalid; 11: Waiting for data initialization; 12: Data being initialized. Valid values: 1, 5, 6, 7, 8, and 9.

1

type

String

The type of the application. The type of advanced applications is enhanced. The type of standard applications is standard. Default value: enhanced.

"enhanced"

virtual_cluster

String

cluster

"example"

Application creation

Create an application.

  • When you create a standard application, if the specified application name already exists, a new version of the application is created.

  • When you create a version of an existing application, you must specify the auto_switch and realtime_shared parameters.

  • When you create a version of an existing application, the values of the quota and `virtual_cluster` parameters are the same as those of the previous version of the application.

  • When you create a version of an existing application, the modification of the quota parameter does not take effect.

POST /apps

Required parameters

Parameter

Type

Description

Example

group[name]

String

The name of the application. Format: ^(?!ops_)[a-zA-z]\w*$

"my_app_name"

quota[doc_size]

Number

The storage capacity for documents in the application. Unit: GB. The minimum value of this parameter is 0.2.

0.3

quota[qps]

Integer

The maximum number of queries per second. Unit: count per second. The minimum value of this parameter is 5.

6

schema[indexes][filter_fields]

Array

The array of attribute fields.

["field"]

schema[indexes][search_fields]

Object

The array of index fields.

{"default":{"fields":["text_field"],"analyzer":"chn_standard"}}

schema[tables]

Object

The schema of the application.

{"main":{"fields":{"id":{"type":"INT","name":"id","primary_key":true}}}}

Optional parameters

Parameter

Type

Description

Example

auto_switch

Boolean

Specifies whether to enable automatic switching after data is imported to a standard application.

true

data_sources

Array

The data sources.

[{"table_name":"main","type":"mysql","fields":[],"plugins":{},"key_field":"literal_pk","parameters":{"filter":"","db_table_name":"antispam_keyword","db_key":"","db_user":"","auto_sync":"true","db_password":""}}]

description

String

The description of the application. Format: .{0,60}

"App description"

fetch_fields

Array

The fields to be displayed in query results.

["id","name"]

first_ranks/active

Boolean

Specifies whether to set the rough sort expression as the default sort expression.

true

first_ranks/description

String

The description of the rough sort expression.

"I am a firstRank"

first_ranks/meta/arg

String

A parameter in the expression function. Default value: "".

"int_field"

first_ranks/meta/attribute

String

The attribute of the parameter.

"timeliness()"

first_ranks/meta/weight

Number

The weight of the parameter. Format: ^[-+]?[0-9]*\.?[0-9]+$

42.0

first_ranks/name

String

The name of the rough sort expression. Format: ^[-+]?[ops_)(?!OPS_)[a-zA-Z][a-zA-Z0-9_]{0,29}$

"first_rank"

query_processors/active

Boolean

Specifies whether the analyzer is active.

true

query_processors/indexes

Array

The index fields to which the analyzer applies. If this parameter is set to _ALL_INDEXES_, the analyzer applies to all the index fields in the application. Do not specify `_ALL_INDEXES_` and single index fields at the same time.

["index_name"]

query_processors/name

String

The name of the analyzer. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"query_processor"

query_processors/processors/name

String

The name of the rule. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"example"

realtime_shared

Boolean

Specifies whether to share real-time streams. This parameter is unavailable if the data source of a standard application is a relational database such as a MySQL database.

true

schema[route_field]

Nullable string

The routing field, which is used in combination with the cluster_name parameter.

"test_field"

second_ranks/active

Boolean

Specifies whether to set the fine sort expression as the default sort expression.

true

second_ranks/description

String

The description of the fine sort expression.

"example"

second_ranks/meta

String

The structure of the expression.

"example"

second_ranks/name

String

The name of the fine sort expression.

"example"

suggests/black_list

Array

The blacklist of the drop-down suggestion.

[null]

suggests/fields

Array

The fields that are used as the data source of the drop-down suggestion.

[null]

suggests/name

String

The name of the drop-down suggestion.

"example"

suggests/white_list

Array

The whitelist of the drop-down suggestion.

[null]

summaries/active

Boolean

Specifies whether the current search result summary is the default one.

true

summaries/meta/element

String

The element that is used for highlighting.

"em"

summaries/meta/ellipsis

String

The string that is used to represent the data that is not displayed.

"..."

summaries/meta/field

String

The field based on which the summary is generated.

"example"

summaries/meta/len

Integer

The length of each summary snippet. Valid values: [1,300].

42

summaries/meta/snippet

Integer

The number of summary snippets that each query can hit. Valid values: [1,5].

1

summaries/name

String

The name of the search result summary. Set this parameter to default.

"example"

type

String

The type of the application. The type of advanced applications is enhanced. The type of standard applications is standard. Default value: enhanced.

"enhanced"

virtual_cluster

String

The cluster to which the application belongs.

"example"

Sample response

HTTP/1.1 201 Created
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}

Application deletion

Delete an application or application version. When you delete a standard application, take note of the following items:

  • If the application has only one version, the application can be deleted.

  • If the application has two versions, only the offline version can be deleted.

DELETE /apps/{app_id_or_name}

Sample response

HTTP/1.1 200 OK
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}

Application details

Obtain the details of an application.

GET /apps/{app_id_or_name}

Sample response

HTTP/1.1 200 OK
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}

Application list

Obtain a list of applications.

  • Supported parameters: page and size

GET /apps

Optional parameters

Parameter

Type

Description

Example

page

String

The page number of the first page. Format: ^\d+$.

"1"

size

String

The number of entries per page. Format: ^\d+$.

"10"

Sample response

HTTP/1.1 200 OK
{
  "status": "OK",
  "headers": {
    "X-Total-Count": 100
  },
  "result": [
    {
      "id": "10001",
      "description": "App description",
      "type": "enhanced",
      "status": 1,
      "fetch_fields": [
        "id",
        "name"
      ],
      "index_task": {
        "progress": 42
      },
      "auto_switch": true,
      "realtime_shared": true,
      "quota": {
        "doc_size": 0.3,
        "qps": 6
      },
      "quota_reviewing_task": {
        "id": "1001",
        "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
        "data": {
          "doc_size": 0.3,
          "qps": 6
        }
      },
      "schema": {
        "tables": {
          "main": {
            "fields": {
              "id": {
                "type": "INT",
                "name": "id",
                "primary_key": true
              }
            }
          }
        },
        "indexes": {
          "search_fields": {
            "default": {
              "fields": [
                "text_field"
              ],
              "analyzer": "chn_standard"
            }
          },
          "filter_fields": [
            "field"
          ]
        },
        "route_field": "test_field"
      },
      "group": {
        "name": "my_app_name",
        "versions": [
          "10001",
          "10002"
        ]
      },
      "virtual_cluster": "example",
      "cluster_name": "example"
    }
  ]
}

Application updates

Update an application.

  • You cannot update the schema and data_sources parameters of a standard application.

PATCH /apps/{app_id_or_name}

Optional parameters

Parameter

Type

Description

Example

data_sources

Array

The data sources.

[{"table_name":"main","type":"mysql","fields":[],"plugins":{},"key_field":"literal_pk","parameters":{"filter":"","db_table_name":"antispam_keyword","db_key":"","db_user":"","auto_sync":"true","db_password":""}}]

description

String

The description of the application. Format: .{0,60}

"App description"

fetch_fields

Array

The fields to be displayed in query results.

["id","name"]

first_ranks/active

Boolean

Specifies whether to set the rough sort expression as the default sort expression.

true

first_ranks/description

String

The description of the rough sort expression.

"I am a firstRank"

first_ranks/meta/arg

String

A parameter in the expression function. Default value: "".

"int_field"

first_ranks/meta/attribute

String

The attribute of the parameter.

"timeliness()"

first_ranks/meta/weight

Number

The weight of the parameter. Format: ^[-+]?[0-9]*\.?[0-9]+$

42.0

first_ranks/name

String

The name of the rough sort expression. Format: ^[-+]?[ops_)(?!OPS_)[a-zA-Z][a-zA-Z0-9_]{0,29}$

"first_rank"

query_processors/active

Boolean

Specifies whether the analyzer is active.

true

query_processors/indexes

Array

The index fields to which the analyzer applies. If this parameter is set to _ALL_INDEXES_, the analyzer applies to all the index fields in the application. Do not specify `_ALL_INDEXES_` and single index fields at the same time.

["index_name"]

query_processors/name

String

The name of the analyzer. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"query_processor"

query_processors/processors/name

String

The name of the rule. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"example"

quota[doc_size]

Number

The storage capacity for documents in the application. Unit: GB. The minimum value of this parameter is 0.2.

0.3

quota[qps]

Integer

The maximum number of queries per second. Unit: count per second. The minimum value of this parameter is 5.

6

schema[indexes][filter_fields]

Array

The array of attribute fields.

["field"]

schema[indexes][search_fields]

Object

The array of index fields.

{"default":{"fields":["text_field"],"analyzer":"chn_standard"}}

schema[route_field]

Nullable string

The routing field, which is used in combination with the cluster_name parameter.

"test_field"

schema[tables]

Object

The schema of the application.

{"main":{"fields":{"id":{"type":"INT","name":"id","primary_key":true}}}}

second_ranks/active

Boolean

Specifies whether to set the fine sort expression as the default sort expression.

true

second_ranks/description

String

The description of the fine sort expression.

"example"

second_ranks/meta

String

The structure of the expression.

"example"

second_ranks/name

String

The name of the fine sort expression.

"example"

suggests/black_list

Array

The blacklist of the drop-down suggestion.

[null]

suggests/fields

Array

The fields that are used as the data source of the drop-down suggestion.

[null]

suggests/name

String

The name of the drop-down suggestion.

"example"

suggests/white_list

Array

The whitelist of the drop-down suggestion.

[null]

summaries/active

Boolean

Specifies whether the current search result summary is the default one.

true

summaries/meta/element

String

The element that is used for highlighting.

"em"

summaries/meta/ellipsis

String

The string that is used to represent the data that is not displayed.

"..."

summaries/meta/field

String

The field based on which the summary is generated.

"example"

summaries/meta/len

Integer

The length of each summary snippet. Valid values: [1,300].

42

summaries/meta/snippet

Integer

The number of summary snippets that each query can hit. Valid values: [1,5].

1

summaries/name

String

The name of the search result summary. Set this parameter to default.

"example"

type

String

The type of the application. The type of advanced applications is enhanced. The type of standard applications is standard. Default value: enhanced.

"enhanced"

virtual_cluster

String

cluster

"example"

Sample response

HTTP/1.1 200 OK
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}

Create an application version

Create a version based on the latest version of an existing application.

POST /apps/{app_id_or_name}/actions/fork

Optional parameters

Parameter

Type

Description

Example

auto_switch

Boolean

Specifies whether to enable automatic switching after data is imported to a standard application.

true

data_sources

Array

The data sources.

[{"table_name":"main","type":"mysql","fields":[],"plugins":{},"key_field":"literal_pk","parameters":{"filter":"","db_table_name":"antispam_keyword","db_key":"","db_user":"","auto_sync":"true","db_password":""}}]

description

String

The description of the application. Format: .{0,60}

"App description"

fetch_fields

Array

The fields to be displayed in query results.

["id","name"]

first_ranks/active

Boolean

Specifies whether to set the rough sort expression as the default sort expression.

true

first_ranks/description

String

The description of the rough sort expression.

"I am a firstRank"

first_ranks/meta/arg

String

A parameter in the expression function. Default value: "".

"int_field"

first_ranks/meta/attribute

String

The attribute of the parameter.

"timeliness()"

first_ranks/meta/weight

Number

The weight of the parameter. Format: ^[-+]?[0-9]*\.?[0-9]+$

42.0

first_ranks/name

String

The name of the rough sort expression. Format: ^[-+]?[ops_)(?!OPS_)[a-zA-Z][a-zA-Z0-9_]{0,29}$

"first_rank"

query_processors/active

Boolean

Specifies whether the analyzer is active.

true

query_processors/indexes

Array

The index fields to which the analyzer applies. If this parameter is set to _ALL_INDEXES_, the analyzer applies to all the index fields in the application. Do not specify `_ALL_INDEXES_` and single index fields at the same time.

["index_name"]

query_processors/name

String

The name of the analyzer. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"query_processor"

query_processors/processors/name

String

The name of the rule. Format: ^(?!ops_)(?!OPS_)[a-z][a-z0-9_]{0,15}$

"example"

realtime_shared

Boolean

Specifies whether to share real-time streams. This parameter is unavailable if the data source of a standard application is a relational database such as a MySQL database.

true

schema[indexes][filter_fields]

Array

The array of attribute fields.

["field"]

schema[indexes][search_fields]

Object

The array of index fields.

{"default":{"fields":["text_field"],"analyzer":"chn_standard"}}

schema[route_field]

Nullable string

The routing field, which is used in combination with the cluster_name parameter.

"test_field"

schema[tables]

Object

The schema of the application.

{"main":{"fields":{"id":{"type":"INT","name":"id","primary_key":true}}}}

second_ranks/active

Boolean

Specifies whether to set the fine sort expression as the default sort expression.

true

second_ranks/description

String

The description of the fine sort expression.

"example"

second_ranks/meta

String

The structure of the expression.

"example"

second_ranks/name

String

The name of the fine sort expression.

"example"

summaries/active

Boolean

Specifies whether the current search result summary is the default one.

true

summaries/meta/element

String

The element that is used for highlighting.

"em"

summaries/meta/ellipsis

String

The string that is used to represent the data that is not displayed.

"..."

summaries/meta/field

String

The field based on which the summary is generated.

"example"

summaries/meta/len

Integer

The length of each summary snippet. Valid values: [1,300].

42

summaries/meta/snippet

Integer

The number of summary snippets that each query can hit. Valid values: [1,5].

1

summaries/name

String

The name of the search result summary. Set this parameter to default.

"example"

type

String

The type of the application. The type of advanced applications is enhanced. The type of standard applications is standard. Default value: enhanced.

"enhanced"

virtual_cluster

String

cluster

"example"

Sample response

HTTP/1.1 201 Created
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}

Specify a version of an application as the current version

You can specify a version of an application as the current version. This feature is supported only for standard applications.

PUT /apps/{app_id_or_name}/actions/set-current

Optional parameters

Parameter

Type

Description

Example

id

String

The ID of the application. Format: ^\d{1,10}$.

"10001"

Sample response

HTTP/1.1 200 OK
{
  "status": "OK",
  "result": {
    "id": "10001",
    "description": "App description",
    "type": "enhanced",
    "status": 1,
    "fetch_fields": [
      "id",
      "name"
    ],
    "index_task": {
      "progress": 42
    },
    "auto_switch": true,
    "realtime_shared": true,
    "quota": {
      "doc_size": 0.3,
      "qps": 6
    },
    "quota_reviewing_task": {
      "id": "1001",
      "message": "The task is approved because the task meets meet business needs." or "The task is rejected because the task fails to meet business needs."
      "data": {
        "doc_size": 0.3,
        "qps": 6
      }
    },
    "schema": {
      "tables": {
        "main": {
          "fields": {
            "id": {
              "type": "INT",
              "name": "id",
              "primary_key": true
            }
          }
        }
      },
      "indexes": {
        "search_fields": {
          "default": {
            "fields": [
              "text_field"
            ],
            "analyzer": "chn_standard"
          }
        },
        "filter_fields": [
          "field"
        ]
      },
      "route_field": "test_field"
    },
    "group": {
      "name": "my_app_name",
      "versions": [
        "10001",
        "10002"
      ]
    },
    "virtual_cluster": "example",
    "cluster_name": "example"
  }
}