kbendick commented on code in PR #5516: URL: https://github.com/apache/iceberg/pull/5516#discussion_r945209431
########## api/src/main/java/org/apache/iceberg/actions/GenerateSymlinkManifest.java: ########## @@ -0,0 +1,50 @@ +/* + * 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. + */ +package org.apache.iceberg.actions; + +/** + * An action that generates a symlink manifest table for an Iceberg table. + * + * <p>This action will generate symlink manifests for a table. A symlink manifest is a file with + * links to the data files in the table. Systems which do not integrate with Iceberg can read the Review Comment: Nit: This paragraph is correct in explaining what a symlink manifest is, but I do encounter a number of people on Slack / in the community who aren’t aware that Icebergs metadata tracks the files already. I worry this will make that _less_ clear. Is it possible to document the symlink manifest without making it seem like Iceberg doesn’t already track the files? Maybe something like the following would help. `A symlink manifest is a standardized table format (specification file?) that many other systems can read. It consists of links to the data files in the table, like Iceberg, but without the additional metadata that Iceberg includes. Systems which do not integrate with Iceberg can read the …` Not necessarily in love with the phrasing I provided here. But given that we often wind up fielding questions from users because they don’t recognize that Iceberg tracks all table files explicitly, it would be nice to make that a bit more explicit when mentioning the symlink manifest format so as not to potentially introduce more confusion (especially for users who don’t necessarily read the docs, but might have questions on this action e.g. with Athena and then _do_ read this JavaDoc ). Again, not blocking as this is a good description overall. But I know we both answered a question about table layout on Slack just this week for a user who was assuming that Iceberg was doing listing to get partition info. It would be good to reduce the chances of getting more of these types of questions if possible. 🙂 -- 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]
