Package org.labkey.remoteapi.query

Class SaveRowsCommand

java.lang.Object
org.labkey.remoteapi.Command<ResponseType,org.apache.hc.client5.http.classic.methods.HttpPost>
org.labkey.remoteapi.PostCommand<SaveRowsResponse>
org.labkey.remoteapi.query.SaveRowsCommand
All Implemented Interfaces:
HasRequiredVersion
public class SaveRowsCommand extends PostCommand<SaveRowsResponse>
Command for executing multiple data modification operations (insert, update, delete) in a single request to a LabKey Server. This command allows batching multiple operations together, optionally in a transaction.

All data exposed from a LabKey Server is organized into schemas containing queries. Each command in a batch specifies the schema name (e.g., 'lists' or 'study') and query name (e.g., 'People' or 'Samples') to operate on.

The command supports several features:

  • Multiple operations (insert, update, delete) in a single request
  • Optional transaction support to ensure all-or-nothing execution
  • Validation-only mode to check operations without making changes
  • Audit trail support with configurable detail levels
  • Custom audit comments for tracking changes

Example usage: 


  ApiKeyCredentialsProvider credentials = new ApiKeyCredentialsProvider("xxx");
  Connection conn = new Connection("http://localhost:8080", credentials);
  SaveRowsApiCommand saveCmd = new SaveRowsApiCommand();

  // Add new gene annotations
  saveCmd.addCommand(new Command(CommandType.Insert, "genome", "GeneAnnotations",
      List.of(
          Map.of("name", "p53 binding site", "geneName", "TP53", "start", 1000, "end", 1020),
          Map.of("name", "TATA box", "geneName", "BRCA1", "start", 2500, "end", 2506)
      )));

  // Update annotation positions
  Command updateCmd = new Command(CommandType.Update, "genome", "GeneAnnotations",
      List.of(Map.of(
          "name", "Promoter region",
          "geneName", "EGFR",
          "start", 5000,
          "end", 5500
      )));
  updateCmd.setAuditBehavior(BaseRowsCommand.AuditBehavior.DETAILED);
  updateCmd.setAuditUserComment("Updated promoter region coordinates based on new assembly");
  saveCmd.addCommands(updateCmd);

  // Delete obsolete annotation
  saveCmd.addCommand(new Command(CommandType.Delete, "genome", "GeneAnnotations",
      List.of(Map.of("name", "Putative enhancer", "geneName", "MYC"))));

  // Execute all commands in a transaction
  SaveRowsApiResponse response = saveCmd.execute(conn, "GenomeProject");

  • Constructor Details

  • Method Details

    • getExtraContext

      public Map<String,Object> getExtraContext()
      Returns the extra context map containing additional parameters for the save operation. This context can be used to pass additional information to the server during the save process.
      Returns:
      Map containing extra context parameters, or null if no extra context is set

    • setExtraContext

      public SaveRowsCommand setExtraContext(Map<String,Object> extraContext)
      Sets additional context parameters for the save operation.
      Parameters:
      extraContext - Map containing extra parameters to be passed to the server
      Returns:
      This SaveRowsCommand instance for method chaining

    • addCommands

      public SaveRowsCommand addCommands(SaveRowsCommand.Command... commands)
      Adds one or more Command objects to the set of commands to be executed by this SaveRowsCommand.
      Parameters:
      commands - The commands to add to this SaveRowsCommand.
      Returns:
      This SaveRowsCommand instance for method chaining

    • getCommands

      public List<SaveRowsCommand.Command> getCommands()
      Returns the list of Command objects representing the batch operations to be executed. Each Command in the list represents a single insert, update, or delete operation.
      Returns:
      List of Command objects to be executed

    • isTransacted

      public Boolean isTransacted()
      Checks if the operations should be executed in a transaction. When true, all operations will be executed atomically - either all succeed or all fail.
      Returns:
      Boolean indicating if operations should be transacted, or null for default behavior

    • setTransacted

      public SaveRowsCommand setTransacted(Boolean transacted)
      Sets whether the operations should be executed in a transaction.
      Parameters:
      transacted - When true, all operations will be executed atomically. When false, operations may partially succeed. When null, uses server default behavior.
      Returns:
      This SaveRowsCommand instance for method chaining

    • isValidateOnly

      public Boolean isValidateOnly()
      Checks if this is a validation-only operation. When true, the server will validate the operations without making any actual changes.
      Returns:
      Boolean When true, validates operations without making changes. When false, executes operations normally. When null, uses server default behavior.

    • setValidateOnly

      public SaveRowsCommand setValidateOnly(Boolean validateOnly)
      Sets whether this should be a validation-only operation.
      Parameters:
      validateOnly - When true, validates operations without making changes. When false, executes operations normally. When null, uses server default behavior.
      Returns:
      This SaveRowsCommand instance for method chaining

    • getJsonObject

      public org.json.JSONObject getJsonObject()
      Description copied from class: PostCommand
      Returns the JSON object to post or null for no JSON. Override this method to provide parameters as JSON.
      Overrides:
      getJsonObject in class PostCommand<SaveRowsResponse>
      Returns:
      The JSON object to post.

    • createResponse

      protected SaveRowsResponse createResponse(String text, int status, String contentType, org.json.JSONObject json)
      Description copied from class: Command
      Creates an instance of the response class, initialized with the response text, the HTTP status code, and parsed JSONObject.

      Override this method to create an instance of a different class that extends CommandResponse

      Overrides:
      createResponse in class Command<SaveRowsResponse,org.apache.hc.client5.http.classic.methods.HttpPost>
      Parameters:
      text - The response text from the server.
      status - The HTTP status code.
      contentType - The Content-Type header value.
      json - The parsed JSONObject (or null if no JSON was returned).
      Returns:
      An instance of the response object.