feat: add paimon-cpp public headers

Author: lszskye

include/paimon/api.h

@@ -0,0 +1,40 @@
+/*
+ * Copyright 2024-present Alibaba Inc.
+ *
+ * Licensed 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.
+ */
+
+// Coarse public API while the library is in development
+
+#pragma once
+
+#include "paimon/commit_context.h"           // IWYU pragma: export
+#include "paimon/defs.h"                     // IWYU pragma: export
+#include "paimon/factories/factory.h"        // IWYU pragma: export
+#include "paimon/file_store_commit.h"        // IWYU pragma: export
+#include "paimon/file_store_write.h"         // IWYU pragma: export
+#include "paimon/fs/file_system_factory.h"   // IWYU pragma: export
+#include "paimon/memory/memory_pool.h"       // IWYU pragma: export
+#include "paimon/predicate/predicate.h"      // IWYU pragma: export
+#include "paimon/read_context.h"             // IWYU pragma: export
+#include "paimon/reader/batch_reader.h"      // IWYU pragma: export
+#include "paimon/record_batch.h"             // IWYU pragma: export
+#include "paimon/result.h"                   // IWYU pragma: export
+#include "paimon/scan_context.h"             // IWYU pragma: export
+#include "paimon/status.h"                   // IWYU pragma: export
+#include "paimon/table/source/table_read.h"  // IWYU pragma: export
+#include "paimon/table/source/table_scan.h"  // IWYU pragma: export
+#include "paimon/write_context.h"            // IWYU pragma: export
+
+/// Top-level namespace for Paimon C++ API.
+namespace paimon {}

include/paimon/arrow/abi.h

@@ -0,0 +1,90 @@
+// 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.
+
+// Adapted from Apache Arrow
+// https://github.com/apache/arrow/blob/main/cpp/src/arrow/c/abi.h
+
+/// \file abi.h Arrow C Data Interface
+///
+/// The Arrow C Data interface defines a very small, stable set
+/// of C definitions which can be easily copied into any project's
+/// source code and vendored to be used for columnar data interchange
+/// in the Arrow format. For non-C/C++ languages and runtimes,
+/// it should be almost as easy to translate the C definitions into
+/// the corresponding C FFI declarations.
+///
+/// Applications and libraries can therefore work with Arrow memory
+/// without necessarily using the Arrow libraries or reinventing
+/// the wheel. Developers can choose between tight integration
+/// with the Arrow software project or minimal integration with
+/// the Arrow format only.
+
+#pragma once
+
+#include <cstdint>
+
+// Spec and documentation: https://arrow.apache.org/docs/format/CDataInterface.html
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#ifndef ARROW_C_DATA_INTERFACE
+#define ARROW_C_DATA_INTERFACE
+
+#define ARROW_FLAG_DICTIONARY_ORDERED 1
+#define ARROW_FLAG_NULLABLE 2
+#define ARROW_FLAG_MAP_KEYS_SORTED 4
+
+struct ArrowSchema {
+    // Array type description
+    const char* format;
+    const char* name;
+    const char* metadata;
+    int64_t flags;
+    int64_t n_children;
+    struct ArrowSchema** children;
+    struct ArrowSchema* dictionary;
+
+    // Release callback
+    void (*release)(struct ArrowSchema*);
+    // Opaque producer-specific data
+    void* private_data;
+};
+
+struct ArrowArray {
+    // Array data description
+    int64_t length;
+    int64_t null_count;
+    int64_t offset;
+    int64_t n_buffers;
+    int64_t n_children;
+    const void** buffers;
+    struct ArrowArray** children;
+    struct ArrowArray* dictionary;
+
+    // Release callback
+    void (*release)(struct ArrowArray*);
+    // Opaque producer-specific data
+    void* private_data;
+};
+
+#endif  // ARROW_C_DATA_INTERFACE
+
+#ifdef __cplusplus
+}
+#endif

include/paimon/catalog/catalog.h

@@ -0,0 +1,98 @@
+/*
+ * Copyright 2024-present Alibaba Inc.
+ *
+ * Licensed 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 <string>
+#include <vector>
+
+#include "paimon/catalog/identifier.h"
+#include "paimon/result.h"
+#include "paimon/status.h"
+#include "paimon/type_fwd.h"
+#include "paimon/visibility.h"
+
+struct ArrowSchema;
+
+namespace paimon {
+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.
+    /// @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);
+
+    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;
+};
+
+}  // namespace paimon

include/paimon/catalog/identifier.h

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2024-present Alibaba Inc.
+ *
+ * Licensed 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 <string>
+
+#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:
+    Identifier(const std::string& database, const std::string& table);
+
+    bool operator==(const Identifier& other);
+    const std::string& GetDatabaseName() const;
+    const std::string& GetTableName() const;
+    std::string ToString() const;
+
+ private:
+    const std::string database_;
+    const std::string table_;
+};
+
+}  // namespace paimon