SubmitPreCheck|V4.2.12|OceanBase Migration Service| docs|Distributed Database

SubmitPreCheck

Last Updated：2026-01-29 07:14:58 Updated

This topic describes the SubmitPreCheck API provided by OceanBase Migration Service (OMS) Community Edition.

Overview

You can call this operation to create a precheck task.

API details

Constraints

This interface applies to OMS Community Edition V4.2.12-CE and later.

Request path

POST /api/v2?Action=SubmitPreCheck

Request parameters

Parameter	Type	Description
name	string	The name of the task. It cannot contain spaces.
type	string	The type of the task. Valid values: `MIGRATION` and `SYNC`. `MIGRATION` indicates a data migration task, and `SYNC` indicates a data synchronization task.
labelIds	array	The ID of the tag. The maximum number of tags allowed is 5.
sourceEndpointId	string	The ID of the source data source. You need to call the `ListDataSource` interface to obtain the ID. The format is `e_****`.
sinkEndpointId	string	The ID of the destination data source. You need to call the `ListDataSource` interface to obtain the ID. The format is `e_****`.
transferMapping	object	The mapping information of the transfer object.
├─ mode	string	The mapping mode of the transfer object. Valid values: `SPECIFIC` and `WILDCARD`. `SPECIFIC` indicates that the objects are specified. `WILDCARD` indicates that the objects are matched by using rules.
├─ databases	array	The list of database objects. For more information, see the data structure described in the "databases/databasesBlack data structure" section.
├─ databasesBlack	array	The list of database objects in the blacklist. For more information, see the data structure described in the "databases/databasesBlack data structure" section.
├─ tableAndViewWhiteList	array	The list of tables and views in the wildcard whitelist.
├─ tableAndViewBlackList	array	The list of tables and views in the wildcard blacklist.
commonTransferConfig	object	The general transfer configuration.
├─ tableCategory	string	The supported table type. Valid values: `ALL`, `WITH_UNIQUE_ROW_ID`, and `WITHOUT_UNIQUE_ROW_ID`. Default value: `ALL`.
├─ activeActive	boolean	Specifies whether the task is a disaster recovery active-active task.
├─ mqSerializerType	string	The JSON serialization type when data is delivered to a message queue. Valid values: `DEFAULT`, `CANAL`, `DATAWORKS_V2`, `SHAREPLEX`, `DEFAULT_WITH_SCHEMA`, `DEBEZIUM`, `DEBEZIUMFLATTEN`, and `DEBEZIUMSMT`.
├─ mqPartitionMode	string	The partition routing mode when data is delivered to a message queue. Valid values: `ONE`, `HASH`, and `TABLE`. `ONE` specifies the partition to which data is delivered. `HASH` specifies to deliver data to a partition by using the hash value of the primary key or shard key. `TABLE` specifies to deliver data to a partition by using the hash value of the database or table name.
├─ mqPartition	integer	The partition to which data is delivered. This parameter is valid only when the value of `partitionMode` is `ONE`.
├─ datahubTopicType	string	The type of the topic when data is delivered to a DataHub message queue. Valid values: `TUPLE` and `BLOB`.
├─ rocketMqProducerGroup	string	The name of the producer group. This parameter is valid only when the destination is a RocketMQ instance. Default value: `OMS`.
├─ rocketMqMsgTags	string	The message tag. This parameter is valid only when the destination is a RocketMQ instance. Default value: `default->default_tag`. That is, if the value of this parameter is `default`, a `_tag` suffix is automatically added.
├─ rocketMqEnableMsgTrace	boolean	Specifies whether to enable message tracing. This parameter is valid only when the destination is a RocketMQ instance.
├─ rocketMqSendMsgTimeout	long	The message delivery timeout period, in seconds. This parameter is valid only when the destination is a RocketMQ instance.
├─ dataWorksBusinessName	string	The business system identifier.
enableStructTransfer	boolean	Specifies whether to enable schema transfer.
structTransferConfig	object	The schema transfer configuration.
├─ byteCharConvertStrategy	string	The byte/char conversion strategy. Valid values: `IGNORE_BYTE_IF_BYTE_USED`, `FORCE_CHAR_IF_BYTE_USED`, `EXPAND_LEN_IF_BYTE_USED`, and `DO_NOTHING_IF_BYTE_USED` (default value).
├─ deferIndexCreation	boolean	Specifies whether to allow index creation after data migration. Default value: `false`.
├─ shardsCount	integer	The number of index shards.
├─ replicasCount	integer	The number of index replicas.
├─ dateFormat	string	The date format. For example, `yyyy-MM-dd HH:mm:ss`.
enableFullTransfer	boolean	Specifies whether to enable full data transfer.
enableFullVerify	boolean	Specifies whether to enable full data verification.
fullTransferConfig	object	The full data transfer configuration.
├─ nonePkUkTruncateDstTable	boolean	Specifies whether to truncate the destination table when you perform full data migration from a table without a unique index.
├─ allowDestTableNotEmpty	string	The strategy for handling the destination table when the destination table contains records. Valid values: Ignore and Stop Migration. Set this parameter to `true` to ignore the destination table data. If the destination table contains data, OMS Community Edition will write data to the destination table by using the ignore or overwrite strategy. Overwrite is supported only when the destination is a MySQL database or OceanBase Database Community Edition. Notice When you select Ignore, full data verification will pull data by using the IN mode. Therefore, the verification cannot detect data that exists in the destination table but not in the source table. In addition, the verification performance will be degraded. Set this parameter to `false` to stop the migration. If the destination table contains data, the full data migration will fail. In this case, you must process the destination table data before you continue the migration. Notice If you click Restore after an error occurs, OMS Community Edition will ignore this configuration option and continue to migrate the table data. Proceed with caution.
├─ fullTransferSpeedMode	string	The full data migration concurrency speed. Valid values: `STEADY`, `NORMAL`, and `FAST`. If the migration task contains a full data migration step, you must specify the `FullTransferSpeedMode` parameter. You can specify `NORMAL`.
├─ fullVerifySpeedMode	string	The speed of full verification, which can be STEADY, NORMAL, or FAST. If the full verification step is enabled, the FullVerifySpeedMode parameter must be specified. You can specify NORMAL.
enableIncrTransfer	boolean	Specifies whether to enable incremental synchronization.
enableReverseIncrTransfer	boolean	Specifies whether to enable reverse incremental synchronization.
incrTransferConfig	object	The configuration of incremental synchronization.
├─ startTimestamp	string	The start point of incremental synchronization. This parameter is supported only when incremental synchronization is enabled but full synchronization is not.
├─ recordTypeWhiteList	array	The types of incremental data to be synchronized during the incremental synchronization phase. Valid values: HEARTBEAT, INSERT, UPDATE, DELETE, BEGIN, COMMIT, ROLLBACK, DDL, and ROW.
├─ storeLogKeptHour	integer	The time for which logs are retained when incremental synchronization is enabled and the incremental log pull component is Store. Unit: hour. Default value: 7 days. Maximum supported value: 365 days.
├─ enableSequencingWithinTxn	boolean	Specifies whether to enable sequence generation within a transaction when incremental synchronization is enabled and the incremental log pull component is Store.
├─ incrSyncConcurrency	integer	The number of threads for incremental synchronization. Default value: 64.
├─ enableIncrSyncStatistics	boolean	Specifies whether to enable statistics collection for incremental records (DML and DDL).

databases/databasesBlack data structure

Parameter	Type	Description
mappedName	string	The name of the target database.
name	string	The name of the source database.
id	string	The ID of the database.
tables	array	The list of configurations of the table objects to be transmitted in the current database. When `mode` is set to `WILDCARD`, this parameter specifies the configuration of the specific blacklist or whitelist, which applies to tables and views.
├─ mappedName	string	The mapped name of the table.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in a standard SQL statement, which is used to configure row filtering.
├─ filterColumns	array	The collection of filtered columns.
├─ shardColumns	array	The collection of shard columns.
views	array	The list of configurations of the view objects to be transmitted in the current database.
├─ mappedName	string	The mapped name of the view.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in a standard SQL statement, which is used to configure row filtering.
├─ filterColumns	array	The collection of filtered columns.
├─ shardColumns	array	The collection of shard columns.
specificTables	array	The list of configurations of the specific table objects. When `mode` is set to `WILDCARD`, this parameter specifies the renaming and row filtering configurations of the specific table objects.
├─ mappedName	string	The mapped name of the table.
├─ name	string	The name of the table.
├─ id	string	The ID of the table.
├─ whereClause	string	The `WHERE` clause in a standard SQL statement, which is used to configure row filtering.
├─ filterColumns	array	The collection of filtered columns.
├─ shardColumns	array	The collection of shard columns.
specificViews	array	The list of configurations of the specific view objects. When `mode` is set to `WILDCARD`, this parameter specifies the renaming configuration of the specific view objects.
├─ mappedName	string	The mapped name of the view.
├─ name	string	The name of the view.
├─ id	string	The ID of the view.
├─ whereClause	string	The `WHERE` clause in a standard SQL statement, which is used to configure row filtering.
├─ filterColumns	array	The collection of filtered columns.
├─ shardColumns	array	The collection of shard columns.
procedures	array	The list of configurations of stored procedures in the current database.
├─ name	string	The name of the stored procedure.
├─ mappedName	string	The mapped name of the stored procedure.
functions	array	The list of configurations of functions in the current database.
├─ name	string	The name of the function.
├─ mappedName	string	The mapped name of the function.

Response parameters

Parameter	Type	Description
success	boolean	Indicates whether the call was successful.
errorDetail	object	The error details.
code	string	The error code.
message	string	The description.
advice	string	The recommendation.
requestId	string	The request ID.
pageNumber	integer[int32]	The page number. This parameter takes effect only when you perform a paginated query.
pageSize	integer[int32]	The page size. This parameter takes effect only when you perform a paginated query.
totalCount	integer[int64]	The total number of items. This parameter takes effect only when you perform a paginated query.
cost	string	The request duration, in seconds.
data	string	The ID of the precheck task.

Examples

Request example

{
    "name":"test",
    "type":"MIGRATION",
    "labelIds":[
        "l_4w****wygjk"
    ],
    "sourceEndpointId":"e_4wg07f****",
    "sinkEndpointId":"e_4wfy2****",
    "transferMapping":{
        "mode":"SPECIFIC",
        "databases":[
            {
                "mappedName":"gez3***",
                "name":"ion1****bmysql",
                "id":null,
                "tables":[
                    {
                        "mappedName":"tion12***20obmysql2",
                        "name":"GRATION129****",
                        "id":null,
                        "whereClause":null,
                        "filterColumns":null,
                        "shardColumns":null,
                    }
                ],
                "views":null,
                "procedures":[
                    {
                        "name": "baxxx_crxxx_user",
                        "mappedName": "baxxx_crxxx_user_rename"
                    }
                ],
                "functions":[
                    {
                        "name": "rand_string",
                        "mappedName": "rand_string_rename"
                    }
                ],
                "specificTables":null,
                "specificViews":null
            }
        ],
        "databasesBlack":null,
        "tableAndViewWhiteList":null,
        "tableAndViewBlackList":null
    },
    "commonTransferConfig":{
        "tableCategory":null,
        "activeActive":false,
        "mqSerializerType":null,
        "mqPartitionMode":null,
        "mqPartition":0,
        "datahubTopicType":null,
        "rocketMqProducerGroup":null,
        "rocketMqMsgTags":null,
        "rocketMqEnableMsgTrace":null,
        "rocketMqSendMsgTimeout":null,
        "dataWorksBusinessName":null
    },
    "enableStructTransfer":true,
    "structTransferConfig":{
        "byteCharConvertStrategy":"DO_NOTHING_IF_BYTE_USED",
        "deferIndexCreation":true,
        "shardsCount": 1,
        "replicasCount": 1,
        "dateFormat": "yyyy-MM-dd HH:mm:ss"
    },
    "enableFullTransfer":true,
    "enableFullVerify":true,
    "fullTransferConfig":{
        "nonePkUkTruncateDstTable":null,
        "allowDestTableNotEmpty":true,
        "fullTransferSpeedMode":"NORMAL",
        "fullVerifySpeedMode":"NORMAL"
    },
    "enableIncrTransfer":true,
    "enableReverseIncrTransfer":true,
    "incrTransferConfig":{
        "startTimestamp":1689201369,
        "recordTypeWhiteList":[
            "DELETE",
            "INSERT",
            "UPDATE"
        ],
        "storeLogKeptHour":120,
        "enableSequencingWithinTxn":true,
        "incrSyncConcurrency":64,
        "enableIncrSyncStatistics":true
    }
}

Response example

{
    "success": true,
    "errorDetail": null,
    "code": null,
    "message": null,
    "advice": null,
    "requestId": "b1854cd****",
    "pageNumber": null,
    "pageSize": null,
    "totalCount": null,
    "cost": "1502 ms",
    "data": "t_7di1uvmxd340"
}

Enterprise Edition

Community Edition