API: Add view interfaces (#4925)

Co-authored-by: [email protected]
Co-authored-by: [email protected]

api/src/main/java/org/apache/iceberg/catalog/ViewCatalog.java

@@ -0,0 +1,119 @@
+/*
+ * 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.List;
+import java.util.Map;
+import org.apache.iceberg.exceptions.AlreadyExistsException;
+import org.apache.iceberg.exceptions.NoSuchViewException;
+import org.apache.iceberg.exceptions.NotFoundException;
+import org.apache.iceberg.view.View;
+import org.apache.iceberg.view.ViewBuilder;
+
+/** A Catalog API for view create, drop, and load operations. */
+public interface ViewCatalog {
+
+  /**
+   * Return the name for this catalog.
+   *
+   * @return this catalog's name
+   */
+  String name();
+
+  /**
+   * Return all the identifiers under this namespace.
+   *
+   * @param namespace a namespace
+   * @return a list of identifiers for views
+   * @throws NotFoundException if the namespace is not found
+   */
+  List<TableIdentifier> listViews(Namespace namespace);
+
+  /**
+   * Load a view.
+   *
+   * @param identifier a view identifier
+   * @return instance of {@link View} implementation referred by the identifier
+   * @throws NoSuchViewException if the view does not exist
+   */
+  View loadView(TableIdentifier identifier);
+
+  /**
+   * Check whether view exists.
+   *
+   * @param identifier a view identifier
+   * @return true if the view exists, false otherwise
+   */
+  default boolean viewExists(TableIdentifier identifier) {
+    try {
+      loadView(identifier);
+      return true;
+    } catch (NoSuchViewException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Instantiate a builder to create or replace a SQL view.
+   *
+   * @param identifier a view identifier
+   * @return a view builder
+   */
+  ViewBuilder buildView(TableIdentifier identifier);
+
+  /**
+   * Drop a view.
+   *
+   * @param identifier a view identifier
+   * @return true if the view was dropped, false if the view did not exist
+   */
+  boolean dropView(TableIdentifier identifier);
+
+  /**
+   * Rename a view.
+   *
+   * @param from identifier of the view to rename
+   * @param to new view identifier
+   * @throws NoSuchViewException if the "from" view does not exist
+   * @throws AlreadyExistsException if the "to" view already exists
+   */
+  void renameView(TableIdentifier from, TableIdentifier to);
+
+  /**
+   * Invalidate cached view metadata from current catalog.
+   *
+   * <p>If the view is already loaded or cached, drop cached data. If the view does not exist or is
+   * not cached, do nothing.
+   *
+   * @param identifier a view identifier
+   */
+  default void invalidateView(TableIdentifier identifier) {}
+
+  /**
+   * Initialize a view catalog given a custom name and a map of catalog properties.
+   *
+   * <p>A custom view catalog implementation must have a no-arg constructor. A compute engine like
+   * Spark or Flink will first initialize the catalog without any arguments, and then call this
+   * method to complete catalog initialization with properties passed into the engine.
+   *
+   * @param name a custom name for the catalog
+   * @param properties catalog properties
+   */
+  default void initialize(String name, Map<String, String> properties) {}
+}

api/src/main/java/org/apache/iceberg/exceptions/NoSuchViewException.java

@@ -0,0 +1,34 @@
+/*
+ * 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.exceptions;
+
+import com.google.errorprone.annotations.FormatMethod;
+
+/** Exception raised when attempting to load a view that does not exist. */
+public class NoSuchViewException extends RuntimeException {
+  @FormatMethod
+  public NoSuchViewException(String message, Object... args) {
+    super(String.format(message, args));
+  }
+
+  @FormatMethod
+  public NoSuchViewException(Throwable cause, String message, Object... args) {
+    super(String.format(message, args), cause);
+  }
+}

api/src/main/java/org/apache/iceberg/view/SQLViewRepresentation.java

@@ -0,0 +1,52 @@
+/*
+ * 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.view;
+
+import java.util.List;
+import org.apache.iceberg.Schema;
+import org.apache.iceberg.catalog.Namespace;
+
+public interface SQLViewRepresentation extends ViewRepresentation {
+
+  @Override
+  default Type type() {
+    return Type.SQL;
+  }
+
+  /** The view query SQL text. */
+  String query();
+
+  /** The view query SQL dialect. */
+  String dialect();
+
+  /** The default catalog when the view is created. */
+  String defaultCatalog();
+
+  /** The default namespace when the view is created. */
+  Namespace defaultNamespace();
+
+  /** The query output schema at version create time, without aliases. */
+  Schema schema();
+
+  /** The view field aliases. */
+  List<String> fieldComments();
+
+  /** The view field comments. */
+  List<String> fieldAliases();
+}

api/src/main/java/org/apache/iceberg/view/UpdateViewProperties.java

@@ -0,0 +1,52 @@
+/*
+ * 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.view;
+
+import java.util.Map;
+import org.apache.iceberg.PendingUpdate;
+
+/**
+ * API for updating view properties.
+ *
+ * <p>Apply returns the updated view properties as a map for validation.
+ *
+ * <p>When committing, these changes will be applied to the current view metadata. Commit conflicts
+ * will be resolved by applying the pending changes to the new view metadata.
+ */
+public interface UpdateViewProperties extends PendingUpdate<Map<String, String>> {
+
+  /**
+   * Add a key/value property to the view.
+   *
+   * @param key a String key
+   * @param value a String value
+   * @return this for method chaining
+   * @throws NullPointerException If either the key or value is null
+   */
+  UpdateViewProperties set(String key, String value);
+
+  /**
+   * Remove the given property key from the view.
+   *
+   * @param key a String key
+   * @return this for method chaining
+   * @throws NullPointerException If the key is null
+   */
+  UpdateViewProperties remove(String key);
+}

api/src/main/java/org/apache/iceberg/view/View.java

@@ -0,0 +1,86 @@
+/*
+ * 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.view;
+
+import java.util.List;
+import java.util.Map;
+import org.apache.iceberg.Schema;
+
+/** Interface for view definition. */
+public interface View {
+
+  String name();
+
+  /**
+   * Return the {@link Schema schema} for this view.
+   *
+   * @return this table's schema
+   */
+  Schema schema();
+
+  /**
+   * Return a map of {@link Schema schema} for this view.
+   *
+   * @return this table's schema map
+   */
+  Map<Integer, Schema> schemas();
+
+  /**
+   * Get the current version for this view, or null if there are no versions.
+   *
+   * @return the current view version.
+   */
+  ViewVersion currentVersion();
+
+  /**
+   * Get the versions of this view.
+   *
+   * @return an Iterable of versions of this view.
+   */
+  Iterable<ViewVersion> versions();
+
+  /**
+   * Get a version in this view by ID.
+   *
+   * @param versionId version ID
+   * @return a version, or null if the ID cannot be found
+   */
+  ViewVersion version(int versionId);
+
+  /**
+   * Get the version history of this table.
+   *
+   * @return a list of {@link ViewHistoryEntry}
+   */
+  List<ViewHistoryEntry> history();
+
+  /**
+   * Return a map of string properties for this view.
+   *
+   * @return this view's properties map
+   */
+  Map<String, String> properties();
+
+  /**
+   * Create a new {@link UpdateViewProperties} to update view properties.
+   *
+   * @return a new {@link UpdateViewProperties}
+   */
+  UpdateViewProperties updateProperties();
+}