Help Center/ Data Replication Service/ API Reference/ APIs V5.0/ Data Processing/ Saving Data Filtering Rules

Updated on 2026-09-07 GMT+08:00

Saving Data Filtering Rules

Function

This API is used to save data filtering rules.

Constraints

1. When common filtering criteria involve subqueries, you need to configure advanced filtering criteria in advance.

2. Data Flows from MySQL to MySQL and from MySQL to Taurus support advanced filtering criteria.

Authorization Information

Each account has all the permissions required to call all APIs, but IAM users must be assigned the required permissions.

If you are using role/policy-based authorization, see Permissions and Supported Actions for details on the required permissions.
If you are using identity policy-based authorization, no identity policy-based permissions are required for calling this API.

URI

PUT /v5/{project_id}/jobs/{job_id}/filter-rules

**Table 1** URI parameters
Parameter	Mandatory	Type	Description
project_id	Yes	String	Definition Project ID of a tenant in a region. For details about how to obtain the project ID, see Obtaining a Project ID. Constraints N/A Range N/A Default Value N/A
job_id	Yes	String	Definition Task ID, which is used to specify the target task for which filtering rules are to be saved. Constraints N/A Range N/A Default Value N/A

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	No	String	Definition MIME type of the request body. Use the default value application/json. For APIs used to upload objects or images, the value varies depending on the flow type. Constraints N/A Range application/json Default Value application/json
X-Auth-Token	Yes	String	Definition User token obtained from IAM. It is a response to the API for obtaining a user token. This API is the only one that does not require authentication. The token is the value of X-Subject-Token in the response header. Constraints N/A Range N/A Default Value N/A
X-Language	No	String	Definition Request language type. Constraints Specify the request language type based on the supported languages. Range en-us: English zh-cn: Chinese es-us: Spanish pt-br: Portuguese Default Value en-us

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
general_filtering_list	No	Array of objects	Definition List of data filtering criteria, which includes information about the data filtering rules to be verified. For details, see Table 4. Constraints This parameter is mandatory when data_filter_type is set to common (simple condition-based filtering). Each element in the list represents a group of filtering criteria, including the list of objects to be filtered and source database filtering criteria SQL. The following key fields are included: filter_object_list (list of objects to be filtered) and source_filter_condition (source database filtering criteria SQL). Application condition: This parameter is mandatory when data_filter_type is set to common. Range N/A Default Value N/A
advanced_setting_list	No	Array of objects	Definition List of advanced settings for data filtering. This parameter is used to configure advanced filtering rules for associated tables, including detailed filtering configurations such as the database name, table name, column name, and index. For details, see Table 6. Constraints Currently, only data flow from MySQL to MySQL supports this function. Application condition: This parameter is mandatory when data_filter_type is set to config. Range N/A Default Value N/A
source	No	String	Definition Source scenario of the verification request. This parameter is used to determine whether the data filtering rule verification is from the data synchronization task execution scenario or the data comparison task execution scenario. Constraints N/A Range job: filtering rule verification during the execution of a data synchronization task compare: filtering rule verification during the execution of a data comparison task Default Value job
data_filter_type	No	String	Definition Data filtering type. This parameter specifies the mode of the data filtering rule. The value common indicates simple condition-based filtering (single-table filtering condition), and the value config indicates association table filtering (multi-table association condition filtering). Constraints When simple condition-based filtering involves subqueries, the association condition needs to be verified first. After the association condition is verified successfully, it needs to be saved. Range common: simple condition-based filtering config: association table filtering Default Value common

**Table 4** GeneralTransformationReq
Parameter	Mandatory	Type	Description
filter_object_list	No	Array of objects	Definition List of data filtering objects, which includes information about the database objects (databases/schemas/tables) to be verified. For details, see Table 5. Constraints This parameter is mandatory in simple condition-based filtering scenarios. Each element in the list represents a database object to be filtered. Range N/A Default Value N/A
source_filter_condition	No	String	Definition SQL statement for filtering source database objects. This parameter defines the rules for filtering data in the source database. Advanced filtering expressions, such as SQL subqueries, are supported. When data filtering involves subqueries, you need to use this field to configure the query conditions. Constraints N/A Range N/A Default Value N/A

**Table 5** DataFilterObjectInfo
Parameter	Mandatory	Type	Description
id	Yes	String	Definition Unique ID of a data filtering object, which identifies the database object to be filtered. The value is in the format of a hierarchical path. Constraints The value must be in one of the following formats: database-name---table-name, schema-name---table-name, and database-name---schema-name---table-name. Range N/A Default Value N/A
parent_id	Yes	String	Definition Parent object ID of a data filtering object, which identifies the upper-level database object (database or schema) to which the current filtering object belongs. Constraints The value must be in one of the following formats: database-name, schema-name, and database-name---schema-name. Range N/A Default Value N/A
object_name	Yes	String	Definition Name of a data filtering object, that is, the name of the database table to be filtered. Constraints N/A Range N/A Default Value N/A
object_type	No	String	Definition Type of a data filtering object, which identifies the database object type of the current filtering object, such as a table, view, or stored procedure. Constraints N/A Range N/A Default Value N/A

**Table 6** DataFilteringAdvancedSetting
Parameter	Mandatory	Type	Description
db_name	Yes	String	Definition Database name. Constraints N/A Range N/A Default Value N/A
table_name	Yes	String	Definition Table name. Constraints N/A Range N/A Default Value N/A
col_names	Yes	String	Definition Column name. Constraints N/A Range N/A Default Value N/A
prim_key_or_indexes	Yes	String	Definition Primary key or unique index. Constraints N/A Range N/A Default Value N/A
indexes	Yes	String	Definition Index required for optimizing the query. Constraints N/A Range N/A Default Value N/A
values	Yes	String	Definition Filtering criteria. Constraints N/A Range N/A Default Value N/A

Response Parameters

Status code: 200

Status code: 400

**Table 7** Response body parameters
Parameter	Type	Description
error_code	String	Definition Error code returned when an error occurs during task execution. Constraints Minimum length: 12 characters Maximum length: 12 characters Range The format is DRS.XXXXXX.
error_msg	String	Definition Detailed error description returned when a task fails to be executed. Constraints Minimum length: 1 character Maximum length: 512 characters Range N/A

Example Request

Request body for batch data filtering rules when the source database object is in the database-table or schema-table structure (two-layer object structure)

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_drs-*-*-mysql1", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql1", 
      "object_alias_name" : "test-*-*-test1", 
      "object_type" : "table" 
    }, { 
      "id" : "test_drs-*-*-mysql2", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql1", 
      "object_alias_name" : "test-*-*-test2", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}

Request body for batch data filtering rules when the source database object is in the database-schema-table structure (three-layer object structure)

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_db-*-*-testschema-*-*-test_table01", 
      "parent_id" : "test_db-*-*-testschema", 
      "object_name" : "test_table", 
      "object_alias_name" : "test_db-*-*-testschema-*-*-test01", 
      "object_type" : "table" 
    }, { 
      "id" : "test_db-*-*-testschema-*-*-test_table02", 
      "parent_id" : "test_db-*-*-testschema", 
      "object_name" : "test_table", 
      "object_alias_name" : "test_db-*-*-testschema-*-*-test02", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}

Advanced filtering criteria configuration when the common filtering criteria involve subqueries

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "advanced_setting_list" : [ { 
    "db_name" : "test_drs", 
    "table_name" : "mysql5", 
    "col_names" : "id", 
    "prim_key_or_indexes" : "id", 
    "indexes" : "id", 
    "values" : "id > 1" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "config" 
}

Common filtering criteria involving subqueries

https://{endpoint}/v5/054ba152d480d55b2f5dc0069e7ddef0/jobs/c7debc9c-8e09-4a5d-8dd6-cc44f78jb20r/filter-rules 
 
{ 
  "general_filtering_list" : [ { 
    "filter_object_list" : [ { 
      "id" : "test_drs-*-*-mysql3", 
      "parent_id" : "test_drs", 
      "object_name" : "mysql3", 
      "object_alias_name" : "test-*-*-mysql3", 
      "object_type" : "table" 
    } ], 
    "source_filter_condition" : "id in (select id from test_drs.mysql5 where id > 1)" 
  } ], 
  "source" : "job", 
  "data_filter_type" : "common" 
}

Example Response

Status code: 200

""

Status code: 400

Bad Request

{ 
  "error_code" : "DRS.10020001", 
  "error_msg" : "The parameter general_filtering_list is empty" 
}

Status Code

Status Code	Description
200	OK
400	Bad Request

For other statuses, see Status Code.

Error Code

For details, see Error Code.

Parent topic: Data Processing

Previous topic: Querying Additional Column Information About Data Processing Objects

Next topic: Collecting Information About Data Filtering Rules