Semantic models¶

A semantic model says what the tables in a namespace mean: datasets that map to tables, their fields, the relationships between datasets and agreed metrics with their SQL. It follows the Apache Ossie specification. Polaris 1.8 stores it in the namespace, next to the tables, and it never runs a metric.

• See them: open a namespace in Catalog. Semantic models are listed after tables and views. Details → shows the overview, the datasets with their AI context and their fields, each with its label, description, synonyms and examples (Open table → jumps to the Iceberg table), the metrics and relationships, and the stored definition, as YAML by default or as the JSON Polaris stores. Reading needs the Reader role.
• Create them: run example notebook 06 · Write an AI-ready flights product. It needs the Writer role; it publishes the flights tables and then their semantic model. Every field gets a description and, where the ontology has one, a label naming the concept it holds, such as Delay or AirportCode; flights.product.yaml holds them beside the notebook. Notebook 07 reads the model back with any role. Notebooks 09 and 10 do the same with Polars for a synthetic MV load forecast; there grid_forecast.product.yaml is the only source of the product's meaning, from the column docs to the metrics. Writers create, replace and remove models; an update is refused if someone else changed the model since you read it. A coding agent can build one with you through the installation's semantic-model skill, which interviews you about the questions the model must answer, and store it with the MCP tool publish_semantic_model.
• See the structure: the Diagram tab draws each dataset as a table with its fields and each relationship as a line between the join columns. Hover a dataset to follow its relationships, or select it to open its table.
• Ask an AI agent: the MCP tools list_semantic_models and describe_semantic_model return the same information. describe_semantic_model gives a summary by default, which search and dataset narrow for large models; detail="full" adds every description, and include_definition also returns the stored document. list_dimension_values lists a dimension's values, so an agent filters on the exact spelling. query_semantic_model answers questions from the agreed metrics: the agent names metrics, dimensions (with an optional time grain) and filters, and the portal compiles the model's SQL, joining only along its relationships, and runs it read-only with your own permissions in a sandboxed DuckDB process. It accepts only scalar and aggregate metric SQL over the model's columns, as Conversational BI does; publishing warns about metrics it would refuse and refuses fields that are not columns of their table.
• Share them: a data share can include semantic models. A listed share publishes them, with their descriptions, labels and AI context, to a data catalog such as OpenMetadata. Recipients see exactly the shared models in Catalog and read them with their own account or the share credential; they can't list other models or change any.

Semantic models are a beta feature of Polaris. The platform switches them on; an administrator can turn them off (semantic models). The portal then simply lists none, and the notebook explains that they are switched off.