feat(labels): Add labels for polaris entities by vignesh-manel · Pull Request #4146 · apache/polaris

vignesh-manel · 2026-04-08T15:55:57Z

Add key-value label support to Catalog entities for organizing and filtering catalogs via the management REST API.

Catalogs can now have optional key-value labels (e.g. env:prod, team:platform) set at creation or updated later
Labels are returned in catalog responses and omitted entirely when not set
UpdateCatalogRequest supports labels (replace) and clearLabels (remove all); the two are mutually exclusive
When labels is omitted on update, existing labels are preserved (non-destructive by default)
Validation enforces: key ≤ 128 chars, value ≤ 256 chars, max 20 labels per catalog

Checklist

🛡️ Don't disclose security issues! (contact security@apache.org)
🔗 Clearly explained why the changes are needed, or linked related issues: Fixes #
🧪 Added/updated tests with good coverage, or manually tested (and explained how)
💡 Added comments for complex logic
🧾 Updated CHANGELOG.md (if needed)
📚 Updated documentation in site/content/in-dev/unreleased (if needed)

snazy · 2026-04-09T10:14:54Z

Thanks a lot for this! I took a brief look over the PR and I do not see anything that's technically worrisome. Sure, there are a few things, but those can be sorted out w/o a lot of hassle.

As this is a new feature, I just wonder whether it's better to go on the dev-mailing-list and start a discussion about this new feature to gather the community's opinion and eventually consensus. WDYT?

Robert

vignesh-manel · 2026-04-09T13:20:33Z

Hi @vignesh-manel !

Thanks a lot for this! I took a brief look over the PR and I do not see anything that's technically worrisome. Sure, there are a few things, but those can be sorted out w/o a lot of hassle.

As this is a new feature, I just wonder whether it's better to go on the dev-mailing-list and start a discussion about this new feature to gather the community's opinion and eventually consensus. WDYT?

Robert

@snazy Thanks for taking a look, I have posted it in dev mail thread: https://lists.apache.org/thread/2ny3gx01dx85b3bzo58zkbddryrjhfr3

dimas-b

The feature LGTM at high level 👍 ... posting a couple of preliminary comments.

dimas-b · 2026-04-10T18:21:17Z

client/python/apache_polaris/cli/command/catalogs.py

@vignesh-manel : If I may suggest moving CLI changes to a separate PR, I think it would simplify review (just different audiences usually review core and CLI changes).

Thanks for the review.
Removed the CLI changes from this PR, will create a different PR for CLI, once this is merged.

dimas-b · 2026-04-10T18:27:05Z

spec/polaris-management-service.yml

          $ref: "#/components/schemas/StorageConfigInfo"
+        labels:
+          type: object
+          x-extra-annotation: "@com.fasterxml.jackson.annotation.JsonInclude(com.fasterxml.jackson.annotation.JsonInclude.Include.NON_EMPTY)"


I believe it is preferable to keep the OpenAPI definition language-neutral.

I believe null values are already not included. Could we represent empty labels as null here?

Alternatively, it might be a good idea to make a separate change to avoid serializing empty values across all endpoints (cf. #1955, https://lists.apache.org/thread/nfboq6yo01x3lw4t3d5gp78f6lgs5ddz).

WDYT?

removed this, now the response will have labels as empty map {} , similar to other collection type attributes in the APIs

dimas-b · 2026-04-10T18:53:22Z

...rc/main/java/org/apache/polaris/service/it/test/PolarisManagementServiceIntegrationTest.java

+    // Update with labels omitted (null) — existing labels must be preserved
+    try (Response response =
+        managementApi
+            .request("v1/catalogs/{name}", Map.of("name", catalogName))


nit: maybe add a helper method to ManagementApi?

added helper method updateCatalogLabels

dimas-b · 2026-04-10T18:54:05Z

...rc/main/java/org/apache/polaris/service/it/test/PolarisManagementServiceIntegrationTest.java

+
+    // Filter by env=prod — only prodCatalog should match
+    try (Response response =
+        managementApi.request("v1/catalogs", Map.of(), Map.of("labelFilter", "env=prod")).get()) {


nit: new helper method in ManagementApi?

added helper method listCatalogsByLabel

dimas-b · 2026-04-10T18:57:14Z

polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisBaseEntity.java

  public static final String EMPTY_MAP_STRING = "{}";

+  /** Internal-property key under which entity labels are stored as a serialized JSON map. */
+  public static final String LABELS_INTERNAL_KEY = "polaris.entity.labels";


protected seems sufficient... Let's not expand the public API surface in "core" unless really necessary.

updated to protected

dimas-b · 2026-04-10T18:58:42Z

polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisBaseEntity.java

+   */
+  @JsonIgnore
+  public Map<String, String> getLabels() {
+    String raw = getInternalPropertiesAsMap().get(LABELS_INTERNAL_KEY);


WDYT about modelling each label as a separate internal property? e.g. polaris.entity.label.env=dev?

dimas-b · 2026-04-10T19:01:07Z

polaris-core/src/main/java/org/apache/polaris/core/entity/PolarisBaseEntity.java

+   * matches every entity.
+   */
+  @JsonIgnore
+  public boolean matchesLabelFilter(@Nonnull Map<String, String> labelFilter) {


nit: how about containsAllLabels? I think it would represent actual behaviour better.

renamed to containsAllLabels

dimas-b · 2026-04-10T19:05:05Z

spec/polaris-management-service.yml

      operationId: listCatalogs
      description: List all catalogs in this polaris service
+      parameters:
+        - name: labelFilter


suggestion: rename to label and use : as the separator. A sample query could be curl -X GET http://.../catalogs?label=env:prod&label=team:eng... I reads nicer from my POV.

thanks for this suggestion, this is better way, updated the code accordingly

dimas-b · 2026-04-10T19:07:32Z

runtime/service/src/main/java/org/apache/polaris/service/admin/PolarisServiceImpl.java

+    }
+    Map<String, String> result = new HashMap<>(labelFilter.size());
+    for (String entry : labelFilter) {
+      int idx = entry.indexOf('=');


We never actually process a label's key/value parts individually, right? Do we need to parse it at all?

github-project-automation bot added this to Basic Kanban Board Apr 8, 2026

github-project-automation bot moved this to PRs In Progress in Basic Kanban Board Apr 8, 2026

vignesh-manel marked this pull request as ready for review April 8, 2026 17:20

dimas-b reviewed Apr 10, 2026

View reviewed changes

vignesh-manel added 4 commits April 11, 2026 16:54

feat(labels): Add labels for polaris entities

fdeeeba

fix CLI CI issues

00f04df

fix tests

8fb2cdf

remove CLI changes

c314e2c

vignesh-manel force-pushed the feature/labels branch from 5f72825 to c314e2c Compare April 11, 2026 11:31

vignesh-manel added 2 commits April 11, 2026 17:58

Address review comments

9d3c1e4

fix test

d182800

Conversation

vignesh-manel commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Checklist

Uh oh!

snazy commented Apr 9, 2026

Uh oh!

vignesh-manel commented Apr 9, 2026

Uh oh!

dimas-b left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vignesh-manel commented Apr 8, 2026 •

edited

Loading