Categories:

System functions (Information)

SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW¶

Reads an existing semantic view and returns its definition as an Open Semantic Interchange (OSI) YAML document.

OSI is an open standard for representing semantic models that enables interoperability across AI and BI tools. This function converts the semantic view’s internal representation to OSI format and returns the resulting YAML string. Snowflake-specific features that have no OSI equivalent are preserved in vendor custom extensions so they survive a round-trip through external tools.

See also:

SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSI_YAML , SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW

Syntax¶

SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW( '<fully_qualified_semantic_view_name>' )

Arguments¶

'fully_qualified_semantic_view_name'

The fully qualified name of an existing semantic view, in the form database_name.schema_name.semantic_view_name.

If any part of the name contains special characters (spaces, mixed case), wrap each part in double quotes inside the single-quoted argument string. For example: '"my database"."my schema"."My Model"'.

Returns¶

On success, returns a VARCHAR containing the OSI YAML document in the standard document wrapper format:

version: "0.1.1"
semantic_model:
  - name: <model_name>
    ...

If the semantic view doesn’t exist or the calling role lacks privileges, the function raises an exception with a descriptive error message.

Access control requirements¶

Snowflake-to-OSI mapping reference¶

Field expression handling¶

Every field and metric expression is emitted with a single SNOWFLAKE dialect entry:

expression:
  dialects:
    - dialect: SNOWFLAKE
      expression: "<sql_expression>"

If the view was originally created from OSI YAML that included an ANSI_SQL dialect, only the SNOWFLAKE expression is returned (since Snowflake stores a single resolved expression internally).

Snowflake-specific data in custom_extensions¶

Snowflake features that have no direct OSI representation are serialized into a SNOWFLAKE vendor custom extension at the appropriate level. External tools can ignore these extensions or pass them through unchanged.

Model-level SNOWFLAKE extension:

Dataset-level SNOWFLAKE extension:

Field-level SNOWFLAKE extension:

Metric-level SNOWFLAKE extension:

What is converted faithfully¶

The following survive a full round-trip (write OSI YAML then read it back):

• Model name, description, and version
• Dataset names, descriptions, sources (qualified names and subqueries)
• Primary keys and unique keys
• All field names, descriptions, and expressions
• Field classification (dimension vs. time_dimension vs. fact)
• Equi-join relationships (name, from/to tables, column mappings)
• Model-level metrics (name, description, expression)
• ai_context at model, dataset, and field levels
• custom_extensions from any vendor (DBT, SALESFORCE, DATABRICKS, COMMON, SNOWFLAKE)

What is lost or not converted¶

Usage notes¶

• The output always uses the document wrapper format (top-level version + semantic_model array with one entry), regardless of whether the view was created from the flat or wrapper format.
• Semantic views created by any method (native YAML, DDL, or OSI YAML) can be exported with this function. Snowflake-specific features appear in the SNOWFLAKE vendor extension.
• Null fields are omitted from the output YAML (no empty keys cluttering the document).
• The output version field is determined as follows:
  • If the semantic view was originally created from OSI YAML, the version stored in extension metadata is used.
  • If the semantic view was created through native YAML or SQL (no stored OSI version), the default version "0.1.1" is used.

If the name of the database, schema, or view is a double-quoted identifier (for example, if the name contains spaces), you must include double quotes around the name. For example:

SELECT SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW(
  '"my database"."my schema"."My Model"'
);

Examples¶

Read a semantic view as OSI YAML¶

SELECT SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW(
  'my_db.my_schema.sales_model'
);

Returns:

version: "0.1.1"
semantic_model:
  - name: sales_model
    description: "Core sales semantic model"
    datasets:
      - name: orders
        source: my_db.public.orders
        primary_key:
          - order_id
        fields:
          - name: order_id
            expression:
              dialects:
                - dialect: SNOWFLAKE
                  expression: order_id
            dimension:
              is_time: false
          - name: order_date
            expression:
              dialects:
                - dialect: SNOWFLAKE
                  expression: order_date
            dimension:
              is_time: true
          - name: total_amount
            expression:
              dialects:
                - dialect: SNOWFLAKE
                  expression: total_amount
    metrics:
      - name: total_revenue
        description: "Sum of all order amounts"
        expression:
          dialects:
            - dialect: SNOWFLAKE
              expression: "SUM(total_amount)"

Read a view that has Snowflake-specific features¶

SELECT SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW(
  'analytics_db.public.customer_model'
);

Returns (Snowflake-specific features appear in custom_extensions):

version: "0.1.1"
semantic_model:
  - name: customer_model
    custom_extensions:
      - vendor: SNOWFLAKE
        content: '{"custom_instructions":"Answer in metric units"}'
    datasets:
      - name: customers
        source: analytics_db.public.customers
        fields:
          - name: region
            expression:
              dialects:
                - dialect: SNOWFLAKE
                  expression: region
            dimension:
              is_time: false
            custom_extensions:
              - vendor: SNOWFLAKE
                content: '{"synonyms":["area","territory"],"is_enum":true}'

Round-trip example: write then read¶

-- Write an OSI model
CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSI_YAML(
  'my_db.my_schema',
  $$
  version: "0.1.1"
  name: round_trip_model
  datasets:
    - name: sales
      source: my_db.public.sales
      primary_key:
        - sale_id
      fields:
        - name: sale_id
          expression:
            dialects:
              - dialect: SNOWFLAKE
                expression: sale_id
          dimension:
            is_time: false
        - name: sale_date
          expression:
            dialects:
              - dialect: SNOWFLAKE
                expression: sale_date
          dimension:
            is_time: true
        - name: amount
          expression:
            dialects:
              - dialect: SNOWFLAKE
                expression: amount
  $$
);

-- Read it back as OSI YAML
SELECT SYSTEM$READ_OSI_YAML_FROM_SEMANTIC_VIEW(
  'my_db.my_schema.round_trip_model'
);