This is an automated email from the ASF dual-hosted git repository.
blue pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iceberg.git
The following commit(s) were added to refs/heads/master by this push:
new b2f4694b4d API: Add view interfaces (#4925)
b2f4694b4d is described below
commit b2f4694b4d15c2e065ac2739d9d22bb7edd3b537
Author: John Zhuge <[email protected]>
AuthorDate: Mon Dec 5 09:58:23 2022 -0800
API: Add view interfaces (#4925)
Co-authored-by: [email protected]
Co-authored-by: [email protected]
---
.../org/apache/iceberg/catalog/ViewCatalog.java | 119 ++++++++++++++++++
.../iceberg/exceptions/NoSuchViewException.java | 34 ++++++
.../apache/iceberg/view/SQLViewRepresentation.java | 52 ++++++++
.../apache/iceberg/view/UpdateViewProperties.java | 52 ++++++++
.../main/java/org/apache/iceberg/view/View.java | 86 +++++++++++++
.../java/org/apache/iceberg/view/ViewBuilder.java | 134 +++++++++++++++++++++
.../org/apache/iceberg/view/ViewHistoryEntry.java | 33 +++++
.../apache/iceberg/view/ViewRepresentation.java | 38 ++++++
.../java/org/apache/iceberg/view/ViewVersion.java | 61 ++++++++++
9 files changed, 609 insertions(+)
diff --git a/api/src/main/java/org/apache/iceberg/catalog/ViewCatalog.java
b/api/src/main/java/org/apache/iceberg/catalog/ViewCatalog.java
new file mode 100644
index 0000000000..2a89466ca3
--- /dev/null
+++ b/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) {}
+}
diff --git
a/api/src/main/java/org/apache/iceberg/exceptions/NoSuchViewException.java
b/api/src/main/java/org/apache/iceberg/exceptions/NoSuchViewException.java
new file mode 100644
index 0000000000..cf2b20a609
--- /dev/null
+++ b/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);
+ }
+}
diff --git
a/api/src/main/java/org/apache/iceberg/view/SQLViewRepresentation.java
b/api/src/main/java/org/apache/iceberg/view/SQLViewRepresentation.java
new file mode 100644
index 0000000000..5fbd1d909e
--- /dev/null
+++ b/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();
+}
diff --git
a/api/src/main/java/org/apache/iceberg/view/UpdateViewProperties.java
b/api/src/main/java/org/apache/iceberg/view/UpdateViewProperties.java
new file mode 100644
index 0000000000..444af0f247
--- /dev/null
+++ b/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);
+}
diff --git a/api/src/main/java/org/apache/iceberg/view/View.java
b/api/src/main/java/org/apache/iceberg/view/View.java
new file mode 100644
index 0000000000..0f4d1cc9c0
--- /dev/null
+++ b/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();
+}
diff --git a/api/src/main/java/org/apache/iceberg/view/ViewBuilder.java
b/api/src/main/java/org/apache/iceberg/view/ViewBuilder.java
new file mode 100644
index 0000000000..57f8a97086
--- /dev/null
+++ b/api/src/main/java/org/apache/iceberg/view/ViewBuilder.java
@@ -0,0 +1,134 @@
+/*
+ * 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;
+import org.apache.iceberg.catalog.Namespace;
+import org.apache.iceberg.catalog.ViewCatalog;
+
+/**
+ * A builder used to create or replace a SQL {@link View}.
+ *
+ * <p>Call {@link ViewCatalog#buildView} to create a new builder.
+ */
+public interface ViewBuilder {
+ /**
+ * Set the view schema.
+ *
+ * @param schema view schema
+ * @return this for method chaining
+ */
+ ViewBuilder withSchema(Schema schema);
+
+ /**
+ * Set the view query.
+ *
+ * @param query view query
+ * @return this for method chaining
+ */
+ ViewBuilder withQuery(String query);
+
+ /**
+ * Set the view SQL dialect.
+ *
+ * @param dialect view SQL dialect
+ * @return this for method chaining
+ */
+ ViewBuilder withDialect(String dialect);
+
+ /**
+ * Set the view default catalog.
+ *
+ * @param defaultCatalog view default catalog
+ * @return this for method chaining
+ */
+ ViewBuilder withDefaultCatalog(String defaultCatalog);
+
+ /**
+ * Set the view default namespace.
+ *
+ * @param defaultNamespace view default namespace
+ * @return this for method chaining
+ */
+ ViewBuilder withDefaultNamespace(Namespace defaultNamespace);
+
+ /**
+ * Set the view query column names.
+ *
+ * @param queryColumnNames view query column names
+ * @return this for method chaining
+ */
+ ViewBuilder withQueryColumnNames(List<String> queryColumnNames);
+
+ /**
+ * Set the view field aliases.
+ *
+ * @param fieldAliases view field aliases
+ * @return this for method chaining
+ */
+ ViewBuilder withFieldAliases(List<String> fieldAliases);
+
+ /**
+ * Set the view field comments.
+ *
+ * @param fieldComments view field comments
+ * @return this for method chaining
+ */
+ ViewBuilder withFieldComments(List<String> fieldComments);
+
+ /**
+ * Add key/value properties to the view.
+ *
+ * @param properties key/value properties
+ * @return this for method chaining
+ */
+ ViewBuilder withProperties(Map<String, String> properties);
+
+ /**
+ * Add a key/value property to the view.
+ *
+ * @param key a key
+ * @param value a value
+ * @return this for method chaining
+ */
+ ViewBuilder withProperty(String key, String value);
+
+ /**
+ * Create the view.
+ *
+ * @return the view created
+ */
+ View create();
+
+ /**
+ * Replace the view.
+ *
+ * @return the {@link View} replaced
+ */
+ View replace();
+
+ /**
+ * Create or replace the view.
+ *
+ * @return the {@link View} created or replaced
+ */
+ View createOrReplace();
+}
diff --git a/api/src/main/java/org/apache/iceberg/view/ViewHistoryEntry.java
b/api/src/main/java/org/apache/iceberg/view/ViewHistoryEntry.java
new file mode 100644
index 0000000000..2840560655
--- /dev/null
+++ b/api/src/main/java/org/apache/iceberg/view/ViewHistoryEntry.java
@@ -0,0 +1,33 @@
+/*
+ * 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 {
+ /** Return the timestamp in milliseconds of the change */
+ long timestampMillis();
+
+ /** Return ID of the new current version */
+ int versionId();
+}
diff --git a/api/src/main/java/org/apache/iceberg/view/ViewRepresentation.java
b/api/src/main/java/org/apache/iceberg/view/ViewRepresentation.java
new file mode 100644
index 0000000000..88e141ef56
--- /dev/null
+++ b/api/src/main/java/org/apache/iceberg/view/ViewRepresentation.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;
+
+import java.util.Locale;
+
+public interface ViewRepresentation {
+
+ enum Type {
+ SQL;
+
+ public static Type fromString(String typeName) {
+ return valueOf(typeName.toUpperCase(Locale.ENGLISH));
+ }
+
+ public String typeName() {
+ return name().toLowerCase(Locale.ENGLISH);
+ }
+ }
+
+ Type type();
+}
diff --git a/api/src/main/java/org/apache/iceberg/view/ViewVersion.java
b/api/src/main/java/org/apache/iceberg/view/ViewVersion.java
new file mode 100644
index 0000000000..d5459389df
--- /dev/null
+++ b/api/src/main/java/org/apache/iceberg/view/ViewVersion.java
@@ -0,0 +1,61 @@
+/*
+ * 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;
+
+/**
+ * A version of the view at a point in time.
+ *
+ * <p>A version consists of a view metadata file.
+ *
+ * <p>Versions are created by view operations, like Create and Replace.
+ */
+public interface ViewVersion {
+
+ /** Return this version's id. Version ids are monotonically increasing */
+ int versionId();
+
+ /**
+ * Return this version's timestamp.
+ *
+ * <p>This timestamp is the same as those produced by {@link
System#currentTimeMillis()}.
+ *
+ * @return a long timestamp in milliseconds
+ */
+ long timestampMillis();
+
+ /**
+ * Return the version summary such as the name of the operation that created
that version of the
+ * view
+ *
+ * @return a version summary
+ */
+ Map<String, String> summary();
+
+ /**
+ * Return the list of other view representations.
+ *
+ * <p>May contain SQL view representations for other dialects.
+ *
+ * @return the list of view representations
+ */
+ List<ViewRepresentation> representations();
+}
