docs(snowflake): clarify output format and link native Ossie semantic-view functions

[alphonse-terrier]

Motivation

The Snowflake converter's README could give the impression that it produces the newer Snowflake semantic view YAML (the format paired with CREATE SEMANTIC VIEW). It actually emits the legacy Cortex Analyst semantic model YAML (the stage-based format). These structures overlap but are distinct Snowflake surfaces, and the ambiguity could mislead users about what the output can be plugged into.

Change

Documentation only — no code or test changes.

• Add an Output format note clarifying that the converter emits the legacy Cortex Analyst semantic model YAML, not the semantic view YAML, with a link to Snowflake's semantic view YAML spec.
• Add an "Ossie YAML and Snowflake semantic views" section pointing to the native Snowflake procedures/functions that round-trip Ossie YAML to and from semantic views today:
  • SYSTEM$CREATE_SEMANTIC_VIEW_FROM_OSSIE_YAML (Ossie YAML → semantic view)
  • SYSTEM$READ_OSSIE_YAML_FROM_SEMANTIC_VIEW (semantic view → Ossie YAML)

Both are linked to their official docs. The section also flags a dedicated open-source Ossie ↔ semantic-view converter as welcome future work.

Scope

• Single file changed: converters/snowflake/README.md
• No changes to the converter source or tests.
• ASF license header preserved.

Checklist

• ICLA on file with the ASF (required before a first non-trivial contribution merges)
• Change is documentation-only; no tests affected
• Motivation and change described above

[khush-bhatia]

@alphonse-terrier Could you please give an example or a pointer to the code where it converts to the legacy yaml ?

Here is the linked converted example that confirms that it converts to the YAML surface that maps to Semantic View.

[alphonse-terrier]

Thanks for taking a look, @khush-bhatia 🙏

Agreed that the converted YAML works end-to-end: Snowflake ingests it and creates a Semantic View. That part isn't in dispute.

My point is a different one though: the file doesn't conform to the published semantic view YAML spec, because the converter emits fields that aren't part of that spec (the loader accepts them, but it looks like it just ignores the extras). Concretely:

1. unique_keys at the table level: emitted in _convert_dataset, visible in the committed example (unique_keys: L30-L33). The semantic view YAML table schema only defines primary_key. There is no table-level unique_keys (there's a unique boolean on dimensions/facts, which is a different thing).
2. synonyms at the table level: emitted here (store_sales in the example (L35-L39)). In the semantic view YAML spec, synonyms live on dimensions/time_dimensions/facts/metrics, not on the table.

Both of these are valid fields in the Cortex Analyst semantic model YAML but they aren't in the semantic view YAML spec. So "creates a Semantic View" and "conforms to the semantic view YAML spec" aren't the same claim: the first is true, the second isn't (extra fields, silently tolerated).

Happy to adjust the doc wording if the "legacy" framing feels too strong but I'd like to keep the note that the output isn't a field-for-field match of the semantic view YAML spec, since that's the practical gotcha for anyone diffing it against the docs. Does that work for you?

[khush-bhatia]

@alphonse-terrier

1. unique_keys at the table level: emitted in [_convert_dataset]

This represents a documentation gap in snowflake docs. I will follow up to get this fixed. The unique_keys at table level is the preferred approach since it enables customers to define a composite key as unique. The unique boolean on dimensions/facts is the old way but it is still supported to maintain backwards compatability.

2. synonyms at the table level:

In the semantic view YAML, synonyms are supported for both tables and facts/dimensions. If the Ossie converter is not handling the conversion correctly here, that's bug in the converter that can be fixed.