dimas-b commented on code in PR #3616: URL: https://github.com/apache/polaris/pull/3616#discussion_r2771276882
########## polaris-core/src/main/java/org/apache/polaris/core/persistence/metrics/MetricsPersistence.java: ########## @@ -0,0 +1,147 @@ +/* + * 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.polaris.core.persistence.metrics; + +import jakarta.annotation.Nonnull; +import org.apache.polaris.core.persistence.pagination.Page; +import org.apache.polaris.core.persistence.pagination.PageToken; + +/** + * Service Provider Interface (SPI) for persisting Iceberg metrics reports. + * + * <p>This interface enables different persistence backends (JDBC, NoSQL, custom) to implement + * metrics storage in a way appropriate for their storage model, while allowing service code to + * remain backend-agnostic. + * + * <p>Implementations should be idempotent - writing the same reportId twice should have no effect. + * Implementations that don't support metrics persistence can use {@link #NOOP} which silently + * ignores write operations and returns empty pages for queries. + * + * <h3>Dependency Injection</h3> + * + * <p>This interface is designed to be injected via CDI (Contexts and Dependency Injection). The + * deployment module (e.g., {@code polaris-quarkus-service}) should provide a {@code @Produces} + * method that creates the appropriate implementation based on the configured persistence backend. + * + * <p>Example producer: + * + * <pre>{@code + * @Produces + * @RequestScoped + * MetricsPersistence metricsPersistence(RealmContext realmContext, PersistenceBackend backend) { + * if (backend.supportsMetrics()) { + * return backend.createMetricsPersistence(realmContext); + * } + * return MetricsPersistence.NOOP; + * } + * }</pre> + * + * <h3>Multi-Tenancy</h3> + * + * <p>Realm context is not passed in the record objects. Implementations should obtain the realm + * from the CDI-injected {@code RealmContext} at write/query time. This keeps catalog-specific code + * from needing to manage realm concerns directly. + * + * <h3>Pagination</h3> + * + * <p>Query methods use the standard Polaris pagination pattern with {@link PageToken} for requests + * and {@link Page} for responses. This enables: + * + * <ul> + * <li>Backend-specific cursor implementations (RDBMS offset, NoSQL continuation tokens, etc.) + * <li>Consistent pagination interface across all Polaris persistence APIs + * <li>Efficient cursor-based pagination that works with large result sets + * </ul> + * + * <p>The {@link ReportIdToken} provides a reference cursor implementation based on report ID + * (UUID), but backends may use other cursor strategies internally. + * + * @see PageToken + * @see Page + * @see ReportIdToken + */ +public interface MetricsPersistence { Review Comment: Given that this is a new SPI and not fully implemented in all Persistence backends yet, it would be nice to flag it as "experimental" for the sake of clarity... but we do not have a common patterns for this in Polaris 😅 Perhaps we could try `com.google.common.annotations.Beta` in this particular case... as a POC 🤔 WDYT? -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
