Using User-Supplied 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-Supplied Metadata.

This user-supplied metadata will be included in the change stream for understanding the context of operation. For more information, see User-Supplied Metadata Streaming.

• Using PutRequest API: You can use the PutRequest to add additional information, known as user-supplied metadata, alongside the main row data in your table. This 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 user-supplied metadata as a JSON string using the setLastWriteMetadata() 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 ManageUserSuppliedMetadata.java for more details, avaialable in the examples here.

  /* user-supplied 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 user-supplied metadata*/
  private static void writeRowWithMetadata(NoSQLHandle handle, MapValue value, String metadata) throws Exception {
     PutRequest putRequest = new PutRequest()
         .setValue(value)
         .setTableName(tableName)
         .setLastWriteMetadata(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 setLastWriteMetadata() to attach user-supplied metadata to the affected rows. See the updateRowViaQuery() in ManageUserSuppliedMetadata.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 setLastWriteMetadata() to help describe the reason for deletion. See the deleteRowWithMetadata() in ManageUserSuppliedMetadata.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 setLastWriteMetadata() 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 MultiUserSuppliedMetadataOps.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 setLastWriteMetadata() in MultiDeleteRequest class. For example, you can use the metadata to document the reason for deleting those rows. See the delMulRows() in MultiUserSuppliedMetadataOps.java for more details, available in the examples here.