feat(catalog): add catalog interfaces, file system catalog and snapshot

include/paimon/catalog/catalog.h

@@ -0,0 +1,205 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <chrono>
+#include <map>
+#include <memory>
+#include <optional>
+#include <string>
+#include <variant>
+#include <vector>
+
+#include "paimon/catalog/identifier.h"
+#include "paimon/result.h"
+#include "paimon/snapshot/snapshot_info.h"
+#include "paimon/status.h"
+#include "paimon/type_fwd.h"
+#include "paimon/visibility.h"
+
+struct ArrowSchema;
+
+namespace paimon {
+// Tag name or snapshot id
+using Instant = std::variant<std::string, int64_t>;
+
+class Database;
+class Table;
+class View;
+class Schema;
+class Snapshot;
+class PartitionStatistics;
+class Tag;
+class Identifier;
+/// This interface is responsible for reading and writing metadata such as database/table from a
+/// paimon catalog.
+class PAIMON_EXPORT Catalog {
+ public:
+    static const char SYSTEM_DATABASE_NAME[];
+    static const char SYSTEM_TABLE_SPLITTER[];
+    static const char DB_SUFFIX[];
+    static const char DB_LOCATION_PROP[];
+
+    /// %Factory method for creating a `Catalog` instance.
+    ///
+    /// @param root_path Path to the root directory where the catalog is located.
+    /// @param options Configuration options for catalog initialization.
+    /// @param file_system Specifies the file system for file operations.
+    ///                    If not set, use default file system (configured in
+    ///                    `Options::FILE_SYSTEM`)
+    /// @return A result containing a unique pointer to a `Catalog` instance, or an error status.
+    static Result<std::unique_ptr<Catalog>> Create(
+        const std::string& root_path, const std::map<std::string, std::string>& options,
+        const std::shared_ptr<FileSystem>& file_system = nullptr);
+
+    virtual ~Catalog() = default;
+
+    /// Creates a database with the specified properties.
+    ///
+    /// @param name Name of the database to be created.
+    /// @param options Additional properties associated with the database.
+    /// @param ignore_if_exists If true, no action is taken if the database already exists.
+    ///                         If false, an error status is returned if the database exists.
+    /// @return A status indicating success or failure.
+    virtual Status CreateDatabase(const std::string& name,
+                                  const std::map<std::string, std::string>& options,
+                                  bool ignore_if_exists) = 0;
+
+    /// Creates a new table in the catalog.
+    ///
+    /// @note System tables cannot be created using this method.
+    ///
+    /// @param identifier Identifier of the table to be created.
+    /// @param c_schema The schema of the table to be created.
+    /// @param partition_keys List of columns that should be used as partition keys for the table.
+    /// @param primary_keys List of columns that should be used as primary keys for the table.
+    /// @param options Additional table-specific options.
+    /// @param ignore_if_exists If true, no action is taken if the table already exists.
+    ///                         If false, an error status is returned if the table exists.
+    /// @return A status indicating success or failure.
+    virtual Status CreateTable(const Identifier& identifier, ArrowSchema* c_schema,
+                               const std::vector<std::string>& partition_keys,
+                               const std::vector<std::string>& primary_keys,
+                               const std::map<std::string, std::string>& options,
+                               bool ignore_if_exists) = 0;
+
+    /// Lists all the databases available in the catalog.
+    ///
+    /// @return A result containing a vector of database names, or an error status.
+    virtual Result<std::vector<std::string>> ListDatabases() const = 0;
+
+    /// Lists all the tables within a specified database.
+    ///
+    /// @note System tables will not be listed.
+    ///
+    /// @param db_name The name of the database to list tables from.
+    /// @return A result containing a vector of table names in the specified database, or an error
+    /// status.
+    virtual Result<std::vector<std::string>> ListTables(const std::string& db_name) const = 0;
+
+    /// Drops a database.
+    ///
+    /// @param name Name of the database to be dropped.
+    /// @param ignore_if_not_exists If true, no action is taken if the database does not exist.
+    /// @param cascade If true, drops all tables and functions in the database before dropping the
+    /// database.
+    /// @return A status indicating success or failure.
+    virtual Status DropDatabase(const std::string& name, bool ignore_if_not_exists,
+                                bool cascade) = 0;
+
+    /// Drops a table.
+    ///
+    /// @param identifier Identifier of the table to drop.
+    /// @param ignore_if_not_exists If true, no action is taken if the table does not exist.
+    /// @return A status indicating success or failure.
+    virtual Status DropTable(const Identifier& identifier, bool ignore_if_not_exists) = 0;
+
+    /// Renames a table.
+    ///
+    /// @param from_table Current identifier of the table.
+    /// @param to_table New identifier for the table.
+    /// @param ignore_if_not_exists If true, no action is taken if the table does not exist.
+    /// @return A status indicating success or failure.
+    virtual Status RenameTable(const Identifier& from_table, const Identifier& to_table,
+                               bool ignore_if_not_exists) = 0;
+
+    /// Gets a table.
+    ///
+    /// @param identifier Identifier of the table to get.
+    /// @return A result containing the table, or an error status.
+    virtual Result<std::shared_ptr<Table>> GetTable(const Identifier& identifier) const = 0;
+
+    /// Checks whether a database with the specified name exists in the catalog.
+    ///
+    /// @param db_name The name of the database to check for existence.
+    /// @return A result containing true if the database exists, false otherwise, or an error
+    /// status.
+    virtual Result<bool> DatabaseExists(const std::string& db_name) const = 0;
+
+    /// Checks whether a table with the specified identifier exists in the catalog.
+    ///
+    /// @param identifier The identifier of the table to check for existence.
+    /// @return A result containing true if the table exists, false otherwise, or an error status.
+    virtual Result<bool> TableExists(const Identifier& identifier) const = 0;
+
+    /// Returns the expected location of a specified database.
+    ///
+    /// @note This does not check whether the database actually exists.
+    ///
+    /// @param db_name The name of the database to get the location for.
+    /// @return A string representing the expected location of the database.
+    virtual std::string GetDatabaseLocation(const std::string& db_name) const = 0;
+
+    /// Returns the expected location of a specified table.
+    ///
+    /// @note This does not check whether the table actually exists.
+    ///
+    /// @param identifier The table identifier containing database and table name.
+    /// @return A string representing the expected location of the table.
+    virtual std::string GetTableLocation(const Identifier& identifier) const = 0;
+
+    /// Returns the root path of the catalog.
+    ///
+    /// @return A string representing the root path of the catalog.
+    virtual std::string GetRootPath() const = 0;
+
+    /// Returns the file system used by the catalog.
+    ///
+    /// @return A shared pointer to the file system instance.
+    virtual std::shared_ptr<FileSystem> GetFileSystem() const = 0;
+
+    /// Loads the latest schema of a specified table.
+    ///
+    /// @note System tables will not be supported.
+    ///
+    /// @param identifier The identifier (database and table name) of the table to load.
+    /// @return A result containing table schema if the table exists, or an error status on failure.
+    virtual Result<std::shared_ptr<Schema>> LoadTableSchema(const Identifier& identifier) const = 0;
+
+    /// Lists all snapshots of the specified table, ordered by snapshot id.
+    ///
+    /// @param identifier The identifier (database and table name) of the table.
+    /// @param branch Branch name; empty string means the main branch.
+    /// @return A result containing a vector of SnapshotInfo ordered by
+    ///         snapshot id ascending, or an error status.
+    virtual Result<std::vector<SnapshotInfo>> ListSnapshots(
+        const Identifier& identifier, const std::string& branch = "") const = 0;
+};
+
+}  // namespace paimon

include/paimon/catalog/database.h

@@ -0,0 +1,55 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <map>
+#include <memory>
+#include <optional>
+#include <string>
+#include <vector>
+
+#include "paimon/result.h"
+#include "paimon/status.h"
+#include "paimon/type_fwd.h"
+#include "paimon/visibility.h"
+
+struct ArrowSchema;
+
+namespace paimon {
+
+/// Interface of a database in a catalog.
+class PAIMON_EXPORT Database {
+ public:
+    virtual ~Database() = default;
+
+    /// ================== Database Metadata =====================
+
+    /// A name to identify this database.
+    virtual std::string Name() const = 0;
+
+    /// Get the database-level options associated with this database.
+    /// @return Options
+    virtual const std::map<std::string, std::string>& Options() const = 0;
+
+    /// Get an optional comment describing the database.
+    /// @return The database comment if set, or std::nullopt otherwise.
+    virtual std::optional<std::string> Comment() const = 0;
+};
+
+}  // namespace paimon

include/paimon/catalog/identifier.h

@@ -0,0 +1,62 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include <optional>
+#include <string>
+
+#include "paimon/result.h"
+#include "paimon/type_fwd.h"
+#include "paimon/visibility.h"
+
+namespace paimon {
+
+/// An identifier for a table containing database and table name.
+class PAIMON_EXPORT Identifier {
+ public:
+    static const char kUnknownDatabase[];
+    static const char kSystemTableSplitter[];
+    static const char kSystemBranchPrefix[];
+    static const char kDefaultMainBranch[];
+
+    explicit Identifier(const std::string& table);
+    Identifier(const std::string& database, const std::string& table);
+
+    bool operator==(const Identifier& other);
+    const std::string& GetDatabaseName() const;
+    const std::string& GetTableName() const;
+    Result<std::string> GetDataTableName() const;
+    Result<std::optional<std::string>> GetBranchName() const;
+    Result<std::string> GetBranchNameOrDefault() const;
+    Result<std::optional<std::string>> GetSystemTableName() const;
+    Result<bool> IsSystemTable() const;
+    std::string ToString() const;
+
+ private:
+    Status SplitTableName() const;
+
+    const std::string database_;
+    const std::string table_;
+    mutable bool parsed_ = false;
+    mutable std::string data_table_;
+    mutable std::optional<std::string> branch_;
+    mutable std::optional<std::string> system_table_;
+};
+
+}  // namespace paimon