manuzhang commented on code in PR #1066: URL: https://github.com/apache/iceberg-cpp/pull/1066#discussion_r4388231834
########## src/iceberg/inspect/metadata_scan.h: ########## @@ -0,0 +1,123 @@ +/* + * 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 + +/// \file iceberg/inspect/metadata_scan.h +/// \brief Configure metadata table scans, plan tasks, and read rows as Arrow batches. + +#include <memory> +#include <string> +#include <vector> + +#include "iceberg/arrow_c_data.h" +#include "iceberg/iceberg_export.h" +#include "iceberg/inspect/metadata_scan_task.h" +#include "iceberg/result.h" +#include "iceberg/type_fwd.h" +#include "iceberg/util/error_collector.h" +#include "iceberg/util/stream.h" + +namespace iceberg { + +using MetadataScanTaskStream = Stream<std::shared_ptr<MetadataScanTask>>; +using MetadataScanTaskStreamPtr = std::unique_ptr<MetadataScanTaskStream>; + +namespace internal { + +/// \brief Scan settings and the source metadata captured by the builder. +struct MetadataScanContext { + MetadataTableKind kind; + std::shared_ptr<const TableMetadata> table_metadata; + std::string metadata_file_location; + std::shared_ptr<Schema> schema; // metadata table schema + std::shared_ptr<Schema> projected_schema; + std::shared_ptr<FileIO> io; + bool case_sensitive = true; +}; + +} // namespace internal + +/// \brief Configure a scan over the metadata captured when this builder is created. +class ICEBERG_EXPORT MetadataScanBuilder : public ErrorCollector { + public: + /// \brief Create a builder for a metadata table; source and schema must be non-null. + /// + /// The schema must describe the metadata table, not the source data table. + static Result<std::unique_ptr<MetadataScanBuilder>> Make( + std::shared_ptr<const Table> source, MetadataTableKind kind, + std::shared_ptr<Schema> schema); + + /// \brief Select columns by name; nested columns use dot-separated paths. + /// + /// An empty list selects no columns; `*` selects all columns. Names are resolved + /// immediately, using the current CaseSensitive() setting. + MetadataScanBuilder& Select(const std::vector<std::string>& columns); + + /// \brief Set the output schema to a projection of the metadata table schema. + MetadataScanBuilder& Project(std::shared_ptr<Schema> schema); + + /// \brief Use case-sensitive column names; enabled by default. + MetadataScanBuilder& CaseSensitive(bool value); + + /// \brief Validate the settings and build a scan with its own copy of them. + /// + /// Returns validation errors or NotImplemented for unsupported metadata table kinds. + /// Later builder changes and table refreshes do not change the returned scan. + Result<std::unique_ptr<MetadataScan>> Build(); + + private: + MetadataScanBuilder(std::shared_ptr<const Table> source, MetadataTableKind kind, + std::shared_ptr<Schema> schema); + + internal::MetadataScanContext context_; +}; + +/// \brief A metadata scan that can plan reusable tasks or read their rows as Arrow. +class ICEBERG_EXPORT MetadataScan { + public: + virtual ~MetadataScan(); + + /// \brief Return a fresh task stream; consuming it may report planning errors. + /// + /// Destroying the stream releases its resources, including after a partial read. + virtual Result<MetadataScanTaskStreamPtr> PlanTasksStream() const = 0; + + /// \brief Collect all tasks, returning any error from PlanTasksStream(). + virtual Result<std::vector<std::shared_ptr<MetadataScanTask>>> PlanTasks() const; + + /// \brief Read every task as one Arrow stream with the requested output schema. + /// + /// The default implementation collects tasks, then reads them in planning order. + /// The returned stream owns its read state and can outlive this scan. The caller + /// must release the stream and each returned schema or array independently. + /// Releasing the stream early closes the active task stream. To customize + /// batch size, open planned tasks with MetadataScanTaskReader instead. Review Comment: It looks there's no public API for MetadataScanTaskReader to access internal fields of `MetadataScanContext`. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
