mchades commented on code in PR #14210: URL: https://github.com/apache/gravitino/pull/14210#discussion_r4413574544
########## docs/manage-semantic-model-metadata-using-gravitino.md: ########## @@ -326,6 +327,144 @@ loaded = models.load_semantic_model(ident) </TabItem> </Tabs> +### Discover Metrics in a Schema + +Use schema-level metric discovery to find metrics across the current definitions of Semantic +Models in one schema. You can list identifiers or retrieve complete metric definitions without +first listing and loading each model. These examples use the `total_revenue` metric in +`mart.sales_model` created above, before importing any other models. + +#### List Metric Identifiers + +<Tabs groupId='language' queryString> +<TabItem value="shell" label="REST"> + +```shell +curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \ + 'http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/mart/semantic-model-metrics' +``` + +The default is `details=false`. If `sales_model` is the only model with metrics in this schema, +the response is: + +```json +{ + "code": 0, + "identifiers": [ + { + "namespace": ["example", "sales", "mart", "sales_model"], + "name": "total_revenue" + } + ] +} +``` + +</TabItem> +<TabItem value="java" label="Java"> + +```java +NameIdentifier[] metricIdentifiers = models.listMetrics(Namespace.of("mart")); +``` + +</TabItem> +<TabItem value="python" label="Python"> + +```python +metric_identifiers = models.list_metrics(Namespace.of("mart")) +``` + +</TabItem> +</Tabs> + +Metric names are unique within a model. Two models can both define `total_revenue`; use the +namespace together with the metric name to distinguish them. + +| Interface | Namespace in each result | Metric name | +|-----------|--------------------------|-------------| +| REST | `["example", "sales", "mart", "sales_model"]` | `total_revenue` | +| Java / Python, using the loaded `sales` catalog | `["mart", "sales_model"]` | `total_revenue` | + +The SDK methods accept a schema namespace, such as `Namespace.of("mart")`. Do not include the +metalake, catalog, or model in that argument. + +#### Retrieve Metric Definitions + +<Tabs groupId='language' queryString> +<TabItem value="shell" label="REST"> + +```shell +curl -X GET -H "Accept: application/vnd.gravitino.v1+json" \ + 'http://localhost:8090/api/metalakes/example/catalogs/sales/schemas/mart/semantic-model-metrics?details=true' +``` + +For the same model, the response is: + +```json +{ + "code": 0, + "metrics": [ + { + "namespace": ["example", "sales", "mart", "sales_model"], + "metric": { + "name": "total_revenue", + "expression": { + "dialects": [ + {"dialect": "ANSI_SQL", "expression": "SUM(orders.order_amount)"} + ] + }, + "datatype": "Decimal" + } + } + ] +} +``` + +</TabItem> +<TabItem value="java" label="Java"> + +```java +SemanticModelMetric[] metricInfos = models.listMetricInfos(Namespace.of("mart")); +``` + +</TabItem> +<TabItem value="python" label="Python"> + +```python +metric_infos = models.list_metric_infos(Namespace.of("mart")) +``` + +</TabItem> +</Tabs> + +Each SDK result exposes `namespace()` and `metric()`. The metric contains its name, expression, +and any stored data type, description, AI context, or custom extensions. To construct its identifier, +use `NameIdentifier.of(info.namespace(), info.metric().name())` in Java or +`NameIdentifier.builder(info.namespace(), info.metric().name())` in Python. + +#### Ordering, Visibility, and Updates + +Both listing modes sort results by the containing model's identifier and then by case-sensitive +metric name. Models without metrics contribute no entries. If there are no visible metrics, REST +returns an empty `identifiers` or `metrics` array and the SDKs return an empty array or list. Review Comment: This follows the existing table, view, and model-version listing APIs, which are also unpaginated. The guide already describes schema-wide discovery and complete definitions, so I’d keep it consistent with the other listing guides. -- 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]
