Data export service

Accessing the feature

Main chain feature entry point

1. Log on to the Alibaba Cloud BaaS console. In the navigation pane on the left, click Ant Blockchain > Contract Chain to go to the My Consortiums page.

2. In the consortium list, find the target consortium and click Manage in the Actions column.

3. In the Chains in Consortium list, find the target primary chain and click Primary Chain Management in the Actions column.

4. In the navigation pane on the left, click Data Export Service to open the data export service console.

Sub-chain feature entry point

1. Log on to the Alibaba Cloud BaaS console. In the navigation pane on the left, click Ant Blockchain > Contract Chain to go to the My Consortiums page.

2. In the consortium list, find the target consortium and click Manage in the Actions column.

3. In the Chains in Consortium list, find the target primary chain and click Subchain Management in the Actions column.

4. In the Subchain Management list, find the target subchain and click Manage in the Actions column.

5. In the navigation pane on the left, click Data Export Service to open the data export service console.

Create an export task

On the data export service console, click New Export in the upper-left corner to create an export task.

Wizard 1: Configure data export settings

Parameter	Description
Task Name	Enter a custom name for the export task. The name can be up to 32 characters long and can contain uppercase letters, lowercase letters, digits, and underscores.
Task Description	Optional. Enter a brief description for the export task. The description can be up to 128 characters long.
Alerting Address	Optional. After you configure this parameter, DingTalk alert notifications are sent when the export task encounters data that it cannot process or when the task is complete. For information about how to configure this, see DingTalk Custom Robot Access. If you leave this empty, the default DingTalk custom robot webhook address is used, such as https://oapi.dingtalk.com/robot/send?access_token=XXX. Note: When you configure a DingTalk custom robot, add the parameter Data to Custom Keywords.
Export Type	Select the type of data to export. The following data types are available: Contract Event: An event that consists of all logs in a transaction receipt. Transaction Event: An event that consists of an on-chain transaction and its receipt. Raw Evidence Event: An event that consists of an on-chain raw evidence transaction. Custom Transaction Event: An event that consists of an on-chain transaction and its receipt. Custom Block Event: An event that consists of an on-chain block. Custom Contract Event: An event that consists of all logs in a transaction receipt. Note Custom events can use Jq syntax to filter data. Events that are not custom only support matching based on specific rules. For more information, see the export rules in the next row.
Export Rules	Configure filtering rules for the exported data. The meaning of the rule varies based on the selected data type: Contract Event: Exports contract logs where the topic name in the log matches the rule. Transaction Event: Exports transactions where the transaction type name matches the rule. For example, `CALL_CONTRACT` exports contract call transactions. Raw Evidence Event: Exports raw evidence transactions where the transaction initiator's address matches the rule. Custom Transaction Event: Filters the event. For the syntax, see Jq Filter Expression. Custom Block Event: Filters the event. For the syntax, see Jq Filter Expression. Custom Contract Event: Filters the event. For the syntax, see Jq Filter Expression.
Start Block Height	The starting block height for data export (inclusive).
End Block Height	The ending block height for data export (exclusive). `Continuous Run` means data is written to the database in near real-time.
Export Preview	Click Generate Preview to get events from the chain that match the Export Type and Export Rules. If no data exists, sample data is displayed.

Wizard 2: Configure export destination settings

Currently, data can only be exported to MySQL.

Parameter	Description
Export Destination	Select MySQL. Use MySQL 5.6 or later.
Database Address	The connection address of the database.
Port Number	The connection port of the database.
Database Name	The name of the database.
Database Username	The username to access the database. This user must have at least INSERT and UPDATE permissions.
Database Password	The password for the database user.
Table Name	The name of the destination table for the exported data. If you leave this empty, a table name is randomly generated.

Wizard 3: Configure table mapping

If you generated preview data in Wizard 1, a default mapping is created in this step. You can modify this mapping.

Parameter	Description
Export Data Field	A Jq filter expression that selects the data for the database column from the exported data.
Field Name	The name of the database column.
Field Type	Select the data type for the database column.
Field Size	The data size of the database column.
Field Description	Optional. The description of the database column.

Wizard 4: Complete creation

Click Next to create the export task.

Manage export tasks

View tasks

On the data export service console, the task list displays all export tasks for the current blockchain instance. The platform categorizes tasks as one-time or continuous based on the End Block Height setting in the data export settings.

• If a custom End Block Height is set, the task is displayed on the One-time Tasks tab after it is created.

• Tasks that write data to a database in near real-time appear on the Continuous Tasks tab after they are created.

An export task can have one of the following statuses:

• Running: Data is being exported.

• Stopped: The task was manually stopped.

• Completed: The export task has finished.

• Failed: The export task failed to run. You can click Start to restart the failed task.

  Note

  If the number of events that fail to be exported to the database reaches a certain limit, the task status changes to Failed. To confirm the specific limit, contact the Ant Blockchain technical team.

View or modify task details

• View task details

  On the Data Export Service page, find the target task and click Details in the Actions column to view its details.

• Modify task details

  On the Task Details page, click Edit in the upper-right corner. In the side panel that appears, you can modify the Task Name, Task Description, and Alerting Address. Then, click Confirm to save the changes.

Pause or resume an export task

If an export task has a Status of Running, you can click Pause in the Actions column to interrupt it. After a task is paused, you can resume it to continue exporting data to the external database.

Delete a task

If an export task is complete or no longer needed, you can remove it from the task list by clicking Delete in the Actions column.

Query and retry failed records

For an export task that has errors, you can click Error Log in the Actions column to view all of its error logs.

For each failed record, you can choose to Ignore the event or Retry writing the event to the destination database. If the retry attempt fails, the log status remains `Pending`. You can identify the problem based on the error cause, make the necessary adjustments, and then click Retry again.

Jq filter expressions

You can use Jq expressions to filter and reorganize the fields of exported data. The following are some examples. For more syntax information, see the official Jq documentation.

Get a specific field

You can use `.<Object Key>` to read the value of a specific field in a JSON object (the input event). `.foo` returns the value of the "foo" key, or null if the key does not exist. If the key contains special characters, enclose it in double quotation marks, for example, `".foo$"`.

Original event:
{
  "name": "demo-event",
  "content": {
    "block_num": 78,
    "input": "invoke"
  }
}
Filter expression:
.content.input
Filter result:
"invoke"

Filter fields

You can use the `select(<boolean_expression>)` method to filter a JSON object (the input event). You can retrieve a specific field and use logical expressions such as `==`, `<`, `>`, `<=`, `>=`, and `!=` to evaluate the result. If there are multiple conditional expressions, connect them with `and` or `or`.

Original event:
{
  "name": "demo-event",
  "content": {
    "block_num": 78,
    "input": "invoke"
  }
}
Filter expression 1:
select( .content.input == "invoke" and .content.block_num > 50 )
Filter result 1:
{"name": "demo-event", "content": { "block_num": 78, "input": "invoke"}}
Filter expression 2:
select( .content.input == "invoke" and .content.block_num < 50 )
Filter result 2:
null

Convert field types

You can use ` | tostring` to convert the content of a retrieved specific field to a string.

Original event:
{
  "name": "demo-event",
  "content": {
    "block_num": 78,
    "input": "invoke"
  }
}
Filter expression:
(.content | tostring )
Filter result:
"{\"block_num\": 78, \"input\": \"invoke\"}}"