com.aliyun.odps.storage.write

Class TableWriteSession

java.lang.Object

com.aliyun.odps.storage.write.TableWriteSession

All Implemented Interfaces:

AutoCloseable

public class TableWriteSession
extends Object
implements AutoCloseable

This class represents a write session for a MaxCompute table, allowing clients to write data in a distributed manner using Arrow format. Each session is associated with a specific table and provides methods to create writers, commit or abort the write operation.

Example usage (Batch mode):

 TableIdentifier tableId = TableIdentifier.of("my_project", "my_table");
 try (TableWriteSession session = client.createWriteSessionBuilder(tableId).build()) {
     TableArrowWriter writer = session.createWriterBuilder("stream1", 1).build();
     // Write data using writer
     writer.close();
     session.commit();
 }
 

Example usage (Streaming mode):

 TableIdentifier tableId = TableIdentifier.of("my_project", "my_table");
 try (TableWriteSession session = client.createWriteSessionBuilder(tableId)
         .withWriteMode(WriteMode.STREAMING).build()) {
     TableArrowWriter writer = session.createWriterBuilder("stream1", 1).build();
     // Write data using writer
     writer.writeBatch(root);
     writer.flush(); // Data becomes visible immediately
     writer.close();
     // No commit needed for streaming mode
 }
 

The session must be either committed or aborted to properly clean up resources in BATCH mode. In STREAMING mode, data is visible after flush and no commit is needed.

Method Summary

Modifier and Type	Method and Description
void	abort() Aborts the write session, discarding all written data.
void	close() Closes the write session, automatically aborting if not already committed.
void	commit() Commits the write session, making all written data available in the table.
TableWriterBuilder	createWriterBuilder(String streamId, long streamVersion) Creates a new builder for a writer for this write session.
String	getId() Gets the unique identifier of this write session.
WriteMode	getWriteMode() Gets the write mode of this session.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getId

public String getId()

Gets the unique identifier of this write session.

Returns:

The session ID

getWriteMode

public WriteMode getWriteMode()

Gets the write mode of this session.

Returns:

The write mode

createWriterBuilder

public TableWriterBuilder createWriterBuilder(String streamId,
                                              long streamVersion)

Creates a new builder for a writer for this write session.

This method initializes a writer builder that can be configured with various options before creating the actual writer. The writer allows writing data to the table in Arrow format.

Parameters:

streamId - The unique identifier for the write stream

streamVersion - The version of the write stream (must be >= 1)

Returns:

A new TableWriterBuilder instance to configure the writer

Throws:

IllegalArgumentException - if streamVersion is less than 1

commit

public void commit()

Commits the write session, making all written data available in the table.

This method makes an API call to the MaxCompute service to commit the write session. After this call, all data written through the writers associated with this session will be visible in the table. The session is automatically closed after committing.

Note: In STREAMING mode, this method is a no-op since data is already visible after flush.

Throws:

IllegalStateException - if the session is already closed

abort

public void abort()

Aborts the write session, discarding all written data.

This method makes an API call to the MaxCompute service to abort the write session. After this call, all data written through the writers associated with this session will be discarded. The session is automatically closed after aborting.

Note: In STREAMING mode, this method is a no-op since data is already visible after flush and cannot be aborted.

close

public void close()

Closes the write session, automatically aborting if not already committed.

This method ensures proper cleanup of resources. If the session has not been explicitly committed, it will be automatically aborted to discard any written data. This behavior is intentional to prevent data inconsistency when a session is closed without explicit commitment.

In STREAMING mode, this method simply marks the session as closed without additional cleanup since data is already visible after flush.

If you want to explicitly close the session without aborting, call commit() before calling this method.

This method is safe to call multiple times.

Specified by:

close in interface AutoCloseable