apache · snazy · Jul 28, 2025 · Jul 24, 2025
diff --git a/integration-tests/src/main/java/org/apache/polaris/service/it/env/ManagementApi.java b/integration-tests/src/main/java/org/apache/polaris/service/it/env/ManagementApi.java
@@ -46,6 +46,7 @@
 import org.apache.polaris.core.admin.model.PrincipalWithCredentials;
 import org.apache.polaris.core.admin.model.Principals;
 import org.apache.polaris.core.admin.model.UpdateCatalogRequest;
+import org.apache.polaris.core.entity.PolarisEntityConstants;
 
 /**
  * A simple, non-exhaustive set of helper methods for accessing the Polaris Management API.
@@ -287,7 +288,7 @@ public void deletePrincipalRole(PrincipalRole role) {
 
   public void dropCatalog(String catalogName) {
     listCatalogRoles(catalogName).stream()
-        .filter(cr -> !cr.getName().equals("catalog_admin"))
+        .filter(cr -> !cr.getName().equals(PolarisEntityConstants.getNameOfCatalogAdminRole()))
         .forEach(role -> deleteCatalogRole(catalogName, role));
 
     deleteCatalog(catalogName);

diff --git a/...main/java/org/apache/polaris/service/it/test/PolarisManagementServiceIntegrationTest.java b/...main/java/org/apache/polaris/service/it/test/PolarisManagementServiceIntegrationTest.java
@@ -1684,7 +1684,9 @@ public void testCatalogAdminGrantAndRevokeCatalogRoles() {
             .build();
     managementApi.createCatalog(catalog);
 
-    CatalogRole catalogAdminRole = managementApi.getCatalogRole(catalogName, "catalog_admin");
+    CatalogRole catalogAdminRole =
+        managementApi.getCatalogRole(
+            catalogName, PolarisEntityConstants.getNameOfCatalogAdminRole());
     managementApi.grantCatalogRoleToPrincipalRole(principalRoleName, catalogName, catalogAdminRole);
 
     PrincipalWithCredentials catalogAdminPrincipal =
@@ -1771,7 +1773,9 @@ public void testServiceAdminCanTransferCatalogAdmin() {
             .build();
     managementApi.createCatalog(catalog);
 
-    CatalogRole catalogAdminRole = managementApi.getCatalogRole(catalogName, "catalog_admin");
+    CatalogRole catalogAdminRole =
+        managementApi.getCatalogRole(
+            catalogName, PolarisEntityConstants.getNameOfCatalogAdminRole());
     managementApi.grantCatalogRoleToPrincipalRole(principalRoleName, catalogName, catalogAdminRole);
 
     PrincipalWithCredentials catalogAdminPrincipal =
@@ -1813,7 +1817,10 @@ public void testServiceAdminCanTransferCatalogAdmin() {
       // grant the admin role back to service_admin so that cleanup can happen
       client
           .managementApi(catalogAdminToken)
-          .grantCatalogRoleToPrincipalRole("service_admin", catalogName, catalogAdminRole);
+          .grantCatalogRoleToPrincipalRole(
+              PolarisEntityConstants.getNameOfPrincipalServiceAdminRole(),
+              catalogName,
+              catalogAdminRole);
     }
   }
 
@@ -1856,7 +1863,9 @@ public void testCatalogAdminGrantAndRevokeCatalogRolesFromWrongCatalog() {
     managementApi.createCatalogRole(catalogName2, catalogRoleName);
 
     // Get the catalog admin role from the *first* catalog and grant that role to the principal role
-    CatalogRole catalogAdminRole = managementApi.getCatalogRole(catalogName, "catalog_admin");
+    CatalogRole catalogAdminRole =
+        managementApi.getCatalogRole(
+            catalogName, PolarisEntityConstants.getNameOfCatalogAdminRole());
     managementApi.grantCatalogRoleToPrincipalRole(principalRoleName, catalogName, catalogAdminRole);
 
     // Create a principal and grant the principal role to it

diff --git a/...main/java/org/apache/polaris/persistence/relational/jdbc/JdbcMetaStoreManagerFactory.java b/...main/java/org/apache/polaris/persistence/relational/jdbc/JdbcMetaStoreManagerFactory.java
@@ -26,6 +26,7 @@
 import java.sql.SQLException;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 import java.util.function.Supplier;
 import javax.sql.DataSource;
 import org.apache.polaris.core.PolarisCallContext;
@@ -34,10 +35,8 @@
 import org.apache.polaris.core.config.RealmConfig;
 import org.apache.polaris.core.context.CallContext;
 import org.apache.polaris.core.context.RealmContext;
-import org.apache.polaris.core.entity.PolarisEntity;
 import org.apache.polaris.core.entity.PolarisEntityConstants;
-import org.apache.polaris.core.entity.PolarisEntitySubType;
-import org.apache.polaris.core.entity.PolarisEntityType;
+import org.apache.polaris.core.entity.PrincipalEntity;
 import org.apache.polaris.core.persistence.AtomicOperationMetaStoreManager;
 import org.apache.polaris.core.persistence.BasePersistence;
 import org.apache.polaris.core.persistence.MetaStoreManagerFactory;
@@ -51,7 +50,6 @@
 import org.apache.polaris.core.persistence.cache.EntityCache;
 import org.apache.polaris.core.persistence.cache.InMemoryEntityCache;
 import org.apache.polaris.core.persistence.dao.entity.BaseResult;
-import org.apache.polaris.core.persistence.dao.entity.EntityResult;
 import org.apache.polaris.core.persistence.dao.entity.PrincipalSecretsResult;
 import org.apache.polaris.core.storage.PolarisStorageIntegrationProvider;
 import org.slf4j.Logger;
@@ -238,14 +236,9 @@ private PrincipalSecretsResult bootstrapServiceAndCreatePolarisPrincipalForRealm
       CallContext.setCurrentContext(polarisContext);
     }
 
-    EntityResult preliminaryRootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
-    if (preliminaryRootPrincipalLookup.isSuccess()) {
+    Optional<PrincipalEntity> preliminaryRootPrincipal =
+        metaStoreManager.findRootPrincipal(polarisContext);
+    if (preliminaryRootPrincipal.isPresent()) {
       String overrideMessage =
           "It appears this metastore manager has already been bootstrapped. "
               + "To continue bootstrapping, please first purge the metastore with the `purge` command.";
@@ -255,16 +248,11 @@ private PrincipalSecretsResult bootstrapServiceAndCreatePolarisPrincipalForRealm
 
     metaStoreManager.bootstrapPolarisService(polarisContext);
 
-    EntityResult rootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
+    PrincipalEntity rootPrincipal =
+        metaStoreManager.findRootPrincipal(polarisContext).orElseThrow();
     return metaStoreManager.loadPrincipalSecrets(
         polarisContext,
-        PolarisEntity.of(rootPrincipalLookup.getEntity())
+        rootPrincipal
             .getInternalPropertiesAsMap()
             .get(PolarisEntityConstants.getClientIdPropertyName()));
   }
@@ -286,15 +274,8 @@ private void checkPolarisServiceBootstrappedForRealm(RealmContext realmContext)
       CallContext.setCurrentContext(polarisContext);
     }
 
-    EntityResult rootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
-
-    if (!rootPrincipalLookup.isSuccess()) {
+    Optional<PrincipalEntity> rootPrincipal = metaStoreManager.findRootPrincipal(polarisContext);
+    if (rootPrincipal.isEmpty()) {
       LOGGER.error(
           "\n\n Realm {} is not bootstrapped, could not load root principal. Please run Bootstrap command. \n\n",
           realmContext.getRealmIdentifier());

diff --git a/...rc/main/java/org/apache/polaris/core/persistence/LocalPolarisMetaStoreManagerFactory.java b/...rc/main/java/org/apache/polaris/core/persistence/LocalPolarisMetaStoreManagerFactory.java
@@ -22,22 +22,20 @@
 import jakarta.annotation.Nullable;
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Optional;
 import java.util.function.Supplier;
 import org.apache.polaris.core.PolarisCallContext;
 import org.apache.polaris.core.PolarisDefaultDiagServiceImpl;
 import org.apache.polaris.core.PolarisDiagnostics;
 import org.apache.polaris.core.config.RealmConfig;
 import org.apache.polaris.core.context.CallContext;
 import org.apache.polaris.core.context.RealmContext;
-import org.apache.polaris.core.entity.PolarisEntity;
 import org.apache.polaris.core.entity.PolarisEntityConstants;
-import org.apache.polaris.core.entity.PolarisEntitySubType;
-import org.apache.polaris.core.entity.PolarisEntityType;
+import org.apache.polaris.core.entity.PrincipalEntity;
 import org.apache.polaris.core.persistence.bootstrap.RootCredentialsSet;
 import org.apache.polaris.core.persistence.cache.EntityCache;
 import org.apache.polaris.core.persistence.cache.InMemoryEntityCache;
 import org.apache.polaris.core.persistence.dao.entity.BaseResult;
-import org.apache.polaris.core.persistence.dao.entity.EntityResult;
 import org.apache.polaris.core.persistence.dao.entity.PrincipalSecretsResult;
 import org.apache.polaris.core.persistence.transactional.TransactionalMetaStoreManagerImpl;
 import org.apache.polaris.core.persistence.transactional.TransactionalPersistence;
@@ -192,14 +190,9 @@ private PrincipalSecretsResult bootstrapServiceAndCreatePolarisPrincipalForRealm
       CallContext.setCurrentContext(polarisContext);
     }
 
-    EntityResult preliminaryRootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
-    if (preliminaryRootPrincipalLookup.isSuccess()) {
+    Optional<PrincipalEntity> preliminaryRootPrincipal =
+        metaStoreManager.findRootPrincipal(polarisContext);
+    if (preliminaryRootPrincipal.isPresent()) {
       String overrideMessage =
           "It appears this metastore manager has already been bootstrapped. "
               + "To continue bootstrapping, please first purge the metastore with the `purge` command.";
@@ -209,16 +202,11 @@ private PrincipalSecretsResult bootstrapServiceAndCreatePolarisPrincipalForRealm
 
     metaStoreManager.bootstrapPolarisService(polarisContext);
 
-    EntityResult rootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
+    PrincipalEntity rootPrincipal =
+        metaStoreManager.findRootPrincipal(polarisContext).orElseThrow();
     return metaStoreManager.loadPrincipalSecrets(
         polarisContext,
-        PolarisEntity.of(rootPrincipalLookup.getEntity())
+        rootPrincipal
             .getInternalPropertiesAsMap()
             .get(PolarisEntityConstants.getClientIdPropertyName()));
   }
@@ -240,15 +228,8 @@ private void checkPolarisServiceBootstrappedForRealm(RealmContext realmContext)
       CallContext.setCurrentContext(polarisContext);
     }
 
-    EntityResult rootPrincipalLookup =
-        metaStoreManager.readEntityByName(
-            polarisContext,
-            null,
-            PolarisEntityType.PRINCIPAL,
-            PolarisEntitySubType.NULL_SUBTYPE,
-            PolarisEntityConstants.getRootPrincipalName());
-
-    if (!rootPrincipalLookup.isSuccess()) {
+    Optional<PrincipalEntity> rootPrincipal = metaStoreManager.findRootPrincipal(polarisContext);
+    if (rootPrincipal.isEmpty()) {
       LOGGER.error(
           "\n\n Realm {} is not bootstrapped, could not load root principal. Please run Bootstrap command. \n\n",
           realmContext.getRealmIdentifier());

diff --git a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisEntityManager.java b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisEntityManager.java
@@ -25,7 +25,6 @@
 import org.apache.polaris.core.context.CallContext;
 import org.apache.polaris.core.entity.PolarisEntity;
 import org.apache.polaris.core.entity.PolarisEntityConstants;
-import org.apache.polaris.core.entity.PolarisEntitySubType;
 import org.apache.polaris.core.entity.PolarisEntityType;
 import org.apache.polaris.core.entity.PolarisGrantRecord;
 import org.apache.polaris.core.entity.PolarisPrivilege;
@@ -82,15 +81,11 @@ private synchronized ResolvedPolarisEntity getSimulatedResolvedRootContainerEnti
       // root entity, then we must actually create a representation of this root entity in the
       // entity store itself.
       PolarisEntity serviceAdminPrincipalRole =
-          PolarisEntity.of(
-              metaStoreManager
-                  .readEntityByName(
-                      callContext.getPolarisCallContext(),
-                      null,
-                      PolarisEntityType.PRINCIPAL_ROLE,
-                      PolarisEntitySubType.NULL_SUBTYPE,
-                      PolarisEntityConstants.getNameOfPrincipalServiceAdminRole())
-                  .getEntity());
+          metaStoreManager
+              .findPrincipalRoleByName(
+                  callContext.getPolarisCallContext(),
+                  PolarisEntityConstants.getNameOfPrincipalServiceAdminRole())
+              .orElse(null);
       if (serviceAdminPrincipalRole == null) {
         throw new IllegalStateException("Failed to resolve service_admin PrincipalRole");
       }

diff --git a/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java b/polaris-core/src/main/java/org/apache/polaris/core/persistence/PolarisMetaStoreManager.java
@@ -29,10 +29,13 @@
 import org.apache.polaris.core.entity.LocationBasedEntity;
 import org.apache.polaris.core.entity.PolarisBaseEntity;
 import org.apache.polaris.core.entity.PolarisEntity;
+import org.apache.polaris.core.entity.PolarisEntityConstants;
 import org.apache.polaris.core.entity.PolarisEntityCore;
 import org.apache.polaris.core.entity.PolarisEntityId;
 import org.apache.polaris.core.entity.PolarisEntitySubType;
 import org.apache.polaris.core.entity.PolarisEntityType;
+import org.apache.polaris.core.entity.PrincipalEntity;
+import org.apache.polaris.core.entity.PrincipalRoleEntity;
 import org.apache.polaris.core.persistence.dao.entity.BaseResult;
 import org.apache.polaris.core.persistence.dao.entity.ChangeTrackingResult;
 import org.apache.polaris.core.persistence.dao.entity.CreateCatalogResult;
@@ -418,4 +421,38 @@ Optional<Optional<String>> hasOverlappingSiblings(
   default boolean requiresEntityReload() {
     return true;
   }
+
+  default Optional<PrincipalEntity> findRootPrincipal(PolarisCallContext polarisCallContext) {
+    return findPrincipalByName(polarisCallContext, PolarisEntityConstants.getRootPrincipalName());
+  }
+
+  default Optional<PrincipalEntity> findPrincipalByName(
+      PolarisCallContext polarisCallContext, String principalName) {
+    EntityResult entityResult =
+        readEntityByName(
+            polarisCallContext,
+            null,
+            PolarisEntityType.PRINCIPAL,
+            PolarisEntitySubType.NULL_SUBTYPE,
+            principalName);
+    if (!entityResult.isSuccess()) {
+      return Optional.empty();
+    }
+    return Optional.of(entityResult.getEntity()).map(PrincipalEntity::of);
+  }
+
+  default Optional<PrincipalRoleEntity> findPrincipalRoleByName(
+      PolarisCallContext polarisCallContext, String principalRoleName) {
+    EntityResult entityResult =
+        readEntityByName(
+            polarisCallContext,
+            null,
+            PolarisEntityType.PRINCIPAL_ROLE,
+            PolarisEntitySubType.NULL_SUBTYPE,
+            principalRoleName);
+    if (!entityResult.isSuccess()) {
+      return Optional.empty();
+    }
+    return Optional.of(entityResult.getEntity()).map(PrincipalRoleEntity::of);
+  }
 }
diff --git a/polaris-core/src/testFixtures/java/org/apache/polaris/core/persistence/BaseResolverTest.java b/polaris-core/src/testFixtures/java/org/apache/polaris/core/persistence/BaseResolverTest.java
@@ -41,7 +41,6 @@
 import org.apache.polaris.core.entity.PrincipalEntity;
 import org.apache.polaris.core.entity.PrincipalRoleEntity;
 import org.apache.polaris.core.persistence.cache.InMemoryEntityCache;
-import org.apache.polaris.core.persistence.dao.entity.EntityResult;
 import org.apache.polaris.core.persistence.dao.entity.ResolvedEntityResult;
 import org.apache.polaris.core.persistence.resolver.Resolver;
 import org.apache.polaris.core.persistence.resolver.ResolverPath;
@@ -477,17 +476,10 @@ private Resolver allocateResolver(
                 scopes ->
                     scopes.stream()
                         .map(
-                            role ->
-                                metaStoreManager()
-                                    .readEntityByName(
-                                        callCtx(),
-                                        null,
-                                        PolarisEntityType.PRINCIPAL_ROLE,
-                                        PolarisEntitySubType.NULL_SUBTYPE,
-                                        role))
-                        .filter(EntityResult::isSuccess)
-                        .map(EntityResult::getEntity)
-                        .map(PrincipalRoleEntity::of)
+                            roleName ->
+                                metaStoreManager().findPrincipalRoleByName(callCtx(), roleName))
+                        .filter(Optional::isPresent)
+                        .map(Optional::get)
                         .collect(Collectors.toList()));
     AuthenticatedPolarisPrincipal authenticatedPrincipal =
         new AuthenticatedPolarisPrincipal(
@@ -774,16 +766,10 @@ private Resolver resolveDriver(
       // the principal does not exist, check that this is the case
       if (principalName != null) {
         // see if the principal exists
-        EntityResult result =
-            metaStoreManager()
-                .readEntityByName(
-                    callCtx(),
-                    null,
-                    PolarisEntityType.PRINCIPAL,
-                    PolarisEntitySubType.NULL_SUBTYPE,
-                    principalName);
+        Optional<PrincipalEntity> principal =
+            metaStoreManager().findPrincipalByName(callCtx(), principalName);
         // if found, ensure properly resolved
-        if (result.getEntity() != null) {
+        if (principal.isPresent()) {
           // the principal exist, check that this is the case
           this.ensureResolved(
               resolver.getResolvedEntity(PolarisEntityType.PRINCIPAL, principalName),

diff --git a/...service/src/test/java/org/apache/polaris/service/quarkus/admin/ManagementServiceTest.java b/...service/src/test/java/org/apache/polaris/service/quarkus/admin/ManagementServiceTest.java
@@ -209,7 +209,10 @@ private PolarisAdminService setupPolarisAdminService(
           @Override
           public Principal getUserPrincipal() {
             return new AuthenticatedPolarisPrincipal(
-                new PrincipalEntity.Builder().setName("root").build(), Set.of("service_admin"));
+                new PrincipalEntity.Builder()
+                    .setName(PolarisEntityConstants.getRootPrincipalName())
+                    .build(),
+                Set.of(PolarisEntityConstants.getNameOfPrincipalServiceAdminRole()));
           }
 
           @Override