Using row metadata in Write Operations

You can supply your own metadata when you perform write operations on the rows in your tables with the help of the APIs below. For more information, see Using user-defined row metadata

This row metadata will be included in the change stream for understanding the context of operation. For more information, see Row metadata Streaming.

Note:

This feature has been made available to you on a "preview" basis so that you can get early access and provide feedback. It is intended for demonstration and preliminary use only. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this feature and will not be responsible for any loss, costs, or damages incurred due to the use of this feature.

Using PutRequest API: You can use the PutRequest to add additional information, known as row metadata, alongside the main row data in your table. This row metadata is useful for storing extra information, that can describe or provide context about the actual row contents, such as the user who made the change or the source of the update. You must pass the row metadata as a JSON string using the setRowMetadata() method in the PutRequest class.
This metadata will be included in the change stream event, allowing the change stream subscriber to see it.

To understand this with an example, refer to writeRowWithMetadata() in ManageMetadata.java for more details, avaialable in the examples here.
```
/* Row Metadata inputs */
final static String rm1="{\"modified_by\" : \"John Doe\",\"reviewed_in\" : \"Q1\",\"update_reason\" : \"Account details updated\"}";
 
/*Calling the method from the main function*/
writeRowWithMetadata(handle, (MapValue)newvalue, rm1);
 
/* Method to add row with associated row metadata*/
private static void writeRowWithMetadata(NoSQLHandle handle, MapValue value, String rowMetadata) throws Exception {
   PutRequest putRequest = new PutRequest()
       .setValue(value)
       .setTableName(tableName)
       .setRowMetadata(rowMetadata);
 
   PutResult putResult = handle.put(putRequest);
   if (putResult.getVersion() != null) {
       System.out.println("Wrote: " + value);
   } else {
       System.out.println("Put failed");
      }
   }
```
QueryRequest API: When executing SQL DML statements using the QueryRequest API, you can apply setRowMetadata() to attach user-defined metadata to the affected rows. See the updateRowViaQuery() in ManageMetadata.java for more details, available in the examples here.
DeleteRequest API: When deleting a single row using its primary key, you can attach metadata using setRowMetadata() to help describe the reason for deletion. See the deleteRowWithMetadata() in ManageMetadata.java for more details, available in the examples here.
MultiWrite API: When performing atomic writes of multiple rows that share the same shard key, you can attach setRowMetadata() individually to each PutRequest in the batch. This is ideal for batch inserts or updates where each row may originate from a different user, source system, or import operation. See the writeMultipleRows() in MutiMetadataOps.java for more details, available in the examples here.
MultiDelete API: When using a single atomic operation to delete multiple rows, that share the same shard key, you can attach the metadata using the setRowMetadata() in MultiDeleteRequest class. For example, you can use the metadata to document the reason for deleting those rows. See the delMulRows() in MutiMetadataOps.java for more details, available in the examples here.