From 9edd089ebeba80be83165721fd1754a3fc6e85de Mon Sep 17 00:00:00 2001 From: Li Feiyang Date: Wed, 22 Oct 2025 18:51:39 +0800 Subject: [PATCH 1/2] feat: add basic REST Catalog request/response models --- src/iceberg/catalog/rest/request_types.h | 84 +++++++++++++++++++++ src/iceberg/catalog/rest/response_types.h | 90 +++++++++++++++++++++++ 2 files changed, 174 insertions(+) create mode 100644 src/iceberg/catalog/rest/request_types.h create mode 100644 src/iceberg/catalog/rest/response_types.h diff --git a/src/iceberg/catalog/rest/request_types.h b/src/iceberg/catalog/rest/request_types.h new file mode 100644 index 000000000..13d3a9d72 --- /dev/null +++ b/src/iceberg/catalog/rest/request_types.h @@ -0,0 +1,84 @@ +/* + * 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 +#include +#include +#include +#include + +#include "iceberg/catalog/rest/iceberg_rest_export.h" +#include "iceberg/partition_spec.h" +#include "iceberg/schema.h" +#include "iceberg/sort_order.h" +#include "iceberg/table_identifier.h" + +namespace iceberg::rest { + +/// \brief Request to create a namespace. +/// \details Corresponds to **POST /v1/{prefix}/namespaces**. +/// Allows creating a new namespace with optional properties. +struct ICEBERG_REST_EXPORT CreateNamespaceRequest { + Namespace namespace_; // required + std::unordered_map properties; +}; + +/// \brief Request to update or remove namespace properties. +/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/properties**. +/// Allows setting and/or removing namespace properties in a single call. +/// Properties not listed in this request are left unchanged. +struct ICEBERG_REST_EXPORT UpdateNamespaceRequest { + std::vector removals; + std::unordered_map updates; +}; + +/// \brief Request to create a table. +/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/tables**. +/// If `stage_create` is false, the table is created immediately. +/// If `stage_create` is true, metadata is prepared and returned without committing, +/// allowing a later transaction commit via the table commit endpoint. +struct ICEBERG_REST_EXPORT CreateTableRequest { + std::string name; // required + std::string location; + std::shared_ptr schema; // required + std::shared_ptr partition_spec; + std::shared_ptr write_order; + std::optional stage_create; + std::unordered_map properties; +}; + +/// \brief Request to register an existing table. +/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/register**. +/// Registers an existing table using a given metadata file location. +struct ICEBERG_REST_EXPORT RegisterTableRequest { + std::string name; // required + std::string metadata_location; // required + std::optional overwrite; +}; + +/// \brief Request to rename a table. +/// \details Corresponds to **POST /v1/{prefix}/tables/rename**. +/// Moves or renames a table from the source identifier to the destination identifier. +struct ICEBERG_REST_EXPORT RenameTableRequest { + TableIdentifier source; // required + TableIdentifier destination; // required +}; + +} // namespace iceberg::rest diff --git a/src/iceberg/catalog/rest/response_types.h b/src/iceberg/catalog/rest/response_types.h new file mode 100644 index 000000000..81580b1e1 --- /dev/null +++ b/src/iceberg/catalog/rest/response_types.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. + */ + +#pragma once + +#include +#include +#include +#include + +#include "iceberg/catalog/rest/iceberg_rest_export.h" +#include "iceberg/table_identifier.h" +#include "iceberg/table_metadata.h" + +namespace iceberg::rest { + +/// \brief An opaque token that allows clients to make use of pagination for list APIs. +using PageToken = std::string; + +/// \brief Result body for table create/load/register APIs. +/// \details Matches **components/schemas/LoadTableResult** in the REST spec. +struct ICEBERG_REST_EXPORT LoadTableResult { + std::optional metadata_location; + TableMetadata metadata; // required + std::unordered_map config; + // TODO(Li Feiyang): Add std::vector storage_credentials; +}; + +/// \brief Alias of LoadTableResult used as the body of CreateTableResponse +using CreateTableResponse = LoadTableResult; + +/// \brief Alias of LoadTableResult used as the body of LoadTableResponse +using LoadTableResponse = LoadTableResult; + +/// \brief Alias of LoadTableResult used as the body of RegisterTableResponse +using RegisterTableResponse = LoadTableResult; + +/// \brief Response body for listing namespaces. +/// Contains all namespaces and an optional pagination token. +struct ICEBERG_REST_EXPORT ListNamespacesResponse { + std::optional next_page_token; + std::vector namespaces; +}; + +/// \brief Response body after creating a namespace. +/// \details Contains the created namespace and its resolved properties. +struct ICEBERG_REST_EXPORT CreateNamespaceResponse { + Namespace namespace_; // required + std::unordered_map properties; +}; + +/// \brief Response body for loading namespace properties. +/// \details Contains stored properties, may be null if unsupported by the server. +struct ICEBERG_REST_EXPORT GetNamespaceResponse { + Namespace namespace_; // required + std::unordered_map properties; +}; + +/// \brief Response body after updating namespace properties. +/// \details Lists keys that were updated, removed, or missing. +struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesResponse { + std::vector updated; // required + std::vector removed; // required + std::vector missing; +}; + +/// \brief Response body for listing tables in a namespace. +/// \details Contains all table identifiers and an optional pagination token. +struct ICEBERG_REST_EXPORT ListTablesResponse { + std::optional next_page_token; + std::vector identifiers; +}; + +} // namespace iceberg::rest From e497ec49127a7d24956e8eadc207774d6eee809e Mon Sep 17 00:00:00 2001 From: Li Feiyang Date: Thu, 23 Oct 2025 18:16:30 +0800 Subject: [PATCH 2/2] fix review --- src/iceberg/catalog/rest/meson.build | 2 +- src/iceberg/catalog/rest/request_types.h | 84 ------------------- src/iceberg/catalog/rest/rest_catalog.cc | 2 + .../rest/{response_types.h => types.h} | 59 +++++++++---- 4 files changed, 48 insertions(+), 99 deletions(-) delete mode 100644 src/iceberg/catalog/rest/request_types.h rename src/iceberg/catalog/rest/{response_types.h => types.h} (62%) diff --git a/src/iceberg/catalog/rest/meson.build b/src/iceberg/catalog/rest/meson.build index 0c32cb625..9d8a7d384 100644 --- a/src/iceberg/catalog/rest/meson.build +++ b/src/iceberg/catalog/rest/meson.build @@ -46,4 +46,4 @@ iceberg_rest_dep = declare_dependency( meson.override_dependency('iceberg-rest', iceberg_rest_dep) pkg.generate(iceberg_rest_lib) -install_headers(['rest_catalog.h'], subdir: 'iceberg/catalog/rest') +install_headers(['rest_catalog.h', 'types.h'], subdir: 'iceberg/catalog/rest') diff --git a/src/iceberg/catalog/rest/request_types.h b/src/iceberg/catalog/rest/request_types.h deleted file mode 100644 index 13d3a9d72..000000000 --- a/src/iceberg/catalog/rest/request_types.h +++ /dev/null @@ -1,84 +0,0 @@ -/* - * 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 -#include -#include -#include -#include - -#include "iceberg/catalog/rest/iceberg_rest_export.h" -#include "iceberg/partition_spec.h" -#include "iceberg/schema.h" -#include "iceberg/sort_order.h" -#include "iceberg/table_identifier.h" - -namespace iceberg::rest { - -/// \brief Request to create a namespace. -/// \details Corresponds to **POST /v1/{prefix}/namespaces**. -/// Allows creating a new namespace with optional properties. -struct ICEBERG_REST_EXPORT CreateNamespaceRequest { - Namespace namespace_; // required - std::unordered_map properties; -}; - -/// \brief Request to update or remove namespace properties. -/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/properties**. -/// Allows setting and/or removing namespace properties in a single call. -/// Properties not listed in this request are left unchanged. -struct ICEBERG_REST_EXPORT UpdateNamespaceRequest { - std::vector removals; - std::unordered_map updates; -}; - -/// \brief Request to create a table. -/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/tables**. -/// If `stage_create` is false, the table is created immediately. -/// If `stage_create` is true, metadata is prepared and returned without committing, -/// allowing a later transaction commit via the table commit endpoint. -struct ICEBERG_REST_EXPORT CreateTableRequest { - std::string name; // required - std::string location; - std::shared_ptr schema; // required - std::shared_ptr partition_spec; - std::shared_ptr write_order; - std::optional stage_create; - std::unordered_map properties; -}; - -/// \brief Request to register an existing table. -/// \details Corresponds to **POST /v1/{prefix}/namespaces/{namespace}/register**. -/// Registers an existing table using a given metadata file location. -struct ICEBERG_REST_EXPORT RegisterTableRequest { - std::string name; // required - std::string metadata_location; // required - std::optional overwrite; -}; - -/// \brief Request to rename a table. -/// \details Corresponds to **POST /v1/{prefix}/tables/rename**. -/// Moves or renames a table from the source identifier to the destination identifier. -struct ICEBERG_REST_EXPORT RenameTableRequest { - TableIdentifier source; // required - TableIdentifier destination; // required -}; - -} // namespace iceberg::rest diff --git a/src/iceberg/catalog/rest/rest_catalog.cc b/src/iceberg/catalog/rest/rest_catalog.cc index a9b18b5f9..cd008e9b2 100644 --- a/src/iceberg/catalog/rest/rest_catalog.cc +++ b/src/iceberg/catalog/rest/rest_catalog.cc @@ -23,6 +23,8 @@ #include +#include "iceberg/catalog/rest/types.h" + namespace iceberg::catalog::rest { RestCatalog::RestCatalog(const std::string& base_url) : base_url_(std::move(base_url)) {} diff --git a/src/iceberg/catalog/rest/response_types.h b/src/iceberg/catalog/rest/types.h similarity index 62% rename from src/iceberg/catalog/rest/response_types.h rename to src/iceberg/catalog/rest/types.h index 81580b1e1..4c50ab268 100644 --- a/src/iceberg/catalog/rest/response_types.h +++ b/src/iceberg/catalog/rest/types.h @@ -19,6 +19,7 @@ #pragma once +#include #include #include #include @@ -26,20 +27,58 @@ #include "iceberg/catalog/rest/iceberg_rest_export.h" #include "iceberg/table_identifier.h" -#include "iceberg/table_metadata.h" +#include "iceberg/type_fwd.h" + +/// \file iceberg/catalog/rest/types.h +/// Request and response types for Iceberg REST Catalog API. namespace iceberg::rest { +/// \brief Request to create a namespace. +struct ICEBERG_REST_EXPORT CreateNamespaceRequest { + Namespace namespace_; // required + std::unordered_map properties; +}; + +/// \brief Update or delete namespace properties request. +struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesRequest { + std::vector removals; + std::unordered_map updates; +}; + +/// \brief Request to create a table. +struct ICEBERG_REST_EXPORT CreateTableRequest { + std::string name; // required + std::string location; + std::shared_ptr schema; // required + std::shared_ptr partition_spec; + std::shared_ptr write_order; + std::optional stage_create; + std::unordered_map properties; +}; + +/// \brief Request to register a table. +struct ICEBERG_REST_EXPORT RegisterTableRequest { + std::string name; // required + std::string metadata_location; // required + bool overwrite = false; +}; + +/// \brief Request to rename a table. +struct ICEBERG_REST_EXPORT RenameTableRequest { + TableIdentifier source; // required + TableIdentifier destination; // required +}; + /// \brief An opaque token that allows clients to make use of pagination for list APIs. using PageToken = std::string; /// \brief Result body for table create/load/register APIs. -/// \details Matches **components/schemas/LoadTableResult** in the REST spec. struct ICEBERG_REST_EXPORT LoadTableResult { std::optional metadata_location; - TableMetadata metadata; // required + std::shared_ptr metadata; // required // required std::unordered_map config; - // TODO(Li Feiyang): Add std::vector storage_credentials; + // TODO(Li Feiyang): Add std::shared_ptr storage_credential; }; /// \brief Alias of LoadTableResult used as the body of CreateTableResponse @@ -48,32 +87,25 @@ using CreateTableResponse = LoadTableResult; /// \brief Alias of LoadTableResult used as the body of LoadTableResponse using LoadTableResponse = LoadTableResult; -/// \brief Alias of LoadTableResult used as the body of RegisterTableResponse -using RegisterTableResponse = LoadTableResult; - /// \brief Response body for listing namespaces. -/// Contains all namespaces and an optional pagination token. struct ICEBERG_REST_EXPORT ListNamespacesResponse { - std::optional next_page_token; + PageToken next_page_token; std::vector namespaces; }; /// \brief Response body after creating a namespace. -/// \details Contains the created namespace and its resolved properties. struct ICEBERG_REST_EXPORT CreateNamespaceResponse { Namespace namespace_; // required std::unordered_map properties; }; /// \brief Response body for loading namespace properties. -/// \details Contains stored properties, may be null if unsupported by the server. struct ICEBERG_REST_EXPORT GetNamespaceResponse { Namespace namespace_; // required std::unordered_map properties; }; /// \brief Response body after updating namespace properties. -/// \details Lists keys that were updated, removed, or missing. struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesResponse { std::vector updated; // required std::vector removed; // required @@ -81,9 +113,8 @@ struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesResponse { }; /// \brief Response body for listing tables in a namespace. -/// \details Contains all table identifiers and an optional pagination token. struct ICEBERG_REST_EXPORT ListTablesResponse { - std::optional next_page_token; + PageToken next_page_token; std::vector identifiers; };