types.h

Go to the documentation of this file.

/*
 * 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 <cstdint>
#include <memory>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
 
#include "iceberg/catalog/rest/endpoint.h"
#include "iceberg/catalog/rest/iceberg_rest_export.h"
#include "iceberg/result.h"
#include "iceberg/storage_credential.h"
#include "iceberg/table_identifier.h"
#include "iceberg/type_fwd.h"
#include "iceberg/util/macros.h"
 
 
namespace iceberg::rest {
 
enum class PlanStatus {
  kSubmitted,
  kCompleted,
  kCancelled,
  kFailed,
};
 
ICEBERG_REST_EXPORT std::string_view ToString(PlanStatus status);
ICEBERG_REST_EXPORT Result<PlanStatus> PlanStatusFromString(std::string_view status_str);
 
struct ICEBERG_REST_EXPORT CatalogConfig {
  std::unordered_map<std::string, std::string> defaults;   // required
  std::unordered_map<std::string, std::string> overrides;  // required
  std::vector<Endpoint> endpoints;
 
  Status Validate() const { return {}; }
 
  bool operator==(const CatalogConfig&) const = default;
};
 
struct ICEBERG_REST_EXPORT ErrorResponse {
  uint32_t code;        // required
  std::string type;     // required
  std::string message;  // required
  std::vector<std::string> stack;
 
  Status Validate() const {
    if (message.empty() || type.empty()) {
      return ValidationFailed("Invalid error response: missing required fields");
    }
 
    if (code < 400 || code > 600) {
      return ValidationFailed(
          "Invalid error response: code {} is out of range [400, 600]", code);
    }
 
    // stack is optional, no validation needed
    return {};
  }
 
  bool operator==(const ErrorResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT CreateNamespaceRequest {
  Namespace namespace_;  // required
  std::unordered_map<std::string, std::string> properties;
 
  Status Validate() const { return {}; }
 
  bool operator==(const CreateNamespaceRequest&) const = default;
};
 
struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesRequest {
  std::vector<std::string> removals;
  std::unordered_map<std::string, std::string> updates;
 
  Status Validate() const {
    for (const auto& key : removals) {
      if (updates.contains(key)) {
        return ValidationFailed("Duplicate key to update and remove: {}", key);
      }
    }
    return {};
  }
 
  bool operator==(const UpdateNamespacePropertiesRequest&) const = default;
};
 
struct ICEBERG_REST_EXPORT RegisterTableRequest {
  std::string name;               // required
  std::string metadata_location;  // required
  bool overwrite = false;
 
  Status Validate() const {
    if (name.empty()) {
      return ValidationFailed("Missing table name");
    }
 
    if (metadata_location.empty()) {
      return ValidationFailed("Empty metadata location");
    }
 
    return {};
  }
 
  bool operator==(const RegisterTableRequest&) const = default;
};
 
struct ICEBERG_REST_EXPORT RenameTableRequest {
  TableIdentifier source;       // required
  TableIdentifier destination;  // required
 
  Status Validate() const {
    ICEBERG_RETURN_UNEXPECTED(source.Validate());
    ICEBERG_RETURN_UNEXPECTED(destination.Validate());
    return {};
  }
 
  bool operator==(const RenameTableRequest&) const = default;
};
 
struct ICEBERG_REST_EXPORT CreateTableRequest {
  std::string name;  // required
  std::string location;
  std::shared_ptr<Schema> schema;  // required
  std::shared_ptr<PartitionSpec> partition_spec;
  std::shared_ptr<SortOrder> write_order;
  bool stage_create = false;
  std::unordered_map<std::string, std::string> properties;
 
  Status Validate() const {
    if (name.empty()) {
      return ValidationFailed("Missing table name");
    }
    if (!schema) {
      return ValidationFailed("Missing schema");
    }
    return {};
  }
 
  bool operator==(const CreateTableRequest& other) const;
};
 
using PageToken = std::string;
 
struct ICEBERG_REST_EXPORT LoadTableResult {
  std::string metadata_location;
  std::shared_ptr<TableMetadata> metadata;  // required
  std::unordered_map<std::string, std::string> config;
  std::vector<StorageCredential> storage_credentials;
 
  Status Validate() const {
    if (!metadata) {
      return ValidationFailed("Invalid metadata: null");
    }
    for (const auto& credential : storage_credentials) {
      ICEBERG_RETURN_UNEXPECTED(credential.Validate());
    }
    return {};
  }
 
  bool operator==(const LoadTableResult& other) const;
};
 
using CreateTableResponse = LoadTableResult;
 
using LoadTableResponse = LoadTableResult;
 
struct ICEBERG_REST_EXPORT ListNamespacesResponse {
  PageToken next_page_token;
  std::vector<Namespace> namespaces;
 
  Status Validate() const { return {}; }
 
  bool operator==(const ListNamespacesResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT CreateNamespaceResponse {
  Namespace namespace_;  // required
  std::unordered_map<std::string, std::string> properties;
 
  Status Validate() const { return {}; }
 
  bool operator==(const CreateNamespaceResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT GetNamespaceResponse {
  Namespace namespace_;  // required
  std::unordered_map<std::string, std::string> properties;
 
  Status Validate() const { return {}; }
 
  bool operator==(const GetNamespaceResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT UpdateNamespacePropertiesResponse {
  std::vector<std::string> updated;  // required
  std::vector<std::string> removed;  // required
  std::vector<std::string> missing;
 
  Status Validate() const { return {}; }
 
  bool operator==(const UpdateNamespacePropertiesResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT ListTablesResponse {
  PageToken next_page_token;
  std::vector<TableIdentifier> identifiers;
 
  Status Validate() const { return {}; }
 
  bool operator==(const ListTablesResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT CommitTableRequest {
  TableIdentifier identifier;
  std::vector<std::shared_ptr<TableRequirement>> requirements;  // required
  std::vector<std::shared_ptr<TableUpdate>> updates;            // required
 
  Status Validate() const { return {}; }
 
  bool operator==(const CommitTableRequest& other) const;
};
 
struct ICEBERG_REST_EXPORT CommitTableResponse {
  std::string metadata_location;            // required
  std::shared_ptr<TableMetadata> metadata;  // required
 
  Status Validate() const {
    if (metadata_location.empty()) {
      return ValidationFailed("Invalid metadata location: empty");
    }
    if (!metadata) {
      return ValidationFailed("Invalid metadata: null");
    }
    return {};
  }
 
  bool operator==(const CommitTableResponse& other) const;
};
 
struct ICEBERG_REST_EXPORT OAuthTokenResponse {
  std::string access_token;                // required
  std::string token_type;                  // required, "bearer" or "N_A"
  std::optional<int64_t> expires_in_secs;  // optional, seconds until expiration
  std::string issued_token_type;           // optional, for token exchange
  std::string refresh_token;               // optional
  std::string scope;                       // optional
 
  Status Validate() const;
 
  bool operator==(const OAuthTokenResponse&) const = default;
};
 
struct ICEBERG_REST_EXPORT PlanTableScanRequest {
  std::optional<int64_t> snapshot_id;
  std::vector<std::string> select;
  std::shared_ptr<Expression> filter;
  bool case_sensitive = true;
  bool use_snapshot_schema = false;
  std::optional<int64_t> start_snapshot_id;
  std::optional<int64_t> end_snapshot_id;
  std::vector<std::string> stats_fields;
  std::optional<int64_t> min_rows_requested;
 
  Status Validate() const;
 
  bool operator==(const PlanTableScanRequest&) const;
};
 
struct ICEBERG_REST_EXPORT PlanTableScanResponse {
  std::optional<std::vector<std::string>> plan_tasks;
  std::optional<std::vector<std::shared_ptr<FileScanTask>>> file_scan_tasks;
  std::vector<std::shared_ptr<DataFile>> delete_files;
  PlanStatus plan_status = PlanStatus::kCompleted;
  std::string plan_id;
  std::optional<ErrorResponse> error;
  // TODO(sandeepg): Add storage credentials and bind scan FileIO to them.
 
  Status Validate() const;
 
  bool operator==(const PlanTableScanResponse&) const;
};
 
struct ICEBERG_REST_EXPORT FetchPlanningResultResponse {
  std::optional<std::vector<std::string>> plan_tasks;
  std::optional<std::vector<std::shared_ptr<FileScanTask>>> file_scan_tasks;
  std::vector<std::shared_ptr<DataFile>> delete_files;
  PlanStatus plan_status = PlanStatus::kCompleted;
  std::optional<ErrorResponse> error;
  // TODO(sandeepg): Add storage credentials and bind scan FileIO to them.
 
  Status Validate() const;
 
  bool operator==(const FetchPlanningResultResponse&) const;
};
 
struct ICEBERG_REST_EXPORT FetchScanTasksRequest {
  std::string planTask;
 
  Status Validate() const;
 
  bool operator==(const FetchScanTasksRequest&) const;
};
 
struct ICEBERG_REST_EXPORT FetchScanTasksResponse {
  std::optional<std::vector<std::string>> plan_tasks;
  std::optional<std::vector<std::shared_ptr<FileScanTask>>> file_scan_tasks;
  std::vector<std::shared_ptr<DataFile>> delete_files;
 
  Status Validate() const;
 
  bool operator==(const FetchScanTasksResponse&) const;
};
 
}  // namespace iceberg::rest