Add pure virtual classes for Catalog, Table, etc.

Author: wgtmac

example/demo_example.cc

@@ -21,11 +21,11 @@
 
 #include "iceberg/arrow/demo_arrow.h"
 #include "iceberg/avro/demo_avro.h"
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 #include "iceberg/puffin/demo_puffin.h"
 
 int main() {
-  std::cout << iceberg::DemoTable().print() << std::endl;
+  std::cout << iceberg::Demo().print() << std::endl;
   std::cout << iceberg::puffin::DemoPuffin().print() << std::endl;
   std::cout << iceberg::arrow::DemoArrow().print() << std::endl;
   std::cout << iceberg::avro::DemoAvro().print() << std::endl;

src/iceberg/CMakeLists.txt

@@ -15,7 +15,7 @@
 # specific language governing permissions and limitations
 # under the License.
 
-set(ICEBERG_SOURCES demo_table.cc schema.cc schema_field.cc type.cc)
+set(ICEBERG_SOURCES demo.cc schema.cc schema_field.cc type.cc)
 
 add_iceberg_lib(iceberg
                 SOURCES

src/iceberg/arrow/demo_arrow.cc

@@ -21,13 +21,12 @@
 
 #include <arrow/config.h>
 
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::arrow {
 
 std::string DemoArrow::print() const {
-  return DemoTable().print() +
-         ", Arrow version: " + ::arrow::GetBuildInfo().version_string;
+  return Demo().print() + ", Arrow version: " + ::arrow::GetBuildInfo().version_string;
 }
 
 }  // namespace iceberg::arrow

src/iceberg/arrow/demo_arrow.h

@@ -22,11 +22,11 @@
 #include <string>
 
 #include "iceberg/arrow/iceberg_arrow_export.h"
-#include "iceberg/table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::arrow {
 
-class ICEBERG_ARROW_EXPORT DemoArrow : public Table {
+class ICEBERG_ARROW_EXPORT DemoArrow : public Demo {
  public:
   DemoArrow() = default;
   ~DemoArrow() override = default;

src/iceberg/avro/demo_avro.cc

@@ -23,7 +23,7 @@
 
 #include "avro/Compiler.hh"
 #include "avro/ValidSchema.hh"
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 namespace iceberg::avro {
 

src/iceberg/catalog.h

@@ -0,0 +1,178 @@
+/*
+ * 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 <string>
+#include <vector>
+
+#include "iceberg/expected.h"
+#include "iceberg/table_identifier.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief A Catalog API for table create, drop, and load operations.
+class ICEBERG_EXPORT Catalog {
+ public:
+  virtual ~Catalog() = default;
+
+  /// \brief Return the name for this catalog
+  virtual std::string name() const = 0;
+
+  /// \brief Return all the identifiers under this namespace
+  ///
+  /// \param ns a namespace
+  /// \return a list of identifiers for tables or Error::kNoSuchNamespace
+  /// if the namespace does not exist
+  virtual expected<std::vector<TableIdentifier>, Error> ListTables(
+      const Namespace& ns) const = 0;
+
+  /// \brief Create a table
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \param spec a partition spec
+  /// \param location a location for the table; leave empty if unspecified
+  /// \param properties a string map of table properties
+  /// \return a Table instance or Error::kAlreadyExists if the table already exists
+  virtual expected<std::unique_ptr<Table>, Error> CreateTable(
+      const TableIdentifier& identifier, const Schema& schema, const PartitionSpec& spec,
+      const std::string& location,
+      const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Start a transaction to create a table
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \param spec a partition spec
+  /// \param location a location for the table; leave empty if unspecified
+  /// \param properties a string map of table properties
+  /// \return a Transaction to create the table or Error::kAlreadyExists if the table
+  /// already exists
+  virtual expected<std::shared_ptr<Transaction>, Error> NewCreateTableTransaction(
+      const TableIdentifier& identifier, const Schema& schema, const PartitionSpec& spec,
+      const std::string& location,
+      const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Check whether table exists
+  ///
+  /// \param identifier a table identifier
+  /// \return true if the table exists, false otherwise
+  virtual bool TableExists(const TableIdentifier& identifier) const = 0;
+
+  /// \brief Drop a table; optionally delete data and metadata files
+  ///
+  /// If purge is set to true the implementation should delete all data and metadata
+  /// files.
+  ///
+  /// \param identifier a table identifier
+  /// \param purge if true, delete all data and metadata files in the table
+  /// \return true if the table was dropped, false if the table did not exist
+  virtual bool DropTable(const TableIdentifier& identifier, bool purge) = 0;
+
+  /// \brief Load a table
+  ///
+  /// \param identifier a table identifier
+  /// \return instance of Table implementation referred to by identifier or
+  /// Error::kNoSuchTable if the table does not exist
+  virtual expected<std::shared_ptr<Table>, Error> LoadTable(
+      const TableIdentifier& identifier) const = 0;
+
+  /// \brief Register a table with the catalog if it does not exist
+  ///
+  /// \param identifier a table identifier
+  /// \param metadata_file_location the location of a metadata file
+  /// \return a Table instance or Error::kAlreadyExists if the table already exists
+  virtual expected<std::shared_ptr<Table>, Error> RegisterTable(
+      const TableIdentifier& identifier, const std::string& metadata_file_location) = 0;
+
+  /// \brief Initialize a catalog given a custom name and a map of catalog properties
+  ///
+  /// A custom Catalog implementation must have a default constructor. A compute engine
+  /// will first initialize the catalog without any arguments, and then call this method
+  /// to complete catalog initialization with properties passed into the engine.
+  ///
+  /// \param name a custom name for the catalog
+  /// \param properties catalog properties
+  virtual void Initialize(const std::string& name,
+                          const std::map<std::string, std::string>& properties) = 0;
+
+  /// \brief Instantiate a builder to either create a table or start a create/replace
+  /// transaction
+  ///
+  /// \param identifier a table identifier
+  /// \param schema a schema
+  /// \return the builder to create a table or start a create/replace transaction
+  virtual std::unique_ptr<class TableBuilder> BuildTable(
+      const TableIdentifier& identifier, const Schema& schema) const = 0;
+
+  /// \brief A builder used to create valid tables or start create/replace transactions
+  class TableBuilder {
+   public:
+    virtual ~TableBuilder() = default;
+
+    /// \brief Sets a partition spec for the table
+    ///
+    /// \param spec a partition spec
+    /// \return this for method chaining
+    virtual TableBuilder& WithPartitionSpec(const PartitionSpec& spec) = 0;
+
+    /// \brief Sets a sort order for the table
+    ///
+    /// \param sort_order a sort order
+    /// \return this for method chaining
+    virtual TableBuilder& WithSortOrder(const SortOrder& sort_order) = 0;
+
+    /// \brief Sets a location for the table
+    ///
+    /// \param location a location
+    /// \return this for method chaining
+    virtual TableBuilder& WithLocation(const std::string& location) = 0;
+
+    /// \brief Adds key/value properties to the table
+    ///
+    /// \param properties key/value properties
+    /// \return this for method chaining
+    virtual TableBuilder& WithProperties(
+        const std::map<std::string, std::string>& properties) = 0;
+
+    /// \brief Adds a key/value property to the table
+    ///
+    /// \param key a key
+    /// \param value a value
+    /// \return this for method chaining
+    virtual TableBuilder& WithProperty(const std::string& key,
+                                       const std::string& value) = 0;
+
+    /// \brief Creates the table
+    ///
+    /// \return the created table
+    virtual std::unique_ptr<Table> Create() = 0;
+
+    /// \brief Starts a transaction to create the table
+    ///
+    /// \return the Transaction to create the table
+    virtual std::unique_ptr<Transaction> CreateTransaction() = 0;
+  };
+};
+
+}  // namespace iceberg

src/iceberg/demo_table.cc renamed to src/iceberg/demo.cc

@@ -17,13 +17,18 @@
  * under the License.
  */
 
-#include "iceberg/demo_table.h"
+#include "iceberg/demo.h"
 
 #include "iceberg/avro.h"  // include to export symbols
+#include "iceberg/catalog.h"
+#include "iceberg/location_provider.h"
 #include "iceberg/puffin.h"
+#include "iceberg/table.h"
+#include "iceberg/table_operations.h"
+#include "iceberg/transaction.h"
 
 namespace iceberg {
 
-std::string DemoTable::print() const { return "DemoTable"; }
+std::string Demo::print() const { return "Demo"; }
 
 }  // namespace iceberg

src/iceberg/demo_table.h renamed to src/iceberg/demo.h

@@ -19,16 +19,18 @@
 
 #pragma once
 
-#include "iceberg/table.h"
+#include <string>
+
+#include "iceberg/iceberg_export.h"
 
 namespace iceberg {
 
-class ICEBERG_EXPORT DemoTable : public Table {
+class ICEBERG_EXPORT Demo {
  public:
-  DemoTable() = default;
-  ~DemoTable() override = default;
+  Demo() = default;
+  virtual ~Demo() = default;
 
-  std::string print() const override;
+  virtual std::string print() const;
 };
 
 }  // namespace iceberg

src/iceberg/location_provider.h

@@ -0,0 +1,56 @@
+/*
+ * 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 <string>
+
+#include "iceberg/iceberg_export.h"
+#include "iceberg/type_fwd.h"
+
+namespace iceberg {
+
+/// \brief Interface for providing data file locations to write tasks.
+class ICEBERG_EXPORT LocationProvider {
+ public:
+  virtual ~LocationProvider() = default;
+
+  /// \brief Return a fully-qualified data file location for the given filename.
+  ///
+  /// \param filename a file name
+  /// \return a fully-qualified location URI for a data file
+  virtual std::string NewDataLocation(const std::string& filename) = 0;
+
+  /// \brief Return a fully-qualified data file location for the given partition and
+  /// filename.
+  ///
+  /// \param spec a partition spec
+  /// \param partition_data a tuple of partition data for data in the file, matching the
+  /// given spec
+  /// \param filename a file name
+  /// \return a fully-qualified location URI for a data file
+  ///
+  /// TODO(wgtmac): StructLike is not well thought yet, we may wrap an ArrowArray
+  /// with single row in StructLike.
+  virtual std::string NewDataLocation(const PartitionSpec& spec,
+                                      const StructLike& partition_data,
+                                      const std::string& filename) = 0;
+};
+
+}  // namespace iceberg