Implementation:Apache Paimon Path

Knowledge Sources	Apache_Paimon
Domains	File System Abstraction, URI Handling, Cross-Platform Compatibility
Last Updated	2026-02-08 00:00 GMT

Overview

Path is Paimon's own file system path abstraction that names files and directories, supporting multiple URI schemes with cross-platform compatibility.

Description

Path (public API since 0.4.0) wraps a java.net.URI internally, providing multiple constructors for creating paths from strings, parent+child paths, scheme+authority+path components, and URIs. The class handles URI parsing manually rather than using new URI(String) to support unescaped characters needed for glob processing.

The implementation normalizes paths by removing duplicated slashes, handling Windows drive letters (C:, D:, etc.), and trimming trailing separators. It is platform-aware with Windows detection for proper backslash handling. The class provides getName() for the final path component, getParent() for the parent directory, toUri() for URI conversion, and createTempPath() for generating temporary file paths. It implements Comparable<Path> based on URI comparison.

This is a fundamental file system abstraction used throughout Paimon for all storage operations. It replaces Hadoop's org.apache.hadoop.fs.Path to eliminate the Hadoop dependency in the API layer, which is a key design goal of the paimon-api module. Every table location, snapshot file, manifest file, and data file is referenced through this class.

Usage

Use Path to represent file and directory locations in Paimon tables across different file systems (local, HDFS, S3, OSS, etc.).

Code Reference

Source Location

• Repository: Apache_Paimon
• File: paimon-api/src/main/java/org/apache/paimon/fs/Path.java
• Lines: 1-384

Signature

@Public
public class Path implements Comparable<Path>, Serializable {

    public static final String SEPARATOR = "/";
    public static final char SEPARATOR_CHAR = '/';
    public static final String CUR_DIR = ".";
    public static final boolean WINDOWS = System.getProperty("os.name").startsWith("Windows");

    private URI uri;

    // Constructors
    public Path(String pathString) { }
    public Path(String parent, String child) { }
    public Path(Path parent, String child) { }
    public Path(URI aUri) { }
    public Path(String scheme, String authority, String path) { }

    // Methods
    public URI toUri() { return uri; }
    public String getName() { }
    public Path getParent() { }
    public Path createTempPath() { }

    @Override
    public String toString() { }

    @Override
    public int compareTo(Path that) {
        return this.uri.compareTo(that.uri);
    }
}

Import

import org.apache.paimon.fs.Path;

I/O Contract

Inputs

Name	Type	Required	Description
pathString	String	yes (constructor)	Path string as URI with unescaped elements
parent	Path/String	no	Parent directory path
child	Path/String	no	Child path component
scheme	String	no	URI scheme (e.g., hdfs, s3, file)
authority	String	no	URI authority (host:port)

Outputs

Name	Type	Description
uri	URI	Normalized URI representation
name	String	Final path component (file or directory name)
parent	Path	Parent directory path (null if at root)
tempPath	Path	Temporary path with UUID suffix

Usage Examples

Creating Paths

import org.apache.paimon.fs.Path;

// Create path from string
Path tablePath = new Path("/warehouse/my_database/my_table");
System.out.println("Table path: " + tablePath);

// Create path from parent and child
Path parent = new Path("/warehouse/my_database");
Path table = new Path(parent, "my_table");
System.out.println("Table: " + table.getName());
System.out.println("Database: " + table.getParent().getName());

// Create path with scheme and authority
Path hdfsPath = new Path("hdfs", "namenode:8020", "/warehouse/my_table");
System.out.println("HDFS path: " + hdfsPath);
System.out.println("URI: " + hdfsPath.toUri());

// Create S3 path
Path s3Path = new Path("s3://my-bucket/warehouse/my_table");
System.out.println("S3 path: " + s3Path);

Working with Path Components

import org.apache.paimon.fs.Path;

Path dataFile = new Path("hdfs://namenode:8020/warehouse/db/table/data/file-1.orc");

// Extract components
String fileName = dataFile.getName();
Path dataDir = dataFile.getParent();
Path tableDir = dataDir.getParent();

System.out.println("File name: " + fileName);
System.out.println("Data directory: " + dataDir);
System.out.println("Table directory: " + tableDir);

// Create temporary path
Path tempFile = dataFile.createTempPath();
System.out.println("Temporary path: " + tempFile);
// Example output: /warehouse/db/table/data/.file-1.orc.a1b2c3d4-e5f6-7890-abcd-ef1234567890.tmp

Cross-Platform Path Handling

import org.apache.paimon.fs.Path;

// Windows path handling
if (Path.WINDOWS) {
    Path windowsPath = new Path("C:/Users/data/table");
    System.out.println("Windows path: " + windowsPath);
    // Automatically handles backslashes and drive letters
}

// Unix path
Path unixPath = new Path("/home/user/data/table");
System.out.println("Unix path: " + unixPath);

// Both normalize to forward slashes internally
System.out.println("Separator: " + Path.SEPARATOR);

Related Pages

• Principle:Apache_Paimon_File_System_Abstraction