You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@polaris.apache.org by yu...@apache.org on 2026/07/07 16:48:00 UTC
(polaris) branch main updated: Mark OSI semantic-model API as beta (#4983)
This is an automated email from the ASF dual-hosted git repository.
flyrain pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/polaris.git
The following commit(s) were added to refs/heads/main by this push:
new 1802bb0d67 Mark OSI semantic-model API as beta (#4983)
1802bb0d67 is described below
commit 1802bb0d675a3cff9888180bf2241ac2aae0f6ce
Author: Yufei Gu <yu...@apache.org>
AuthorDate: Tue Jul 7 09:47:56 2026 -0700
Mark OSI semantic-model API as beta (#4983)
---
.../polaris/core/config/FeatureConfiguration.java | 8 ++++--
.../config-sections/flags-polaris_features.md | 2 +-
spec/polaris-catalog-apis/semantic-models-api.yaml | 31 +++++++++++++++++-----
3 files changed, 31 insertions(+), 10 deletions(-)
diff --git a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java
index 1affe451c9..596286ec8f 100644
--- a/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java
+++ b/polaris-core/src/main/java/org/apache/polaris/core/config/FeatureConfiguration.java
@@ -508,8 +508,12 @@ public class FeatureConfiguration<T> extends PolarisConfiguration<T> {
public static final FeatureConfiguration<Boolean> ENABLE_SEMANTIC_MODELS =
PolarisConfiguration.<Boolean>builder()
.key("ENABLE_SEMANTIC_MODELS")
- .description("If true, the semantic-model (OSI) endpoints are enabled")
- .defaultValue(false) // keep it to false until the implementation is done
+ .description(
+ "If true, the semantic-model (Apache Ossie) endpoints are enabled. This is a beta feature: "
+ + "the API is under active development and may change in a backward-incompatible "
+ + "way. It is disabled by default; enable it with caution and report any issues "
+ + "encountered.")
+ .defaultValue(false) // beta feature, keep it off by default
.buildFeatureConfiguration();
public static final FeatureConfiguration<List<String>> SUPPORTED_CATALOG_CONNECTION_TYPES =
diff --git a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md
index 3c2309ed7b..43ad35e70b 100644
--- a/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md
+++ b/site/content/in-dev/unreleased/configuration/config-sections/flags-polaris_features.md
@@ -309,7 +309,7 @@ If true, the policy-store endpoints are enabled
##### `polaris.features."ENABLE_SEMANTIC_MODELS"`
-If true, the semantic-model (OSI) endpoints are enabled
+If true, the semantic-model (Apache Ossie) endpoints are enabled. This is a beta feature: the API is under active development and may change in a backward-incompatible way. It is disabled by default; enable it with caution and report any issues encountered.
- **Type:** `Boolean`
- **Default:** `false`
diff --git a/spec/polaris-catalog-apis/semantic-models-api.yaml b/spec/polaris-catalog-apis/semantic-models-api.yaml
index 2d4ba5f9a3..af4fc199de 100644
--- a/spec/polaris-catalog-apis/semantic-models-api.yaml
+++ b/spec/polaris-catalog-apis/semantic-models-api.yaml
@@ -31,9 +31,12 @@ paths:
summary: Create a semantic model in the given namespace
operationId: createSemanticModel
description: |
+ **Beta:** The semantic-model (Apache Ossie) API is under active development and may change in a
+ backward-incompatible way.
+
Creates a semantic model in the specified namespace.
- A semantic model is an Open Semantic Interchange (OSI) document describing
+ A semantic model is an Apache Ossie document describing
datasets, fields, relationships, metrics, and AI context for a logical analytics surface above
physical tables and views.
@@ -83,6 +86,9 @@ paths:
summary: List semantic models in the given namespace
operationId: listSemanticModels
description: |
+ **Beta:** The semantic-model (Apache Ossie) API is under active development and may change in a
+ backward-incompatible way.
+
List semantic-model identifiers under a namespace.
parameters:
- $ref: '../iceberg-rest-catalog-open-api.yaml#/components/parameters/page-token'
@@ -122,7 +128,11 @@ paths:
- Semantic Model API
summary: Load a semantic model
operationId: loadSemanticModel
- description: Load a semantic model from the catalog.
+ description: |
+ **Beta:** The semantic-model (Apache Ossie) API is under active development and may change in a
+ backward-incompatible way.
+
+ Load a semantic model from the catalog.
responses:
200:
$ref: '#/components/responses/LoadSemanticModelResponse'
@@ -152,6 +162,9 @@ paths:
summary: Update a semantic model
operationId: updateSemanticModel
description: |
+ **Beta:** The semantic-model (Apache Ossie) API is under active development and may change in a
+ backward-incompatible way.
+
Replace a semantic model's document with a new one.
Upon a successful update, the model's entity-version changes and the new value is returned.
@@ -205,7 +218,11 @@ paths:
- Semantic Model API
summary: Drop a semantic model from the catalog
operationId: dropSemanticModel
- description: Remove a semantic model from the catalog.
+ description: |
+ **Beta:** The semantic-model (Apache Ossie) API is under active development and may change in a
+ backward-incompatible way.
+
+ Remove a semantic model from the catalog.
responses:
204:
description: Success, no content
@@ -259,18 +276,18 @@ components:
SemanticModelDocument:
type: object
- description: An Open Semantic Interchange (OSI) document body.
+ description: An Apache Ossie document body.
required:
- version
- semantic_model
properties:
version:
type: string
- description: The OSI spec version.
+ description: The Apache Ossie spec version.
example: "0.1.1"
semantic_model:
type: string
- description: The OSI semantic model serialized as a JSON string.
+ description: The Apache Ossie semantic model serialized as a JSON string.
example:
version: "0.1.1"
semantic_model: '{"name":"tpcds_retail_model","description":"retail analytics","datasets":[{"name":"store_sales","source":"public.store_sales","primary_key":["ss_item_sk","ss_ticket_number"]}],"metrics":[{"name":"total_sales","expression":{"dialects":[{"dialect":"ANSI_SQL","expression":"SUM(ss_ext_sales_price)"}]}}]}'
@@ -349,7 +366,7 @@ components:
description: |
Response when a semantic model is successfully updated.
- The updated OSI document is returned in the `document` field.
+ The updated Apache Ossie document is returned in the `document` field.
content:
application/json:
schema: