obelix74 commented on code in PR #3616: URL: https://github.com/apache/polaris/pull/3616#discussion_r2766749220
########## polaris-core/src/main/java/org/apache/polaris/core/persistence/metrics/MetricsQueryCriteria.java: ########## @@ -0,0 +1,164 @@ +/* + * 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 java.time.Instant; +import java.util.List; +import java.util.Map; +import java.util.Optional; +import java.util.OptionalLong; +import org.apache.polaris.immutables.PolarisImmutable; + +/** + * Query criteria for retrieving metrics reports. + * + * <p>This class defines the filter parameters for metrics queries. Pagination is handled separately + * via {@link org.apache.polaris.core.persistence.pagination.PageToken}, which is passed as a + * separate parameter to query methods. This separation of concerns allows: + * + * <ul> + * <li>Different backends to implement pagination in their optimal way + * <li>Cursor-based pagination that works with both RDBMS and NoSQL backends + * <li>Reuse of the existing Polaris pagination infrastructure + * </ul> + * + * <h3>Supported Query Patterns</h3> + * + * <table> + * <tr><th>Pattern</th><th>Fields Used</th><th>Index Required</th></tr> + * <tr><td>By Table + Time</td><td>catalogId, tableId, startTime, endTime</td><td>Yes (OSS)</td></tr> + * <tr><td>By Time Only</td><td>startTime, endTime</td><td>Partial (timestamp index)</td></tr> + * </table> + * + * <p>Additional query patterns (e.g., by trace ID) can be implemented by persistence backends using + * the {@link #metadata()} filter map. Client-provided correlation data should be stored in the + * metrics record's metadata map and can be filtered using the metadata criteria. + * + * <h3>Pagination</h3> + * + * <p>Pagination is handled via the {@link org.apache.polaris.core.persistence.pagination.PageToken} + * passed to query methods. The token contains: + * + * <ul> + * <li>{@code pageSize()} - Maximum number of results to return + * <li>{@code value()} - Optional cursor token (e.g., {@link ReportIdToken}) for continuation + * </ul> + * + * <p>Query results are returned as {@link org.apache.polaris.core.persistence.pagination.Page} + * which includes an encoded token for fetching the next page. + * + * @see org.apache.polaris.core.persistence.pagination.PageToken + * @see org.apache.polaris.core.persistence.pagination.Page + * @see ReportIdToken + */ +@PolarisImmutable +public interface MetricsQueryCriteria { + + // === Table Identification (optional) === + + /** + * Catalog ID to filter by. + * + * <p>This is the internal catalog entity ID. Callers should resolve catalog names to IDs before + * querying, as catalog names can change over time. + */ + OptionalLong catalogId(); + + /** + * Namespace to filter by. + * + * <p>The namespace is represented as a list of levels to avoid ambiguity when segments contain + * dots. An empty list means no namespace filter is applied. + */ + List<String> namespace(); Review Comment: Makes sense. I've removed namespace() from MetricsQueryCriteria. Queries are now by catalogId + tableId only (both required). If users want to query by namespace, the service layer should resolve namespace → table IDs using the current catalog state, then query by those IDs. I've kept namespace in MetricsRecordIdentity for storage/display purposes - it's useful context when showing metrics to users, even though we don't query by it. -- 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]
