Core: Secondary Index metadata handling POC

api/src/main/java/org/apache/iceberg/UpdateLocation.java

@@ -18,10 +18,10 @@
  */
 package org.apache.iceberg;
 
-/** API for setting a table's or view's base location. */
+/** API for setting a table's, view's or index's base location. */
 public interface UpdateLocation extends PendingUpdate<String> {
   /**
-   * Set the table's or view's location.
+   * Set the table's, view's or index's location.
    *
    * @param location a String location
    * @return this for method chaining

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

@@ -0,0 +1,135 @@
+/*
+ * 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.NoSuchIndexException;
+import org.apache.iceberg.exceptions.NoSuchTableException;
+import org.apache.iceberg.index.Index;
+import org.apache.iceberg.index.IndexBuilder;
+import org.apache.iceberg.index.IndexDefinition;
+import org.apache.iceberg.index.IndexType;
+
+/**
+ * A Catalog API for index create, drop, and load operations.
+ *
+ * <p>Indexes are specialized data structures that improve the speed of data retrieval operations on
+ * a database table. An index instance is uniquely identified by its {@link IndexIdentifier}, which
+ * is constructed by combining the {@link TableIdentifier} with the index name.
+ */
+public interface IndexCatalog {
+
+  /**
+   * Return the name for this catalog.
+   *
+   * @return this catalog's name
+   */
+  String name();
+
+  /**
+   * Return a list of index instances for the specified table, filtered to include only those whose
+   * type matches one of the provided types.
+   *
+   * <p>This enables query optimizers to discover the indexes available for a given table. The
+   * returned list is already filtered to include only index types supported by the engine.
+   *
+   * @param tableIdentifier the identifier of the table to list indexes for
+   * @param types the index types to filter by; if empty, returns all indexes
+   * @return a list of index summaries matching the criteria
+   * @throws NoSuchTableException if the table does not exist
+   */
+  List<IndexDefinition> listIndexes(TableIdentifier tableIdentifier, IndexType... types);
+
+  /**
+   * Load an index.
+   *
+   * @param identifier an index identifier
+   * @return instance of {@link Index} implementation referred by the identifier
+   * @throws NoSuchIndexException if the index does not exist
+   */
+  Index loadIndex(IndexIdentifier identifier);
+
+  /**
+   * Check whether an index exists.
+   *
+   * @param identifier an index identifier
+   * @return true if the index exists, false otherwise
+   */
+  default boolean indexExists(IndexIdentifier identifier) {
+    try {
+      loadIndex(identifier);
+      return true;
+    } catch (NoSuchIndexException e) {
+      return false;
+    }
+  }
+
+  /**
+   * Instantiate a builder to create or update an index.
+   *
+   * @param identifier a view identifier
+   * @return a view builder
+   */
+  IndexBuilder buildIndex(IndexIdentifier identifier);
+
+  /**
+   * Drop an index.
+   *
+   * @param identifier an index identifier
+   * @return true if the index was dropped, false if the index did not exist
+   */
+  boolean dropIndex(IndexIdentifier identifier);
+
+  /**
+   * Invalidate cached index metadata from current catalog.
+   *
+   * <p>If the index is already loaded or cached, drop cached data. If the index does not exist or
+   * is not cached, do nothing.
+   *
+   * @param identifier a index identifier
+   */
+  default void invalidateIndex(IndexIdentifier identifier) {}
+
+  /**
+   * Register an index with the catalog if it does not exist.
+   *
+   * @param identifier a index identifier
+   * @param metadataFileLocation the location of a metadata file
+   * @return an Index instance
+   * @throws AlreadyExistsException if an index with the same identifier already exists in the
+   *     catalog.
+   */
+  default Index registerIndex(IndexIdentifier identifier, String metadataFileLocation) {
+    throw new UnsupportedOperationException("Registering index is not supported");
+  }
+
+  /**
+   * Initialize an index catalog given a custom name and a map of catalog properties.
+   *
+   * <p>A custom index 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/catalog/IndexIdentifier.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.io.Serializable;
+import java.util.Arrays;
+import java.util.Objects;
+import org.apache.iceberg.relocated.com.google.common.base.Preconditions;
+
+/**
+ * Identifies an index instance within a catalog.
+ *
+ * <p>An index instance is uniquely identified by combining the {@link TableIdentifier} with the
+ * index name. This ensures that index names are scoped to their respective tables.
+ *
+ * <p>Example: For a table "persons" in the "company" database with an index named
+ * "nationality_index", the resulting IndexIdentifier would be: "company.persons.nationality_index"
+ */
+public class IndexIdentifier implements Serializable {
+
+  private final TableIdentifier tableIdentifier;
+  private final String name;
+
+  private IndexIdentifier(TableIdentifier tableIdentifier, String name) {
+    Preconditions.checkArgument(tableIdentifier != null, "Table identifier cannot be null");
+    Preconditions.checkArgument(
+        name != null && !name.isEmpty(), "Index name cannot be null or empty");
+    this.tableIdentifier = tableIdentifier;
+    this.name = name;
+  }
+
+  /**
+   * Creates an IndexIdentifier from a table identifier and index name.
+   *
+   * @param tableIdentifier the table identifier
+   * @param name the index name
+   * @return an IndexIdentifier
+   */
+  public static IndexIdentifier of(TableIdentifier tableIdentifier, String name) {
+    return new IndexIdentifier(tableIdentifier, name);
+  }
+
+  /**
+   * Creates an IndexIdentifier from a namespace, table name, and index name.
+   *
+   * @param namespace the namespace
+   * @param tableName the table name
+   * @param indexName the index name
+   * @return an IndexIdentifier
+   */
+  public static IndexIdentifier of(Namespace namespace, String tableName, String indexName) {
+    return new IndexIdentifier(TableIdentifier.of(namespace, tableName), indexName);
+  }
+
+  /**
+   * Creates an IndexIdentifier by parsing a string representation.
+   *
+   * <p>The string should be in the format "namespace.table.indexName" where namespace can contain
+   * multiple levels separated by dots.
+   *
+   * @param identifier the string representation of the index identifier
+   * @return an IndexIdentifier
+   * @throws IllegalArgumentException if the identifier string is invalid
+   */
+  public static IndexIdentifier parse(String identifier) {
+    Preconditions.checkArgument(
+        identifier != null && !identifier.isEmpty(),
+        "Cannot parse index identifier: null or empty");
+
+    return IndexIdentifier.of(identifier.split("\\."));
+  }
+
+  public static IndexIdentifier of(String... names) {
+    Preconditions.checkArgument(names != null, "Cannot create index identifier from null array");
+    Preconditions.checkArgument(
+        names.length > 0, "Cannot create index identifier without a index name");
+    Preconditions.checkArgument(
+        names.length > 1, "Cannot create index identifier without a table name");
+
+    return new IndexIdentifier(
+        TableIdentifier.of(Arrays.copyOf(names, names.length - 1)), names[names.length - 1]);
+  }
+
+  /**
+   * Returns the table identifier for this index.
+   *
+   * @return the table identifier
+   */
+  public TableIdentifier tableIdentifier() {
+    return tableIdentifier;
+  }
+
+  /**
+   * Returns the namespace for this index (same as the table's namespace).
+   *
+   * @return the namespace
+   */
+  public Namespace namespace() {
+    return tableIdentifier.namespace();
+  }
+
+  /**
+   * Returns the name of the table this index belongs to.
+   *
+   * @return the table name
+   */
+  public String tableName() {
+    return tableIdentifier.name();
+  }
+
+  /**
+   * Returns the name of this index.
+   *
+   * @return the index name
+   */
+  public String name() {
+    return name;
+  }
+
+  @Override
+  public boolean equals(Object o) {
+    if (this == o) {
+      return true;
+    }
+
+    if (o == null || getClass() != o.getClass()) {
+      return false;
+    }
+
+    IndexIdentifier that = (IndexIdentifier) o;
+    return tableIdentifier.equals(that.tableIdentifier) && name.equals(that.name);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(tableIdentifier, name);
+  }
+
+  @Override
+  public String toString() {
+    return tableIdentifier.toString() + "." + name;
+  }
+}