File System#

Interface#

class FileSystem#

Abstract file system interface.

Public Functions

virtual ~FileSystem()#
virtual Result<std::unique_ptr<InputStream>> Open(const std::string &path) const = 0#

Open an existing file for reading.

Parameters:

path – The file path to open.

Returns:

Result containing a unique pointer to InputStream on success, or error status on failure (e.g., file not found, permission denied).

virtual Result<std::unique_ptr<OutputStream>> Create(const std::string &path, bool overwrite) const = 0#

Create a new file for writing.

Parameters:

  • path – The file path to create.

  • overwrite – If true, overwrite existing file; if false, fail if file exists.

Returns:

Result containing a unique pointer to OutputStream on success, or error status on failure (e.g., I/O error, permission denied).

virtual Status Mkdirs(const std::string &path) const = 0#

Create directories recursively.

Parameters:

path – The directory path to create (including all parent directories).

Returns:

Status indicating success (OK) or failure with error information.

virtual Status Rename(const std::string &src, const std::string &dst) const = 0#

Rename or move a file or directory.

Parameters:

  • src – The source path (file or directory to rename/move).

  • dst – The destination path.

Returns:

Status indicating success (OK) or failure with error information.

virtual Status Delete(const std::string &path, bool recursive = true) const = 0#

Delete a file or directory.

Parameters:

  • path – The path to delete.

  • recursive – If true, delete directories and their contents recursively; if false, only delete empty directories.

Returns:

Status indicating success (OK) or failure with error information.

virtual Result<std::unique_ptr<FileStatus>> GetFileStatus(const std::string &path) const = 0#

Get detailed status information for a file or directory.

Parameters:

path – The file or directory path to query.

Returns:

Result containing a unique pointer to FileStatus on success, or error status on failure (e.g., path not found, permission denied).

virtual Status ListDir(const std::string &directory, std::vector<std::unique_ptr<BasicFileStatus>> *file_status_list) const = 0#

List files of a directory (basic information only).

Parameters:

  • directory – The directory path to list.

  • file_status_list – [out] Output vector to store BasicFileStatus objects.

Returns:

Status indicating success (OK) or failure with error information.

virtual Status ListFileStatus(const std::string &path, std::vector<std::unique_ptr<FileStatus>> *file_status_list) const = 0#

List file status with detailed information.

Parameters:

  • path – The file or directory path to list.

  • file_status_list – [out] Output vector to store FileStatus objects.

Returns:

Status indicating success (OK) or failure with error information.

virtual Result<bool> Exists(const std::string &path) const = 0#

Check if a file or directory exists.

Parameters:

path – The file or directory path to check.

Returns:

Result containing true if path exists, false if not found; or error status if I/O error occurs during check.

virtual Status ReadFile(const std::string &path, std::string *content)#

Read entire file content into a string at once.

Note

Virtual only for mock testing purposes.

Parameters:

  • path – The file path to read.

  • content – [out] Output string to store the file content.

Returns:

Status indicating success (OK) or failure with error information.

virtual Status WriteFile(const std::string &path, const std::string &content, bool overwrite)#

Write the entire content to a file at once.

Note

Virtual only for mock testing purposes.

Parameters:

  • path – The file path to write to.

  • content – The string content to write.

  • overwrite – If true, overwrite existing file; if false, fail if file exists.

Returns:

Status indicating success (OK) or failure with error information.

virtual Status AtomicStore(const std::string &path, const std::string &content)#

Write content to a file atomically.

Atomic operation: writes to temporary hidden file first, then renames to target.

Note

Virtual only for mock testing purposes.

Parameters:

  • path – The target file path.

  • content – The string content to write.

Returns:

Status indicating success (OK) or failure with error information.

Public Static Functions

static Result<bool> IsObjectStore(const std::string &path_str)#

Check if the given path represents an object store.

Note

Object stores typically have different semantics than traditional file systems.

class FileSystemFactory : public paimon::Factory#

A factory for creating FileSystem instances.

Public Functions

virtual Result<std::unique_ptr<FileSystem>> Create(const std::string &path, const std::map<std::string, std::string> &options) const = 0#

Create a FileSystem of current factory with specific path.

Public Static Functions

static Result<std::unique_ptr<FileSystem>> Get(const std::string &identifier, const std::string &path, const std::map<std::string, std::string> &fs_options)#

Get FileSystem corresponding to identifier and specific path.

Pre:

Factory is already registered.

class InputStream : public paimon::Stream#

Abstract class for input stream operations.

Subclassed by paimon::BufferedInputStream, paimon::ByteArrayInputStream

Public Functions

InputStream() = default#
~InputStream() override = default#
virtual Status Seek(int64_t offset, SeekOrigin origin) = 0#

Seek to a specified position in the input stream.

Parameters:
Returns:

Status indicating success (OK) or failure with appropriate error information.

virtual Result<int64_t> GetPos() const = 0#

Get the current position in the input stream.

Returns:

Current position in the input stream.

Returns:

IOError returned if an I/O error occurred in the underlying stream. implementation while accessing the stream’s position.

virtual Result<int32_t> Read(char *buffer, uint32_t size) = 0#

Read data from the current position in the stream.

Note

The stream position advances by the number of bytes actually read.

Parameters:

  • buffer – [out] Pointer to the buffer where read data will be stored.

  • size – Maximum number of bytes to read.

Returns:

Result containing the actual number of bytes read on success, or an error status on failure.

virtual Result<int32_t> Read(char *buffer, uint32_t size, uint64_t offset) = 0#

Read data from given position in the stream.

Read with offset performs like pread() function, which will not change the position in the input stream.

Parameters:

  • buffer – [out] The buffer to store the read content.

  • size – The number of bytes to read.

  • offset – The position in the stream to read from.

virtual void ReadAsync(char *buffer, uint32_t size, uint64_t offset, std::function<void(Status)> &&callback) = 0#

Asynchronously read data from the input stream.

This function initiates an asynchronous read operation. The specified number of bytes will be read from the stream starting at the given offset and stored in the provided buffer. Once the read operation is complete, the provided callback function will be invoked with the status of the read operation.

Parameters:

  • buffer – [out] The buffer to store the read content.

  • size – The number of bytes to read.

  • offset – The position in the stream to read from.

  • callback – The callback function to be invoked upon completion of the read operation. The callback will receive a Status object indicating the success or failure of the read operation.

virtual Result<std::string> GetUri() const = 0#

Get an identifier that uniquely identify the underlying content.

Returns:

An uri if the underlying content can be uniquely identified.

Returns:

Empty string if the underlying content cannot be uniquely identified.

virtual Result<uint64_t> Length() const = 0#

Get the total length of the file in bytes.

class OutputStream : public paimon::Stream#

Abstract class for output stream operations.

Public Functions

OutputStream() = default#
virtual Result<int32_t> Write(const char *buffer, uint32_t size) = 0#

Write data to the output stream.

Note

The stream position advances by the number of bytes actually written.

Parameters:

  • buffer – Pointer to the data buffer to write.

  • size – Number of bytes to write from the buffer.

Returns:

Result containing the actual number of bytes written on success, or an error status on failure.

virtual Status Flush() = 0#

Flush pending data to the disk.

virtual Result<int64_t> GetPos() const = 0#

Get the write position.

virtual Result<std::string> GetUri() const = 0#

Get the uri of the output stream.

enum paimon::SeekOrigin#

Enumeration for stream seek origin positions.

Values:

enumerator FS_SEEK_SET#

Seek from the beginning of the stream.

enumerator FS_SEEK_CUR#

Seek from the current position in the stream.

enumerator FS_SEEK_END#

Seek from the end of the stream.

class FileStatus#

Extended file status information interface.

This class extends BasicFileStatus to provide comprehensive file system metadata including file size, modification time, and other attributes. It’s used for operations that require detailed file information.

Public Functions

FileStatus() = default#
virtual ~FileStatus() = default#
virtual uint64_t GetLen() const = 0#

Get the size of the file in bytes.

Note

For directories, this method is undefined behavior.

virtual bool IsDir() const = 0#

Check if this entry represents a directory.

virtual std::string GetPath() const = 0#

Get the path of this file or directory.

virtual int64_t GetModificationTime() const = 0#

Get the last modification time of the file.

Returns:

A long value representing the time the file was last modified, measured in milliseconds since the epoch (UTC January 1, 1970).

class BasicFileStatus#

Basic file status information interface.

This class provides fundamental file system metadata for files and directories. It serves as a lightweight interface for basic file operations that only require path information and directory status.

Public Functions

BasicFileStatus() = default#
virtual ~BasicFileStatus() = default#
virtual bool IsDir() const = 0#

Check if this entry represents a directory.

virtual std::string GetPath() const = 0#

Get the path of this file or directory.