Create a tenant|V4.4.2| docs|Distributed Database

This topic describes how to create a tenant by using an API.

API details

Constraints

The obshell server performs security verification on this API. For more information, see API hybrid encryption.

Request path

POST /api/v1/tenant

Request parameters

Parameter	Type	Required	Example value	Description
name	string	Yes	t1	The name of the tenant to be created.
zone_list	[]ZoneParam	Yes	For more information, see the data structure of ZoneParam below.	The resource specifications and replica distribution of the tenant.
mode	string	No	MYSQL	The type of the tenant to be created. Valid value: `MYSQL`.
primary_zone	string	No	RANDOM	The primary zone of the tenant. The zone that provides read and write services for the tenant.
whitelist	string	No	%	The access allowlist of the tenant.
root_password	string	No	123456	The root user password of the tenant.
scenario	string	No	kv	The workload type of the tenant. Valid values: `express_oltp`: applies to workloads such as trade and payment core systems and high-throughput internet applications. It does not support foreign keys, stored procedures, long transactions, large transactions, complex connections, or complex subqueries. `complex_oltp`: applies to workloads such as banking and insurance systems. These workloads usually involve complex joins, complex correlated subqueries, PL-written batch jobs, long transactions, and large transactions. Parallel execution is sometimes used for short-running queries. `olap`: applies to real-time data warehouse analysis scenarios. `htap`: applies to hybrid OLAP and OLTP workloads. It is usually used to obtain real-time insights from active operational data, fraud detection, and personalized recommendations. `kv`: applies to key-value workloads and wide-column workloads similar to HBase. These workloads typically have very high throughput and are sensitive to latency. Note This option is supported only when the OceanBase cluster version is V4.3.0 or later.
variables	map[string]interface{}	No	{ "max_connections": 1000, "ob_query_timeout": 10000000 }	The system variables of the tenant.
parameters	map[string]interface{}	No	{ "backup_data_file_size": "2G", "arbitration_timeout": "10s" }	The parameters of the tenant.
charset	string	No	N/A	The character set of the tenant.
collation	string	No	N/A	The collation of the tenant.
read_only	bool	No	false	Specifies whether the tenant is read-only.
comment	string	No	N/A	The information of the tenant.
import_script	bool	No	false	Specifies whether to import timezone data and GIS metadata to the sys tenant. The default value is `false`. Note This option is supported starting with obshell V4.2.4.2.

The data structure of ZoneParam:

Parameter	Type	Required	Example value	Description
name	string	Yes	zone1	The name of the zone.
replica_type	string	No	FULL	The replica type of the tenant in the zone. Valid values: `FULL` (a full-featured replica) and `READONLY` (a read-only replica). Default value: `FULL`.
unit_config_name	string	Yes	s1	The resource specification of the tenant resource pool in the zone.
unit_num	int	Yes	1	The number of units of the tenant in the zone.

Response parameters

Parameter	Type	Description
successful	bool	Indicates whether the request was successful.
timestamp	time.Time	The timestamp when the server finishes the request.
duration	int	The time taken by the server to process the request, in milliseconds.
status	int	The HTTP status code that conforms to the HTTP status specification.
traceId	string	The Trace ID of the request.
data	DagDetailDTO	The information about the asynchronous task. For more information, see the DagDetailDTO data structure below.
error	ApiError	The error generated by the request. It contains the following information: `code`: the error code. `message`: the detailed error message. `subErrors`: the sub-error message.

The following table describes the DagDetailDTO data structure.

Parameter	Type	Description
id	string	The general ID of the DAG.
dag_id	int	The DAG ID, which is the primary key stored in OceanBase Database.
name	string	The name of the DAG.
stage	int	The current execution stage of the DAG.
max_stage	int	The total number of stages in the DAG execution process.
state	string	The execution status of the DAG.
operator	string	The operation type for DAG execution.
start_time	time.Time	The start time of DAG execution.
end_time	time.Time	The end time of DAG execution.
additional_data	map[string]any	Other data of the DAG.
nodes	[]NodeDetailDTO	The information about all nodes in the DAG. For more information, see Get the details of a node.

Examples

Request example

POST 10.10.10.1:2886/api/v1/tenant

{
    "name": "t1",
    "zone_list": [
        {
            "name": "zone1",
            "unit_config_name": "s1",
            "unit_num": 1
        },
        {
            "name": "zone2",
            "unit_config_name": "s1",
            "unit_num": 1
        },
        {
            "name": "zone3",
            "unit_config_name": "s1",
            "unit_num": 1
        }
    ],
    "mode": "MYSQL",
    "read_only": false
}

Response example

{
    "successful": true,
    "timestamp": "2024-10-12T17:35:23.85443063+08:00",
    "duration": 64,
    "status": 200,
    "traceId": "42ee97601d3de292",
    "data": {
        "id": "18",
        "dag_id": 8,
        "name": "Create tenant t1",
        "stage": 1,
        "max_stage": 3,
        "state": "READY",
        "operator": "RUN",
        "start_time": "0001-01-01T00:00:00Z",
        "end_time": "0001-01-01T00:00:00Z",
        "additional_data": null,
        "nodes": null
    }
}

References

In addition to using the CLI to call the API, you can also use the SDK.

For more information about how to call APIs by using obshell-sdk-python, see Create a tenant.
For more information about how to call APIs by using obshell-sdk-go, see Create a tenant.

Create a tenant