Transaction Web Service operation description

This topic describes the logic of the Web service's operations, as well as its request and response structure.

Operation description

Here is the logic of the Web service's operations:
  • Before an outer transaction starts, the pre-transaction version of the index is available; it is known as the last published version of the index.
  • When a startOuterTransaction operation is issued, it starts an outer transaction. This transaction, because it encapsulates inner transactions within it, is referred to as an outer transaction. Only one outer transaction can be running at a time.

    You can supply the ID for the transaction in the startOuterTransaction operation. If you do not specify it, the Dgraph process issues a unique outer transaction ID in the response.

    While the outer transaction is in progress, update requests to the index that reference the outer transaction ID are processed within the outer transaction. These updates can be made through any of the available interfaces that can issue requests to the server, including the Data Ingest Web Service, the Configuration Web Service, and the Bulk Load Interface. Updating requests from all interfaces except the Bulk Load that don't reference the ID wait until the outer transaction is committed (or rolled back), and are computed based on the published version of the index. (Requests from the Bulk Load interface that don't specify the ID are rejected while the outer transaction is in progress).

  • Once an outer transaction starts, the index files are internally updated. Internal versions of the index might become available to qualifying requests (those that reference the ID) within an outer transaction. These versions are known as transaction versions.
  • For the duration of the outer transaction, the Dgraph answers updating queries only if they specify the transaction ID. These updating queries are answered against a transaction version of the index that is not published until the transaction is committed. (This transaction version reflects the most recent "writes" to the index that occurred within the outer transaction until this point.) All non-updating queries are answered either against the last published version of the index (if they don't specify the ID), or against the transaction version (if they specify the ID).
  • The outer transaction is committed with the Transaction Web Service commitOuterTransaction operation.
  • Once the transaction commits, its version of the index is published. Updating requests that were waiting in the queue (and that didn't specify the ID) are now processed against this version.

  • If an outer transaction fails to commit, it remains open. You cannot start another outer transaction until you commit or back the outer transaction that failed to commit. You can manually issue a commit or rollback operation to recover from a failed transaction without restarting the Dgraph process for the data domain. (This statement has one exception — if an outer transaction fails to commit because the Dgraph fails, the transaction is not applied and does not require to be committed or rolled back).

    To manually end a transaction that failed to commit and roll back the changes, you can issue the rollBackOuterTransaction operation, specifying the ID of this outer transaction. If you roll back an outer transaction, then updating requests that didn't specify the ID and that were waiting in the queue are processed once the transaction is successfully rolled back.

    For information on connectors that support transactions, see the Oracle Endeca Information Discovery Integrator ETL User's Guide.

Request

The input to the Web service depends on the operation used and can include any of its operations for starting, committing, or rolling back a transaction, or for listing the outer transaction ID.

In the startOuterTransaction operation, you can provide a transaction ID. If it is not provided, the Dgraph process issues an ID automatically and returns it in the response. In addition, you can use the listOuterTransaction operation to obtain the ID from the Dgraph running in your data domain.

Response

The response to the Transaction Web Service indicates whether each of the operations succeeded or failed.

If any operation does not succeed, the whole Web service transaction returns a SOAP fault and none of the operations are applied.