jacques-n commented on a change in pull request #1849: URL: https://github.com/apache/iceberg/pull/1849#discussion_r536470421
########## File path: api/src/main/java/org/apache/iceberg/catalog/SupportsCatalogTransactions.java ########## @@ -0,0 +1,162 @@ +/* + * 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.catalog; + +import java.util.Set; + +/** + * Catalog methods for working with catalog-level transactions. + * + * <p>Catalog implementations are not required to support catalog-level transactional state. + * If they do, they may support one or more {@code IsolationLevel}s and one or more + * {@code LockingMode}s. + */ +public interface SupportsCatalogTransactions { + + /** + * The level of isolation for a catalog-level transaction. + * + * <p>Isolation covers both what data is read and what data can be written. + * + * <p>At all levels, data is only visible if it is either committed by another transaction or + * committed by a nested transaction within this catalog-level transaction. + * + * <p>Individual nested Table transactions may be "rebased" to expose updated versions of a + * table if the isolation level allows that behavior. + * + * <p>In the definitions of each isolation level, the concept of conflicting writes is + * referenced. Conflicting writes are two mutations to the same object that happen concurrently. + * Depending on the particular implementation, the coarseness of this conflict may vary. The + * most coarse conflict is any two mutations to the same table. However, some implementations + * may consider some of these "absolute" conflicts as allowable by using finer-grained conflict + * resolution. For example, two different operations that both append new files to a table may + * be in "absolute" conflict but could be resolved automatically as a "safe conflict" by using + * a set of automatic implementation-defined conflict resolution rules. + */ + enum IsolationLevel { + + /** + * Reading the same table multiple times may result in different versions read of the same + * table. A commit can be completed as long as any tables changed externally do not conflict + * with any writes within this transaction. + */ + READ_COMMITTED, + + /** + * Reading the same table multiple times will result in the same view of that table. + * Different tables may come from different snapshots. A commit can be completed as + * long as any tables changed externally do not conflict with any writes within this + * transaction. + */ + REPEATED_READ, + + /** + * A commit will only succeed if there have been no meaningful changes to data read during + * the course of this transaction prior to commit. This imposes stricter read guarantees than + * {@code REPEATED_READ} (consistent reads per table) as it requires that the reads are + * consistent for all tables to a single point in time (or single snapshot of the database). + * Additionally, it implies additional requirements around the successful completion of a + * write. In order for a write to complete, any entities read during this transaction are also + * blocked from changing (via another transaction) post-read in ways that would influence the + * writes of this operation. This is also sometimes called snapshot isolation. Review comment: I updated the sentence here to clarify that it covers those guarantees, rather than suggesting they are interchangeable. ---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
