[WIP] API/Core: View support

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

@@ -0,0 +1,159 @@
+/*
+ * 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.Collections;
+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.ViewDefinition;
+import org.apache.iceberg.view.ViewRepresentation;
+
+/**
+ * A Catalog API for view create, drop, and load operations.
+ */
+public interface ViewCatalog {
+
+  /**
+   * Return the name for this catalog.
+   *
+   * @return this catalog's name
+   */
+  default String name() {
+    return toString();
+  }
+
+  /**
+   * Return all the identifiers under this namespace.
+   *
+   * @param namespace a namespace
+   * @return a list of identifiers for view
+   * @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 {@code tableIdentifier}
+   * @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 table exists, false otherwise
+   */
+  default boolean viewExists(TableIdentifier identifier) {
+    try {
+      loadView(identifier);
+      return true;
+    } catch (NoSuchViewException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Create a view.
+   *
+   * @param identifier a view identifier
+   * @param representations a list of view representations
+   * @param properties a string map of view properties
+   */
+  View createView(
+      TableIdentifier identifier,
+      List<ViewRepresentation> representations,
+      Map<String, String> properties);
+
+  /**
+   * Create a view with SQL definition.
+   *
+   * @param identifier a view identifier
+   * @param definition a view definition
+   * @param properties a string map of view properties
+   */
+  default View createView(
+      TableIdentifier identifier,
+      ViewDefinition definition,
+      Map<String, String> properties) {
+    return createView(identifier, Collections.singletonList(definition), properties);
+  }
+
+  /**
+   * Drop a view and delete all data and metadata files.
+   *
+   * @param identifier a view identifier
+   * @return true if the view was dropped, false if the view did not exist
+   */
+  default boolean dropView(TableIdentifier identifier) {
+    return dropView(identifier, true /* drop data and metadata files */);
+  }
+
+  /**
+   * Drop a view; optionally delete data and metadata files.
+   * <p>
+   * If purge is set to true the implementation should delete all data and metadata files.
+   *
+   * @param identifier a view identifier
+   * @param purge      if true, delete all data and metadata files in the view
+   * @return true if the view was dropped, false if the view did not exist
+   */
+  boolean dropView(TableIdentifier identifier, boolean purge);
+
+  /**
+   * 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,37 @@
+/*
+ * 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/View.java

@@ -0,0 +1,74 @@
+/*
+ * 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;
+
+/**
+ * Interface for view definition.
+ */
+public interface View {
+
+  String name();
+
+  /**
+   * 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();
+
+  /**
+   * Update view properties and commit the changes.
+   *
+   * @return a new {@link ViewUpdateProperties}
+   */
+  ViewUpdateProperties updateProperties();
+}

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

@@ -0,0 +1,79 @@
+/*
+ * 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;
+
+public interface ViewDefinition extends ViewRepresentation {
+  @Override
+  default Type type() {
+    return Type.SQL;
+  }
+
+  /**
+   * Returns the view query SQL text.
+   *
+   * @return the view query SQL text
+   */
+  String sql();
+
+  /**
+   * Returns the SQL dialect of the query SQL text.
+   *
+   * @return the SQL dialect of the query SQL text
+   */
+  String dialect();
+
+  /**
+   * Returns the view query output schema.
+   *
+   * @return the view query output schema
+   */
+  Schema schema();
+
+  /**
+   * Returns the default catalog when the view is created.
+   *
+   * @return the default catalog
+   */
+  String defaultCatalog();
+
+  /**
+   * Returns the default namespace when the view is created.
+   *
+   * @return the default namespace
+   */
+  List<String> defaultNamespace();
+
+  /**
+   * Returns the field aliases specified when creating the view.
+   *
+   * @return the field aliases
+   */
+  List<String> fieldAliases();
+
+  /**
+   * Returns the field comments specified when creating the view.
+   *
+   * @return the field comments
+   */
+  List<String> fieldComments();
+}

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

@@ -0,0 +1,38 @@
+/*
+ * 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;
+
+/**
+ * View history entry.
+ * <p>
+ * An entry contains a change to the view state.
+ * At the given timestamp, the current version was set to the given version ID.
+ */
+public interface ViewHistoryEntry {
+  /**
+   * Returns the timestamp in milliseconds of the change
+   */
+  long timestampMillis();
+
+  /**
+   * Returns ID of the new current version
+   */
+  int versionId();
+}