[#12385] feat(api): Add structured Metric View Java API

api/src/main/java/org/apache/gravitino/rel/MetricRepresentation.java

@@ -0,0 +1,108 @@
+/*
+ * 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.gravitino.rel;
+
+import com.google.common.base.Preconditions;
+import java.util.Objects;
+import org.apache.gravitino.annotation.Unstable;
+import org.apache.gravitino.rel.metric.SemanticModel;
+
+/** A structured OSI-compatible {@link Representation} of a Metric View. */
+@Unstable
+public final class MetricRepresentation implements Representation {
+
+  private final SemanticModel semanticModel;
+
+  private MetricRepresentation(SemanticModel semanticModel) {
+    this.semanticModel = semanticModel;
+  }
+
+  /**
+   * Creates a builder for a metric representation.
+   *
+   * @return A new builder.
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
+  @Override
+  public String type() {
+    return Representation.TYPE_METRIC;
+  }
+
+  /**
+   * Returns the structured semantic model.
+   *
+   * @return The semantic model.
+   */
+  public SemanticModel semanticModel() {
+    return semanticModel;
+  }
+
+  @Override
+  public boolean equals(Object other) {
+    if (this == other) {
+      return true;
+    }
+    if (!(other instanceof MetricRepresentation)) {
+      return false;
+    }
+    MetricRepresentation that = (MetricRepresentation) other;
+    return Objects.equals(semanticModel, that.semanticModel);
+  }
+
+  @Override
+  public int hashCode() {
+    return Objects.hash(semanticModel);
+  }
+
+  @Override
+  public String toString() {
+    return "MetricRepresentation{" + "semanticModel=" + semanticModel + '}';
+  }
+
+  /** Builder for {@link MetricRepresentation}. */
+  public static final class Builder {
+    private SemanticModel semanticModel;
+
+    private Builder() {}
+
+    /**
+     * Sets the structured semantic model.
+     *
+     * @param semanticModel The semantic model.
+     * @return This builder.
+     */
+    public Builder withSemanticModel(SemanticModel semanticModel) {
+      this.semanticModel = semanticModel;
+      return this;
+    }
+
+    /**
+     * Builds the metric representation.
+     *
+     * @return The metric representation.
+     */
+    public MetricRepresentation build() {
+      Preconditions.checkArgument(semanticModel != null, "semanticModel must not be null");
+      return new MetricRepresentation(semanticModel);
+    }
+  }
+}

api/src/main/java/org/apache/gravitino/rel/Representation.java

@@ -22,17 +22,19 @@
 
 /**
  * A representation of a view's underlying definition. A view can carry multiple representations
- * targeting different engines or dialects. Currently only the {@link #TYPE_SQL SQL} representation
- * type is supported.
+ * targeting different engines or semantic models.
  */
 @Unstable
 public interface Representation {
 
   /** The representation type for SQL-based view definitions. */
   String TYPE_SQL = "sql";
 
+  /** The representation type for structured metric view definitions. */
+  String TYPE_METRIC = "metric";
+
   /**
-   * Returns the representation type. The only supported value today is {@link #TYPE_SQL}.
+   * Returns the representation type.
    *
    * @return The representation type identifier.
    */

api/src/main/java/org/apache/gravitino/rel/View.java

@@ -28,9 +28,10 @@
 import org.apache.gravitino.tag.SupportsTags;
 
 /**
- * An interface representing a logical view in a {@link Namespace}. A view is a named query whose
- * definition may be expressed in one or more SQL dialects. A catalog implementation with {@link
- * ViewCatalog} should implement this interface.
+ * An interface representing a view in a {@link Namespace}. A logical view is a named query whose
+ * definition may be expressed in one or more SQL dialects. A Metric View carries a structured
+ * {@link MetricRepresentation}. A catalog implementation with {@link ViewCatalog} should implement
+ * this interface.
  */
 @Unstable
 public interface View extends Auditable {
@@ -116,6 +117,21 @@ default Optional<SQLRepresentation> sqlFor(String dialect) {
     return Optional.empty();
   }
 
+  /**
+   * Returns the structured metric representation when this is a Metric View.
+   *
+   * @return The metric representation, or {@link Optional#empty()} for a logical View.
+   */
+  default Optional<MetricRepresentation> metricRepresentation() {
+    Representation[] reps = representations();
+    for (Representation rep : reps) {
+      if (rep instanceof MetricRepresentation) {
+        return Optional.of((MetricRepresentation) rep);
+      }
+    }
+    return Optional.empty();
+  }
+
   /**
    * Returns the properties of the view, or an empty map if no properties are set.
    *

api/src/main/java/org/apache/gravitino/rel/ViewCatalog.java

@@ -18,6 +18,7 @@
  */
 package org.apache.gravitino.rel;
 
+import com.google.common.base.Preconditions;
 import java.util.Map;
 import javax.annotation.Nullable;
 import org.apache.gravitino.NameIdentifier;
@@ -103,6 +104,40 @@ default View createView(
     throw new UnsupportedOperationException("createView is not supported");
   }
 
+  /**
+   * Creates a Metric View through the existing View lifecycle.
+   *
+   * <p>A Metric View has no fixed output columns and contains exactly one {@link
+   * MetricRepresentation}. It does not use a default catalog or schema because each dataset source
+   * is catalog and schema qualified.
+   *
+   * @param ident A view identifier.
+   * @param comment The view comment, or {@code null}.
+   * @param representation The Metric View representation.
+   * @param properties The view properties.
+   * @return The created Metric View.
+   * @throws NoSuchSchemaException If the schema does not exist.
+   * @throws ViewAlreadyExistsException If the view already exists.
+   * @throws IllegalArgumentException If the Metric View constraints are violated.
+   */
+  default View createMetricView(
+      NameIdentifier ident,
+      @Nullable String comment,
+      MetricRepresentation representation,
+      Map<String, String> properties)
+      throws NoSuchSchemaException, ViewAlreadyExistsException {
+    Preconditions.checkArgument(
+        representation != null, "A Metric View must contain one MetricRepresentation");
+    return createView(
+        ident,
+        comment,
+        new Column[0],
+        new Representation[] {representation},
+        null,
+        null,
+        properties);
+  }
+
   /**
    * Apply the {@link ViewChange changes} to a view in the catalog.
    *