Data Transfer API, REST: Transfer.Update

Written by

Updated at December 17, 2024

HTTP request
Path parameters
Body parameters
Runtime
YcRuntime
ShardingUploadParams
Transformation
Transformer
MaskFieldTransformer
TablesFilter
MaskFunction
MaskFunctionHash
FilterColumnsTransformer
ColumnsFilter
RenameTablesTransformer
RenameTable
Table
ReplacePrimaryKeyTransformer
ToStringTransformer
SharderTransformer
TableSplitterTransformer
FilterRowsTransformer
Response
Status

HTTP request

PATCH https://datatransfer.api.cloud.yandex.net/v1/transfer/{transferId}

Path parameters

Field

Description

transferId

string

Required field. Identifier of the transfer to be updated.

Body parameters

{
  "description": "string",
  "runtime": {
    // Includes only one of the fields `ycRuntime`
    "ycRuntime": {
      "jobCount": "string",
      "uploadShardParams": {
        "jobCount": "string",
        "processCount": "string"
      }
    }
    // end of the list of possible fields
  },
  "name": "string",
  "updateMask": "object",
  "labels": "object",
  "transformation": {
    "transformers": [
      {
        // Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`
        "maskField": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "columns": [
            "string"
          ],
          "function": {
            // Includes only one of the fields `maskFunctionHash`
            "maskFunctionHash": {
              "userDefinedSalt": "string"
            }
            // end of the list of possible fields
          }
        },
        "filterColumns": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "columns": {
            "includeColumns": [
              "string"
            ],
            "excludeColumns": [
              "string"
            ]
          }
        },
        "renameTables": {
          "renameTables": [
            {
              "originalName": {
                "nameSpace": "string",
                "name": "string"
              },
              "newName": {
                "nameSpace": "string",
                "name": "string"
              }
            }
          ]
        },
        "replacePrimaryKey": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "keys": [
            "string"
          ]
        },
        "convertToString": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "columns": {
            "includeColumns": [
              "string"
            ],
            "excludeColumns": [
              "string"
            ]
          }
        },
        "sharderTransformer": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "columns": {
            "includeColumns": [
              "string"
            ],
            "excludeColumns": [
              "string"
            ]
          },
          "shardsCount": "string"
        },
        "tableSplitterTransformer": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "columns": [
            "string"
          ],
          "splitter": "string"
        },
        "filterRows": {
          "tables": {
            "includeTables": [
              "string"
            ],
            "excludeTables": [
              "string"
            ]
          },
          "filter": "string",
          "filters": [
            "string"
          ]
        }
        // end of the list of possible fields
      }
    ]
  }
}

Field	Description
description	string The new description for the transfer.
runtime	Runtime
name	string The new transfer name. Must be unique within the folder.
updateMask	object (field-mask) A comma-separated names off ALL fields to be updated. Only the specified fields will be changed. The others will be left untouched. If the field is specified in `updateMask` and no value for that field was sent in the request, the field's value will be reset to the default. The default value for most fields is null or 0. If `updateMask` is not sent in the request, all fields' values will be updated. Fields specified in the request will be updated to provided values. The rest of the fields will be reset to the default.
labels	object (map<string, string>)
transformation	Transformation

Runtime

Field

Description

ycRuntime

YcRuntime

Includes only one of the fields ycRuntime.

YcRuntime

Field	Description
jobCount	string (int64)
uploadShardParams	ShardingUploadParams

ShardingUploadParams

Field	Description
jobCount	string (int64)
processCount	string (int64)

Transformation is converting data using special transformer functions.
These functions are executed on a data stream, applied to each data change item,
and transform them.
A transformer can be run at both the metadata and data levels.
Data can only be transformed if the source and target are of different types.

Field

Description

transformers[]

Transformer

Transformers are set as a list.
When activating a transfer, a transformation plan is made for the tables that
match the specified criteria.
Transformers are applied to the tables in the sequence specified in the list.

Transformer

Some transformers may have limitations and only apply to some source-target
pairs.

Field	Description
maskField	MaskFieldTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
filterColumns	FilterColumnsTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
renameTables	RenameTablesTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
replacePrimaryKey	ReplacePrimaryKeyTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
convertToString	ToStringTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
sharderTransformer	SharderTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
tableSplitterTransformer	TableSplitterTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.
filterRows	FilterRowsTransformer Includes only one of the fields `maskField`, `filterColumns`, `renameTables`, `replacePrimaryKey`, `convertToString`, `sharderTransformer`, `tableSplitterTransformer`, `filterRows`.

MaskFieldTransformer

Mask field transformer allows you to hash data

Field	Description
tables	TablesFilter List of included and excluded tables
columns[]	string Specify the name of the column for data masking (a regular expression).
function	MaskFunction Mask function

TablesFilter

Filter tables using lists of included and excluded tables.

Field

Description

includeTables[]

string

List of tables that will be included to transfer

excludeTables[]

string

List of tables that will be excluded to transfer

MaskFunction

Mask function

Field

Description

maskFunctionHash

MaskFunctionHash

Hash mask function

Includes only one of the fields maskFunctionHash.

MaskFunctionHash

Hash data using HMAC

Field

Description

userDefinedSalt

string

This string will be used in the HMAC(sha256, salt) function applied to the
column data.

FilterColumnsTransformer

Set up a list of table columns to transfer

Field

Description

tables

TablesFilter

List of the tables to filter using lists of included and excluded tables.

columns

ColumnsFilter

List of the columns to transfer to the target tables using lists of included and
excluded columns.

ColumnsFilter

Filter columns using lists of included and excluded columns.

Field

Description

includeColumns[]

string

List of columns that will be included to transfer

excludeColumns[]

string

List of columns that will be excluded to transfer

RenameTablesTransformer

Set rules for renaming tables by specifying the current names of the tables in
the source and new names for these tables in the target.

Field

Description

renameTables[]

RenameTable

List of renaming rules

RenameTable

Specify rule for renaming table

Field

Description

originalName

Table

Specify the current names of the table in the source

newName

Table

Specify the new names for this table in the target

Table

Field	Description
nameSpace	string
name	string

ReplacePrimaryKeyTransformer

Override primary keys

Field

Description

tables

TablesFilter

List of included and excluded tables

keys[]

string

List of columns to be used as primary keys

ToStringTransformer

Convert column values to strings
The values will be converted depending on the source type
Conversion rules are described here:
https://cloud.yandex.com/en/docs/data-transfer/concepts/data-transformation#convert-to-string

Field

Description

tables

TablesFilter

List of included and excluded tables

columns

ColumnsFilter

List of included and excluded columns

SharderTransformer

Set the number of shards for particular tables and a list of columns whose
values will be used for calculating a hash to determine a shard.

Field	Description
tables	TablesFilter List of included and excluded tables
columns	ColumnsFilter List of included and excluded columns
shardsCount	string (int64) Number of shards

TableSplitterTransformer

A transfer splits the X table into multiple tables (X_1, X_2, ..., X_n) based on
data.
If a row was located in the X table before it was split, it is now in the X_i
table,
where i is determined by the column list and split string parameters.
Example:
If the column list has two columns, month of birth and gender, specified and the
split string states @,
information about an employee whose name is John and who was born on February
11, 1984,
from the Employees table will get to a new table named Employees@February@male.

Field	Description
tables	TablesFilter List of included and excluded tables
columns[]	string Specify the columns in the tables to be partitioned.
splitter	string Specify the split string to be used for merging components in a new table name.

FilterRowsTransformer

This filter only applies to transfers with queues (Logbroker or Apache Kafka®)
as a data source.
When running a transfer, only the strings meeting the specified criteria remain
in a changefeed.

Field	Description
tables	TablesFilter List of included and excluded tables.
filter	string Filtering criterion. This can be comparison operators for numeric, string, and Boolean values, comparison to NULL, and checking whether a substring is part of a string. Details here: https://yandex.cloud/en-ru/docs/data-transfer/concepts/data-transformation#append-only-sources. Deprecated: Use filters instead.
filters[]	string Data is transported if it satisfies at least one of filters. Consider that there is OR statement between filters. Each filter can be comparison operators for numeric, string, and Boolean values, comparison to NULL, and checking whether a substring is part of a string. Details in docs: https://yandex.cloud/en-ru/docs/data-transfer/concepts/data-transformation#append-only-sources.

Response

HTTP Code: 200 - OK

{
  "id": "string",
  "description": "string",
  "createdAt": "string",
  "createdBy": "string",
  "modifiedAt": "string",
  "done": "boolean",
  "metadata": "object",
  // Includes only one of the fields `error`, `response`
  "error": {
    "code": "integer",
    "message": "string",
    "details": [
      "object"
    ]
  },
  "response": "object"
  // end of the list of possible fields
}

An Operation resource. For more information, see Operation.

Field	Description
id	string ID of the operation.
description	string Description of the operation. 0-256 characters long.
createdAt	string (date-time) Creation timestamp. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
createdBy	string ID of the user or service account who initiated the operation.
modifiedAt	string (date-time) The time when the Operation resource was last modified. String in RFC3339 text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the Protocol Buffers reference. In some languages, built-in datetime utilities do not support nanosecond precision (9 digits).
done	boolean If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available.
metadata	object Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any.
error	Status The error result of the operation in case of failure or cancellation. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.
response	object The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is google.protobuf.Empty. If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set.

Status

The error result of the operation in case of failure or cancellation.

Field	Description
code	integer (int32) Error code. An enum value of google.rpc.Code.
message	string An error message.
details[]	object A list of messages that carry the error details.

Data Transfer API, REST: Transfer.Update

HTTP requestHTTP request

Path parametersPath parameters

Body parametersBody parameters

RuntimeRuntime

YcRuntimeYcRuntime

ShardingUploadParamsShardingUploadParams

TransformationTransformation

TransformerTransformer

MaskFieldTransformerMaskFieldTransformer

TablesFilterTablesFilter

MaskFunctionMaskFunction

MaskFunctionHashMaskFunctionHash

FilterColumnsTransformerFilterColumnsTransformer

ColumnsFilterColumnsFilter

RenameTablesTransformerRenameTablesTransformer

RenameTableRenameTable

TableTable

ReplacePrimaryKeyTransformerReplacePrimaryKeyTransformer

ToStringTransformerToStringTransformer

SharderTransformerSharderTransformer

TableSplitterTransformerTableSplitterTransformer

FilterRowsTransformerFilterRowsTransformer

ResponseResponse

StatusStatus

Was the article helpful?

HTTP request

Path parameters

Body parameters

Runtime

YcRuntime

ShardingUploadParams

Transformation

Transformer

MaskFieldTransformer

TablesFilter

MaskFunction

MaskFunctionHash

FilterColumnsTransformer

ColumnsFilter

RenameTablesTransformer

RenameTable

Table

ReplacePrimaryKeyTransformer

ToStringTransformer

SharderTransformer

TableSplitterTransformer

FilterRowsTransformer

Response

Status