Create Data Comparison Task

Create a new data comparison task and specify the source, target, and the databases and tables to be compared.

Request URL: /openapi/v1/comparedata/create

Request Method: POST

Before You Call

sourceDsId and targetDsId can be obtained from data[].datasourceId in Retrieve Data Source List.
If the data source has not been created yet, call Create Data Source first, then use data.datasourceId from the response.
databaseName, targetDatabase, tableName, and targetTable must use the real database names and table names in the source and target instances.

Request Parameters

Parameter	Type	Required	Description	Example
name	String	Yes	Task name. It is recommended to use a name that reflects the business purpose and comparison scope for easier follow-up queries.	`compare-docx-proof-20260508163538`
sourceDsId	String	Yes	Source data source ID, which represents the baseline side of the comparison. You can get it from `data[].datasourceId` in Retrieve Data Source List.	`ds-ct192k3jlj4f`
targetDsId	String	Yes	Target data source ID, which represents the side compared against the source. You can get it from `data[].datasourceId` in Retrieve Data Source List.	`ds-d37s953l33d3`
taskMode	String	Yes	Comparison type. The current example uses `FULL`, which means full comparison.	`FULL`
objectConfig	JSON	Yes	Comparison scope configuration. Use `all`, `databaseList`, `schemaList`, `tableList`, and `columnList` together to define the instance, database, schema, table, and column mapping scope to compare.	See the example below

objectConfig Fields

Parameter	Type	Description	Example
all	Boolean	Whether to directly select all objects under the instance. If `true`, you do not need to specify databases or tables one by one. If `false`, you need to provide `databaseList`.	`false`
allDatabase	Boolean	Whether to select all databases. This is usually consistent with `all`. Set it to `false` when you configure databases, tables, or column mappings explicitly.	`false`
databaseList	Array	List of databases to compare. When multiple databases are needed, pass multiple objects in a JSON array.	`[{...}]`
migrateTrigger	Boolean	Whether to include trigger objects. For data comparison tasks, this is usually set to `false`.	`false`
migrateEvent	Boolean	Whether to include event objects. For data comparison tasks, this is usually set to `false`.	`false`

databaseList Fields

Parameter	Type	Description	Example
objectType	String	Object type. Use `database` for a database object.	`database`
databaseName	String	Source database name. It must match an actual database name in the instance identified by `sourceDsId`.	`9zdbtest2`
targetDatabase	String	Target database name. It must match an actual database name in the instance identified by `targetDsId`.	`9zdbtest3`
targetSchema	String	Target schema name. Required only when the target side is a three-level data source.	`public`
all	Boolean	Whether to compare all tables in the database. If `true`, all tables in the database are included. If `false`, you need to provide `tableList`.	`true`
tableList	Array	List of tables to compare for two-level data sources. When multiple tables are needed, pass multiple objects in a JSON array.	`[{...},{...}]`
schemaList	Array	List of schemas to compare for three-level data sources such as PostgreSQL or SQL Server.	`[{...}]`

schemaList Fields

Parameter	Type	Description	Example
objectType	String	Object type. Use `schema` for a schema object.	`schema`
schemaName	String	Source schema name.	`public`
targetSchema	String	Target schema name.	`public`
targetDatabase	String	Target database name. You can specify it at the schema level when the target side is a two-level data source.	`test_db`
all	Boolean	Whether to compare all tables in the schema. If `false`, you need to provide `tableList`.	`false`
tableList	Array	List of tables to compare.	`[{...}]`

tableList Fields

Parameter	Type	Description	Example
databaseName	String	Source database name. Provide this field for cross-level mappings or when you need to explicitly specify the database.	`9zdbtest2`
targetDatabase	String	Target database name. Provide this field for cross-level mappings or when you need to explicitly specify the target database.	`9zdbtest3`
schemaName	String	Source schema name. Required when the source side is a three-level data source.	`public`
targetSchema	String	Target schema name. Required when the target side is a three-level data source.	`public`
tableName	String	Source table name. It must match an actual table name in the source database.	`sbtest1`
targetTable	String	Target table name. It must match an actual table name in the target database.	`sbtest1`
sourceKeyColumns	String	Source primary key or unique key columns used to identify records during comparison.	`id`
columnList	Array	Source-to-target column mapping list. Provide this field when source and target column names are different, or when you need to explicitly specify column types.	`[{...}]`

columnList Fields

Parameter	Type	Description	Example
objectType	String	Object type. Use `column` for a column object.	`column`
columnName	String	Source column name.	`id`
targetColumn	String	Target column name.	`id_t`
columnType	String	Source column type. Provide this field for heterogeneous data source comparisons or when you need to explicitly specify the type.	`NUMBER`
targetColumnType	String	Target column type. Provide this field for heterogeneous data source comparisons or when you need to explicitly specify the type. For homogeneous data sources, you can pass an empty string.	`numeric`

How to Use the Returned Value

data in the successful response is the taskId created for this task. You need this value when calling Start Data Comparison Task, Query Data Comparison Main Task Details, Stop Data Comparison Task, and Delete Data Comparison Task.

Request Example

{
  "name": "compare-docx-proof-20260508163538",
  "objectConfig": {
    "all": false,
    "databaseList": [
      {
        "databaseName": "9zdbtest2",
        "targetDatabase": "9zdbtest3",
        "all": true,
        "tableList": [
          {
            "tableName": "sbtest1",
            "targetTable": "sbtest1"
          },
          {
            "tableName": "sbtest2",
            "targetTable": "sbtest2"
          }
        ]
      }
    ]
  },
  "sourceDsId": "ds-ct192k3jlj4f",
  "targetDsId": "ds-d37s953l33d3",
  "taskMode": "FULL"
}

objectConfig Example with Column Mapping

If source and target table names or column names are different, use targetTable in tableList to specify the target table, and use columnList to specify the source-to-target column mappings.

Two-level data source to two-level data source, such as MySQL to MySQL:

{
  "all": false,
  "allDatabase": false,
  "databaseList": [
    {
      "objectType": "database",
      "databaseName": "wzy_test1",
      "targetDatabase": "wzy_test1",
      "all": false,
      "tableList": [
        {
          "databaseName": "wzy_test1",
          "tableName": "test_ys1",
          "targetTable": "test_ys2",
          "sourceKeyColumns": "c_int_t",
          "columnList": [
            {
              "objectType": "column",
              "columnName": "c_bit_t1",
              "targetColumn": "c_bit_t2",
              "targetColumnType": ""
            },
            {
              "objectType": "column",
              "columnName": "c_int_t",
              "targetColumn": "c_int_t",
              "targetColumnType": "int"
            }
          ]
        }
      ]
    }
  ],
  "migrateTrigger": false,
  "migrateEvent": false
}

Three-level data source to three-level data source, such as PostgreSQL to PostgreSQL:

{
  "all": false,
  "allDatabase": false,
  "databaseList": [
    {
      "objectType": "database",
      "databaseName": "postgres",
      "targetDatabase": "postgres",
      "all": false,
      "schemaList": [
        {
          "objectType": "schema",
          "schemaName": "public",
          "targetSchema": "public",
          "all": false,
          "tableList": [
            {
              "databaseName": "postgres",
              "schemaName": "public",
              "targetSchema": "public",
              "tableName": "activities",
              "targetTable": "activities",
              "sourceKeyColumns": "id",
              "columnList": [
                {
                  "objectType": "column",
                  "columnName": "id",
                  "targetColumn": "id",
                  "columnType": "integer",
                  "targetColumnType": "integer"
                },
                {
                  "objectType": "column",
                  "columnName": "activity_name",
                  "targetColumn": "activity_name",
                  "columnType": "character varying",
                  "targetColumnType": "character varying"
                }
              ]
            }
          ],
          "otherStoredObjectList": []
        }
      ]
    }
  ],
  "migrateTrigger": false,
  "migrateEvent": false
}

Two-level data source to three-level data source, such as Oracle to PostgreSQL:

{
  "all": false,
  "allDatabase": false,
  "databaseList": [
    {
      "objectType": "database",
      "databaseName": "NINEDATA",
      "targetDatabase": "postgres",
      "targetSchema": "public",
      "all": false,
      "tableList": [
        {
          "databaseName": "NINEDATA",
          "targetDatabase": "postgres",
          "targetSchema": "public",
          "tableName": "EMPLOYEES",
          "targetTable": "activities",
          "sourceKeyColumns": "ID",
          "columnList": [
            {
              "objectType": "column",
              "columnName": "ID",
              "targetColumn": "id",
              "columnType": "NUMBER",
              "targetColumnType": "integer"
            },
            {
              "objectType": "column",
              "columnName": "NAME",
              "targetColumn": "activity_name",
              "columnType": "VARCHAR2",
              "targetColumnType": "character varying"
            }
          ]
        }
      ]
    }
  ],
  "migrateTrigger": false,
  "migrateEvent": false
}

Three-level data source to two-level data source:

{
  "all": false,
  "allDatabase": false,
  "databaseList": [
    {
      "objectType": "database",
      "databaseName": "postgres",
      "targetDatabase": "9zdbtest2",
      "all": false,
      "schemaList": [
        {
          "objectType": "schema",
          "schemaName": "public",
          "targetDatabase": "9zdbtest2",
          "all": false,
          "tableList": [
            {
              "databaseName": "postgres",
              "schemaName": "public",
              "targetDatabase": "9zdbtest2",
              "tableName": "activities",
              "targetTable": "sbtest1",
              "sourceKeyColumns": "id",
              "columnList": [
                {
                  "objectType": "column",
                  "columnName": "id",
                  "targetColumn": "id",
                  "columnType": "integer",
                  "targetColumnType": "int"
                },
                {
                  "objectType": "column",
                  "columnName": "activity_name",
                  "targetColumn": "c",
                  "columnType": "character varying",
                  "targetColumnType": "char"
                }
              ]
            }
          ],
          "otherStoredObjectList": []
        }
      ]
    }
  ],
  "migrateTrigger": false,
  "migrateEvent": false
}

Response Parameters

Parameter	Type	Description	Example
success	Boolean	Whether the request is successful.	`true`
requestId	String	Request ID, which can be used for troubleshooting and tracing.	`Em1u9SHH-kqqraVGnllse6BZdmnh5DQM`
data	String	Data comparison task ID, which is the `taskId` used by follow-up APIs.	`cd-tepmjmnj6o`

Successful Invocation Example

{
  "success": true,
  "requestId": "Em1u9SHH-kqqraVGnllse6BZdmnh5DQM",
  "data": "cd-tepmjmnj6o"
}

Create Data Comparison Task

Before You Call​

Request Parameters​

objectConfig Fields​

databaseList Fields​

schemaList Fields​

tableList Fields​

columnList Fields​

How to Use the Returned Value​

Request Example​

objectConfig Example with Column Mapping​

Response Parameters​

Successful Invocation Example​