com.aliyun.odps.storage.read

Class TableReadSessionBuilder

java.lang.Object

com.aliyun.odps.storage.read.TableReadSessionBuilder

public class TableReadSessionBuilder
extends Object

Implementation of TableReadSessionBuilder for the MaxCompute Storage API.

This builder allows configuration of various read session settings including:

• Data and partition column selection
• Partition and bucket filtering
• Split options for parallel processing
• Arrow-specific options
• Filter predicates for data filtering
• Incremental read options

Example usage:

 TableIdentifier tableId = TableIdentifier.of("my_project", "my_table");
 TableReadSessionBuilder builder = client.createReadSessionBuilder(tableId)
     .withRequiredDataColumns(Arrays.asList("col1", "col2"))
     .withRequiredPartitions(Arrays.asList("pt='20250101'"))
     .withSplitOptions(SplitOptions.newBuilder().build());
 TableReadSession session = builder.build();
 

Constructor Summary

Constructors

Constructor and Description
TableReadSessionBuilder(StorageStub storageStub, org.apache.arrow.memory.BufferAllocator allocator, TableIdentifier table) Constructs a new TableReadSessionBuilder with the provided parameters.

Method Summary

Modifier and Type	Method and Description
TableReadSession	build() Builds and returns a new TableReadSession instance with the configured settings.
TableReadSessionBuilder	enableFilterFallback(boolean enable) Sets whether to fallback to no filter if specific filtering fails.
SplitOptions	getSplitOptions()
TableIdentifier	getTable() Gets the table identifier for this builder.
TableReadSessionBuilder	withArrowOptions(ArrowOptions arrowOptions) Sets the Arrow options for data processing.
TableReadSessionBuilder	withBucketIds(List<Integer> requiredBucketIds) Sets the required bucket IDs to read from the table.
TableReadSessionBuilder	withColumns(List<String> requiredDataColumns) Sets the required data columns to read from the table.
TableReadSessionBuilder	withFilter(String filterPredicate) Sets the filter for server-side data filtering.
TableReadSessionBuilder	withIncrementalReadEnabled(boolean incrementalRead) Sets whether to enable incremental read mode for the session.
TableReadSessionBuilder	withIncrementalReadOptions(IncrementalReadOptions incrementalReadOptions) Sets the incremental read options for the read session.
TableReadSessionBuilder	withMaxFilesPerSplit(int maxFilesPerSplit) Sets the maximum number of files per split for reading.
TableReadSessionBuilder	withPartitionColumns(List<String> requiredPartitionColumns) Sets the required partition columns to read from the table.
TableReadSessionBuilder	withPartitions(List<PartitionSpec> requiredPartitions) Sets the required partitions to read from the table.
TableReadSessionBuilder	withSessionId(String sessionId)
TableReadSessionBuilder	withSessionReadyTimeout(long timeoutSeconds) Sets the maximum time to wait for the session to be ready.
TableReadSessionBuilder	withSplitOptions(SplitOptions splitOptions) Sets the split options for parallel processing.

Methods inherited from class java.lang.Object

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

Constructor Detail

TableReadSessionBuilder

public TableReadSessionBuilder(StorageStub storageStub,
                               org.apache.arrow.memory.BufferAllocator allocator,
                               TableIdentifier table)

Constructs a new TableReadSessionBuilder with the provided parameters.

Parameters:

storageStub - The storage stub for communicating with the MaxCompute service

allocator - The buffer allocator for Arrow memory management

table - The identifier of the table to read from

Throws:

IllegalArgumentException - if table is null

Method Detail

withSessionId

public TableReadSessionBuilder withSessionId(String sessionId)

withColumns

public TableReadSessionBuilder withColumns(List<String> requiredDataColumns)

Sets the required data columns to read from the table.

By specifying only the columns needed, network traffic and processing overhead can be reduced.

Parameters:

requiredDataColumns - The list of data column names to read

Returns:

This builder instance for method chaining

withPartitionColumns

public TableReadSessionBuilder withPartitionColumns(List<String> requiredPartitionColumns)

Sets the required partition columns to read from the table.

Parameters:

requiredPartitionColumns - The list of partition column names to read

Returns:

This builder instance for method chaining

withPartitions

public TableReadSessionBuilder withPartitions(List<PartitionSpec> requiredPartitions)

Sets the required partitions to read from the table.

This allows filtering data by specific partition values, reducing the amount of data that needs to be processed.

Parameters:

requiredPartitions - The list of partition specifications to read (e.g., "pt='20250101'")

Returns:

This builder instance for method chaining

withBucketIds

public TableReadSessionBuilder withBucketIds(List<Integer> requiredBucketIds)

Sets the required bucket IDs to read from the table.

This allows filtering data by specific bucket IDs, which is useful for clustered tables.

Parameters:

requiredBucketIds - The list of bucket IDs to read

Returns:

This builder instance for method chaining

withSplitOptions

public TableReadSessionBuilder withSplitOptions(SplitOptions splitOptions)

Sets the split options for parallel processing.

These options control how the data is split into chunks for parallel processing, including split size and other parameters.

Parameters:

splitOptions - The split options configuration

Returns:

This builder instance for method chaining

withArrowOptions

public TableReadSessionBuilder withArrowOptions(ArrowOptions arrowOptions)

Sets the Arrow options for data processing.

These options control Arrow-specific behavior such as memory allocation and serialization settings.

Parameters:

arrowOptions - The Arrow options configuration

Returns:

This builder instance for method chaining

enableFilterFallback

public TableReadSessionBuilder enableFilterFallback(boolean enable)

Sets whether to fallback to no filter if specific filtering fails.

Parameters:

enable - Whether to fallback to no filter

Returns:

This builder instance for method chaining

withFilter

public TableReadSessionBuilder withFilter(String filterPredicate)

Sets the filter for server-side data filtering.

This allows filtering data at the server side, reducing the amount of data transferred over the network.

Parameters:

filterPredicate - The filter predicate expression

Returns:

This builder instance for method chaining

withMaxFilesPerSplit

public TableReadSessionBuilder withMaxFilesPerSplit(int maxFilesPerSplit)

Sets the maximum number of files per split for reading.

Parameters:

maxFilesPerSplit - The maximum number of files per split

Returns:

This builder instance for method chaining

withIncrementalReadOptions

public TableReadSessionBuilder withIncrementalReadOptions(IncrementalReadOptions incrementalReadOptions)

Sets the incremental read options for the read session.

Parameters:

incrementalReadOptions - The incremental read options configuration

Returns:

This builder instance for method chaining

withIncrementalReadEnabled

public TableReadSessionBuilder withIncrementalReadEnabled(boolean incrementalRead)

Sets whether to enable incremental read mode for the session.

Parameters:

incrementalRead - Whether to enable incremental read mode

Returns:

This builder instance for method chaining

withSessionReadyTimeout

public TableReadSessionBuilder withSessionReadyTimeout(long timeoutSeconds)

Sets the maximum time to wait for the session to be ready.

When creating a session, it may take some time for the session to transition from INIT to NORMAL state. This method controls the maximum time to wait for the session to become ready.

Parameters:

timeoutSeconds - The maximum time to wait in seconds (default is 3600 seconds / 1 hour)

Returns:

This builder instance for method chaining

build

public TableReadSession build()

Builds and returns a new TableReadSession instance with the configured settings.

This method makes an API call to the MaxCompute service to create a read session with the specified configuration. The session can then be used to read data from the table in a distributed manner.

If the session is in INIT state, this method will poll the session status until it becomes NORMAL or the timeout is reached. The default wait time is 3600 seconds (1 hour), but can be customized using withSessionReadyTimeout(long).

Returns:

A new TableReadSession instance

Throws:

ClientException - if the session creation fails or times out

MaxStorageException - if the session cannot be created due to server-side errors

getTable

public TableIdentifier getTable()

Gets the table identifier for this builder.

Returns:

The table identifier.

getSplitOptions

public SplitOptions getSplitOptions()