Cortex Analyst-Spezifikation des semantischen Modells¶

Warum sollten Sie semantische Modelle verwenden?¶

Cortex Analyst ermöglicht Benutzern die Abfrage von Snowflake-Daten in natürlicher Sprache. Geschäftsanwender verwenden jedoch oft eine Sprache, die mit dem Schema nicht kompatibel ist. Während Benutzer in ihren Fragen domänenspezifische Geschäftsbegriffe angeben, werden die zugrunde liegenden Daten oft in technischen Abkürzungen gespeichert. Zum Beispiel wird „CUST“ oft für Kunden verwendet. Diese Diskrepanz in Verbindung mit dem fehlenden semantischen Kontext des Schemas macht es für Cortex Analyst schwierig, genaue Antworten zu geben.

Semantische Modelle dienen der Zuordnung von Geschäftsterminologie zu Datenbankschemata und fügen kontextbezogene Bedeutung hinzu. Wenn ein Benutzer beispielsweise nach dem „Gesamtumsatz im letzten Monat“ fragt, kann das semantische Modell „Umsatz“ als Nettoumsatz und „letzter Monat“ als den vorhergehenden Kalendermonat definieren. Diese Zuordnung hilft Cortex Analyst, die Absicht des Benutzers zu verstehen und genaue Antworten zu geben.

Bemerkung

Semantische Modelle werden als Metadaten betrachtet.

Die wichtigsten Konzepte¶

Bemerkung

In diesem Thema werden Datenbankartefakte als „physische“ Objekte bezeichnet, während semantische Modellartefakte als „logische“ Objekte bezeichnet werden.

Die Struktur und die Konzepte des semantischen Modells ähneln denen von Datenbank-Schemas, semantische Modelle ermöglichen es Ihnen, mehr semantische Informationen über Ihre Daten bereitzustellen.

Konzepte der semantischen Ebene¶

Die Struktur und die Konzepte, die die logische semantische Schicht definieren, sind denen ähnlich, die die physische Datenbankschicht definieren. Im Folgenden finden Sie die Konzepttypen für eine semantische Ebene:

Logische Tabellenebene
Modell-Ebene
Zusätzlicher Kontext

Semantische Modellkonzepte mit dem semantischen Modell ganz oben.

Logische Konzepte auf Tabellenebene¶

Eine logische Tabelle ist ein grundlegendes Konzept des semantischen Modells von Snowflake. Hierbei handelt es sich entweder um eine physische Datenbanktabelle oder um eine Ansicht. Sie entspricht in der Regel Geschäftsentitäten (wie Kunden, Aufträge oder Lieferanten) oder Dimensionen (wie Standort oder Zeit). Jede Zeile in einer logischen Tabelle repräsentiert normalerweise eine eindeutige Instanz der Entität, z. B. eine Kunden-ID.

Logische Tabellen enthalten die folgenden Arten von Spalten:

Fakten (quantitative Daten über Geschäftsereignisse)
Dimensionen (wer, was, wo und wie)
Uhrzeit (wann das Ereignis eingetreten ist)
Filter, die mit der logischen Tabelle verknüpft sind, damit die Abfrageergebnisse auf bestimmte Datenuntergruppen beschränkt werden können.

Sie können Metriken definieren, indem Sie Aggregationen oder Kombinationen anderer logischer Objekte verwenden.

Die folgenden Beispiele verwenden das TPC-H-Schema, das die Faktentabelle LINEITEM enthält. Eine vollständige YAML-Implementierung finden Sie in der Datei snow_tpch.

TPC-H-Schema, das die Beziehung zwischen der Faktentabelle LINEITEM und den DIMENSIONS-Tabellen zeigt.

Alle folgenden Beispiele auf der Ebene der logischen Tabelle gehören zu der logischen Tabelle order_lineitems.

tables:
  - name: order_lineitems
    description: >
      The order line items table contains detailed information about each item within an
      order, including quantities, pricing, and dates.

    base_table:
      database: SNOWFLAKE_SAMPLE_DATA
      schema: TPCH_SF1
      table: LINEITEM
    primary_key:
      columns:
        - order_key
        - order_lineitem_number

Copy

Die Dimension stellt kategorische Daten dar, die den Fakten einen Kontext geben, wie z. B. Produkt-, Kunden- oder Standortinformationen. Dimensionen enthalten in der Regel beschreibende Textwerte, wie z. B. Produktnamen oder Kundenadressen. Sie werden verwendet, um Fakten in Analysen und Berichten zu filtern, zu gruppieren und zu kennzeichnen.

Eine Zeitdimension bietet zeitlichen Kontext für die Analyse von Fakten über verschiedene Zeiträume hinweg. Sie ermöglicht die Nachverfolgung von Kennzahlen über bestimmte Zeitintervalle (Daten, Monate, Jahre) und unterstützt Analysen wie die Identifizierung von Trends und den Vergleich zwischen verschiedenen Zeiträumen.

time_dimensions:
  - name: shipment_duration
    synonyms:
      - "shipping time"
      - "shipment time"
    description: The time it takes for items to be shipped.

    expr: DATEDIFF(day, lineitem.L_SHIPDATE, lineitem.L_RECEIPTDATE)
    data_type: NUMBER
    unique: false

Copy

Fakten sind messbare, quantitative Daten, die den Kontext für Analysen liefern. Fakten stellen numerische Werte dar, die sich auf Geschäftsprozesse beziehen, z. B. Umsatz, Kosten oder Menge. Ein Fakt ist ein unaggregiertes Konzept auf Zeilenebene.

# Fact columns in the logical table.
facts:
  - name: net_revenue
    synonyms:
      - "revenue after discount"
      - "net sales"
    description: Net revenue after applying discounts.

    expr: lineitem.L_EXTENDEDPRICE * (1 - lineitem.L_DISCOUNT)
    data_type: NUMBER

Copy

Fakten können privat sein (im semantischen Modell zugänglich, aber nicht für Benutzer), indem das Feld access_modifier auf private_access eingestellt wird. Standardmäßig sind Fakten öffentlich (für Benutzer zugänglich).

Ein Filter ist eine Bedingung, die die Abfrageergebnisse auf bestimmte Datenuntergruppen einschränkt, die auf Kriterien wie Zeitraum, Ort oder Kategorie basieren.

- name: north_america
  synonyms:
    - "NA"
    - "North America region"
  description: >
    Filter to restrict data to orders from North America.
  comments: Used for analysis focusing on North American customers.
  expr: nation.N_NAME IN ('Canada', 'Mexico', 'United States')

Copy

Eine Kennzahl ist ein quantifizierbares Maß für die Geschäftsleistung, ausgedrückt als SQL-Formel. Sie können Kennzahlen als wichtige Leistungsindikatoren (KPIs) in Berichten und Dashboards verwenden. Sie können zwei Arten von Kennzahlen berechnen:

Reguläre Kennzahlen aggregieren Werte (mit Funktionen wie SUM oder AVG) für eine Faktenspalte.
Abgeleitete Kennzahlen werden aus vorhandenen Kennzahlen berechnet, wobei arithmetische Operationen wie Addition oder Division verwendet werden.

Definieren Sie Kennzahlen auf ihrer detaillierteste Ebene für die Aggregation auf höheren Ebenen. Definieren Sie beispielsweise total_revenue auf Einzelpostenebene, um eine Aggregation nach Kunden, Lieferanten oder Regionen zu ermöglichen.

Das folgende Beispiel zeigt zwei reguläre metrische Berechnungen: eine einfache und eine komplexere Berechnung. Diese sind innerhalb einer table-Definition definiert, sodass sie auf diese logische Tabelle beschränkt sind.

metrics:

    # Simple metric referencing objects from the same logical table
    - name: total_revenue
      expr: SUM(lineitem.l_extendedprice * (1 - lineitem.l_discount))

    # Complex metric referencing objects from multiple logical tables.
    # The relationships between tables have been defined below.
    - name: total_profit_margin
      description: >
                  The profit margin from orders. This metric is not additive
                  and should always be calculated directly from the base tables.
      expr: (SUM(order_lineitems.net_revenue) -
            SUM(part_suppliers.part_supplier_cost * order_lineitems.lineitem_quantity))
            / SUM(order_lineitems.net_revenue)

Copy

Tipp

Kennzahlen können privat gemacht werden (zugänglich im semantischen Modell, aber nicht für Benutzer), indem das Feld access_modifier auf private_access eingestellt wird. Standardmäßig sind Kennzahlen öffentlich (für Benutzer zugänglich).

Erlaubte Referenzen¶

Expressions for dimensions, facts, filters, or regular table-scoped metrics can reference:

Physische Spalten aus ihrer eigenen Basistabelle
Logische Spalten innerhalb der gleichen logischen Tabelle
Logische Spalten aus anderen logischen Tabellen im semantischen Modell

Abgeleitete Kennzahlen, die in den Bereich des Modells fallen, können auf Kennzahlen verweisen, die in einer beliebigen logischen Tabelle im semantischen Modell definiert sind, oder auf andere abgeleitete Kennzahlen.

Bemerkung

Ausdrücke können keine physischen Spalten aus anderen physischen Tabellen referenzieren.

Konzepte auf Modellebene¶

Beziehungen verbinden logische Tabellen durch Verknüpfungen auf gemeinsamen Schlüsseln. Es könnte zum Beispiel eine Beziehung zwischen den Tabellen Kunden und Bestellungen durch eine Verknüpfung über die Spalte Kunden_id bestehen. Sie können Verknüpfungen verwenden, um Auftragsdaten mit Kundenattributen zu analysieren.

relationships:

  # Relationship between orders and lineitems
  - name: order_lineitems_to_orders
    left_table: order_lineitems
    right_table: orders
    relationship_columns:
      - left_column: order_key
        right_column: order_key
    join_type: left_outer
    relationship_type: many_to_one

  # Relationship between lineitems and partsuppliers
  - name: order_lineitems_to_part_suppliers
    left_table: order_lineitems
    right_table: part_suppliers
    # The relationship requires equality of multiple columns from each table
    relationship_columns:
      - left_column: part_key
        right_column: part_key
      - left_column: supplier_key
        right_column: supplier_key
    join_type: left_outer
    relationship_type: many_to_one

Copy

Ein verifiziertes Abfrage-Repository (VQR) ist eine Sammlung von Fragen und entsprechenden SQL-Abfragen, die als korrekt verifiziert wurden. Sie können die Abfragen verwenden, um die Genauigkeit der Ergebnisse von Cortex Analyst zu verbessern.

Sie können Benutzerdefinierte Anweisungen in Cortex Analyst verwenden, um eine bessere Kontrolle über die SQL-Abfrage von Cortex Analyst zu haben. In den benutzerdefinierten Anweisungen stellen Sie dem LLM den einzigartigen Kontext Ihres Unternehmens zur Verfügung.

Semantischen Modelle von Cortex Analyst sind in YAML spezifiziert. Das Modell liefert die notwendigen semantischen Informationen, um natürlichsprachliche Fragen mit hoher Präzision zu beantworten.

YAML-Format¶

YAML ist ausgewogen zwischen menschlicher Lesbarkeit und Präzision. Geschäftsanwender können es verstehen, während Dateningenieure und Analysten technische Konzepte klar definieren können.

Die allgemeine Syntax eines semantischen Modells in Cortex Analyst lautet:

# Name and description of the semantic model.
name: <name>
description: <string>
comments: <string>

# Logical table-level concepts

# A semantic model can contain one or more logical tables.
tables:

  # A logical table on top of a base table.
  - name: <name>
    description: <string>


    # The fully qualified name of the base table.
    base_table:
      database: <database>
      schema: <schema>
      table: <base table name>

    # Dimension columns in the logical table.
    dimensions:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>
        cortex_search_service:
          service: <string>
          literal_column: <string>
          database: <string>
          schema: <string>
        is_enum: <boolean>


    # Time dimension columns in the logical table.
    time_dimensions:
      - name: <name>
        synonyms:  <array of strings>
        description: <string>

        expr: <SQL expression>
        data_type: <data type>
        unique: <boolean>

    # Fact columns in the logical table.
    facts:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        expr: <SQL expression>
        data_type: <data type>


    # Regular metrics scoped to the logical table.
    metrics:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        access_modifier: < public_access | private_access >  # Default is public_access

        expr: <SQL expression>


    # Commonly used filters over the logical table.
    filters:
      - name: <name>
        synonyms: <array of strings>
        description: <string>

        expr: <SQL expression>

# Model-level concepts

# Relationships between logical tables
relationships:
  - name: <string>

    left_table: <table>
    right_table: <table>
    relationship_columns:
      - left_column: <column>
        right_column: <column>
      - left_column: <column>
        right_column: <column>
    join_type: <left_outer | inner>
    relationship_type: < one_to_one | many_to_one >

# Derived metrics scoped to the semantic model
metrics:
  - name: <name>
    synonyms: <array of strings>
    description: <string>
    access_modifier: < public_access | private_access >  # Default is public_access

    expr: <SQL expression>


# Additional context concepts

#  Verified queries with example questions and queries that answer them
verified_queries:
  - name:        # A descriptive name of the query.

    question:    # The natural language question that this query answers.
    verified_at: # Optional: Time (in seconds since the UNIX epoch, January 1, 1970) when the query was verified.
    verified_by: # Optional: Name of the person who verified the query.
    use_as_onboarding_question:  # Optional: Marks this question as an onboarding question for the end user.
    sql:                         # The SQL query for answering the question

Copy

Eine Beispielspezifikation finden Sie in der Datei snow_tpch.yaml.

Erstellen Sie ein semantisches Modell mit dem Modellgenerator¶

Verwenden Sie den semantischen Modellgenerator, um ein semantisches Modell aus Ihren Tabellen zu erstellen. Anstatt ein semantisches Modell manuell mit Ihrer eigenen YAML-Spezifikation zu erstellen, können Sie den Modellgenerator in Snowsight verwenden, um Zeit zu sparen. Der Prozess der Erstellung eines semantischen Modells umfasst folgende Schritte:

Bereitstellung einer Beschreibung mit grundlegenden Informationen über das Modell.
Bereitstellung der Datenquelle, die Sie zur Erstellung des Modells verwenden. Sie müssen mindestens eine Tabelle oder Ansicht bereitstellen.
Auswählen der Spalten, die Sie zum Erstellen des Modells verwenden.

Um mit der Erstellung des Modells zu beginnen, navigieren Sie zur Seite Let’s Create a Semantic Model:

Wählen Sie in Snowsight die Option AI & ML aus.
Wählen Sie neben Cortex Analyst die Option Try.
Wählen Sie Create new aus.

Sie haben die Beschreibungsseite des semantischen Modellgenerators geöffnet. Um ein semantisches Modell zu erstellen, gehen Sie wie folgt vor:

Für Description geben Sie Informationen über das semantische Modell an. Sie müssen den Dateinamen, den Dateispeicherort und den Modellnamen angeben. Sie können auch eine Beschreibung mit Kontext zu den Daten angeben.
(Optional) Geben Sie für User Questions die Arten von Fragen an, die Benutzer zu den Daten stellen können. Der Modellgenerator verwendet die Informationen, die Sie in das Feld eingeben, um Tabellen, Ansichten und Spalten vorzuschlagen, die Sie zur Erstellung des Modells verwenden können.
Geben Sie unter Select Data (Table/View) die Datenquelle an, die Sie zur Erstellung des semantischen Modells verwenden. Sie müssen mindestens eine Tabelle oder Ansicht bereitstellen. Es gibt keine Begrenzung für die Tabellen oder Ansichten, die Sie angeben können, aber wir empfehlen, nicht mehr als 10 für das semantische Modell zu verwenden.
Wählen Sie unter Select Columns die Spalten aus, die Sie zur Erstellung des semantischen Modells verwenden. Sie können alle Spalten oder bestimmte Spalten auswählen. Aus Leistungsgründen empfehlen wir, nicht mehr als 50 Spalten zu verwenden.

Nachdem Sie das Modell erstellt haben, speichern Sie es in einem Stagingbereich. Um zu speichern, wählen Sie Save in der oberen rechten Ecke des Bildschirms. Wenn Sie weitere Änderungen vornehmen müssen, können Sie das Modell entweder mit Snowsight oder direkt in der YAML-Datei bearbeiten.

Öffnen Sie ein vorhandenes semantisches Modell¶

Nachdem Sie ein semantisches Modell erstellt haben, können Sie es in Snowsight öffnen. Um ein semantisches Modell zu öffnen, gehen Sie wie folgt vor:

Wählen Sie Open semantic model aus.
Wählen Sie Open aus.
Wählen Sie Select from stage aus.
Wählen Sie die Datenbank und das Schema aus.
Klicken Sie außerhalb des Dialogfelds.
Wählen Sie den Stagingbereich, in dem Sie die Datei gespeichert haben.
Wählen Sie Öffnen.

Bemerkung

If you don’t see your semantic model within your stage, try refreshing the list of models, not the page.

Tipps für die Erstellung eines semantischen Modells¶

Organisieren Sie Ihre YAML-Datei nach Geschäftsbereichen oder Themen
- Strukturieren Sie Ihre YAML-Dateien so, dass sie sich an bestimmten Geschäftsbereichen oder Themen orientieren und der Bereich fokussiert bleibt. Erstellen Sie zum Beispiel separate semantische Modelle für die Vertriebsanalyse und die Marketinganalyse.
- Passen Sie Ihre Anwendungsfälle an das Zielpublikum, die erwarteten Fragen oder KPIs und die benötigten Daten an. Gut definierte Anwendungsfälle führen zu umfangreicheren semantischen Modellen und einem effektiveren Datenabruf.
Denken Sie aus der Perspektive des Endbenutzers
- Identifizieren Sie die wichtigsten Fragen, die Benutzer wahrscheinlich zu diesem Thema stellen werden, und nehmen Sie nur die Tabellen und Spalten auf, die zur Beantwortung dieser Fragen erforderlich sind.
- Verwenden Sie Namen und Synonyme, die dem von Ihren Benutzern verwendeten Vokabular ähnlich sind.
- Fügen Sie wichtige Details in die Beschreibungsfelder ein, die für jemanden, der zum ersten Mal Abfragen zu diesem Datenset schreibt, hilfreich wären, wie z. B. die Zeitzone einer DATETIME Spalte.
Komplexe Berechnungen erfassen

Fügen Sie schwierigere oder geschäftsspezifische Abfragen in Ausdrücke ein.
Breite Tabellen anstelle von langen Tabellen verwenden

Wenn Sie eine Tabelle mit Spalten wie „Kennzahl“ und „Wert“ haben, vereinfachen Sie die Tabelle so, dass jede Kennzahl eine Spalte ist. Dieser Ansatz versorgt das Modell mit mehr semantischen Informationen zu jeder Metrik.
Automatisch generierte Beschreibungen überprüfen

Wenn Sie den semantic model generator verwenden, versucht dieser, automatisch Beschreibungen für Ihre Tabellen und Spalten zu erstellen. Überprüfen Sie diese Beschreibungen immer, um sicherzustellen, dass sie angemessen und relevant sind; nehmen Sie bei Bedarf Änderungen vor.
Beginnen Sie einfach und erweitern Sie schrittweise

Eine gut durchdachte semantische Datei gewährleistet eine höhere Präzision und Genauigkeit der Ergebnisse. Beginnen Sie mit einer kleinen Anzahl von Tabellen und Spalten und erweitern Sie das semantische Modell YAML schrittweise, um mehr Arten von Fragen abzudecken. Denken Sie daran, dass der YAML-Aufbau ein kontinuierlicher Prozess ist.
Verifizierte Abfragen einbeziehen

Ein von Geprüftes Abfrage-Repository (VQR), das eine Sammlung Fragen in einfacher Sprache und Abfragen zu deren Beantwortung darstellt, kann dazu beitragen, die Genauigkeit und Vertrauenswürdigkeit der Ergebnisse zu verbessern.

Bekannte Einschränkungen¶

Cortex Analyst legt eine Größenbeschränkung von 1 MB für die semantische Modelldatei fest, um die Größe der API-Eingaben zu begrenzen.

Spezifikation¶

Dieser Abschnitt enthält detaillierte Spezifikationen zu den in den vorangegangenen Abschnitten beschriebenen Schlüsselkonzepten.

Semantisches Modell¶

Ein semantisches Modell stellt eine Sammlung von Tabellen dar. Das Modell enthält Beschreibungen von Tabellen, die jeweils Beschreibungen spezifischer Aspekte der Tabelle enthalten. Jede im Modell beschriebene Tabelle wird einer physischen Basistabelle in Snowflake zugeordnet.

Es hat die folgenden Felder:

Erforderlich

name

Ein beschreibender Name für dieses semantische Modell

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

Optional

Diese Felder sind nicht obligatorisch, sollten aber nach Möglichkeit ausgefüllt werden.

description: Eine Beschreibung dieses semantischen Modells, einschließlich Details über die Art der Analyse, für die es nützlich ist.
tables: Eine Liste der logischen Tabellen in diesem semantischen Modell
relationships: Eine Liste von Verknüpfungen zwischen logischen Tabellen.

Logische Tabelle¶

Sie können sich eine logische Tabelle als eine Ansicht über eine physische Datenbanktabelle oder Ansicht vorstellen. Es hat die folgenden Felder:

Erforderlich

name

Ein beschreibender Name für diese Tabelle

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

base_table

Ein vollständig qualifizierter Name der zugrunde liegenden Basistabelle in der Datenbank.

Optional

Diese Felder sind nicht obligatorisch, sollten aber nach Möglichkeit ausgefüllt werden.

synonyms: Eine Liste anderer Begriffe/Phrasen, die sich auf diese Tabelle beziehen. Sie muss für alle Synonyme innerhalb der logischen Tabelle eindeutig sein.
description: Eine Beschreibung dieser Tabelle.
primary_key: Die Primärschlüsselspalten für diese Tabelle. Erforderlich, wenn Sie Beziehungen definieren.
dimensions: Eine Liste der Dimensionsspalten in dieser Tabelle.
time_dimensions: Eine Liste der Zeitdimensionsspalten in dieser Tabelle
facts: Eine Liste der Faktspalten in dieser Tabelle.
metrics: Eine Liste der Metriken in dieser Tabelle.
filters: Vordefinierte Filter für diese Tabelle, falls vorhanden.

Dimension¶

Eine Dimension beschreibt kategoriale Werte wie Status, user_type, Plattform usw. Es hat die folgenden Felder:

Erforderlich

name

Ein beschreibender Name für diese Dimension

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

expr

Der SQL-Ausdruck für diese Dimension. Dies kann ein Verweis auf eine physische Spalte oder ein SQL-Ausdruck mit einer oder mehreren Spalten aus der zugrunde liegenden Basistabelle sein.

data_type

Der Datentyp dieser Dimension. Eine Übersicht zu allen Datentypen in Snowflake finden Sie unter Referenz der SQL-Datentypen. Beachten Sie, dass VARIANT, OBJECT, GEOGRAPHY und ARRAY derzeit nicht unterstützt werden.

Optional

Diese Felder sind nicht obligatorisch, sollten aber nach Möglichkeit ausgefüllt werden.

synonyms

Eine Liste anderer Begriffe/Phrasen, die sich auf diese Dimension beziehen. Muss für alle Synonyme in diesem semantischen Modell eindeutig sein.

description

Eine kurze Beschreibung dieser Dimension, einschließlich der Daten, die sie enthält.

unique

Ein boolescher Wert, der angibt, dass diese Dimension eindeutige Werte hat.

sample_values

Beispielwerte für diese Spalte, falls vorhanden. Fügen Sie alle Werte hinzu, auf die in den Fragen der Benutzer wahrscheinlich Bezug genommen wird.

is_enum

Ein boolescher Wert. Wenn Sie True wählen, werden die Werte im Feld sample_values als die vollständige Liste der möglichen Werte betrachtet und das Modell wählt nur aus diesen Werten, wenn es nach dieser Spalte filtert.

cortex_search_service

Gibt den Cortex Search Service an, der für diese Dimension verwendet werden soll. Es hat die folgenden Felder:

service: Der Name des Cortex Search Service.
literal_column: (optional) Die Spalte im Cortex Search Service, die die literalen Werte enthält.
database: (optional) Die Datenbank, in der sich der Cortex Search Service befindet. Standardmäßig wird die Datenbank von base_table verwendet.
schema: (optional) Das Schema, in dem sich der Cortex Search Service befindet. Standardmäßig wird das Schema von base_table verwendet.

cortex_search_service replaces the cortex_search_service_name field, which could only specify the name. cortex_search_service_name has been deprecated.

Zeitliche Dimension¶

Eine Zeitdimension beschreibt Zeitwerte, wie sale_date, created_at und year. Es hat die folgenden Felder:

Erforderlich

name

Ein beschreibender Name für diese Zeitdimension

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

expr

Der SQL-Ausdruck für diese Spalte. Dies kann ein Verweis auf eine physische Spalte oder ein SQL-Ausdruck mit einer oder mehreren Spalten aus der zugrunde liegenden Basistabelle sein.

data_type

Der Datentyp dieser Zeitdimension Eine Übersicht zu allen Datentypen in Snowflake finden Sie unter Referenz der SQL-Datentypen. Beachten Sie, dass VARIANT, OBJECT, GEOGRAPHY und ARRAY derzeit nicht unterstützt werden.

Optional

Diese Felder sind nicht obligatorisch, sollten aber nach Möglichkeit ausgefüllt werden.

synonyms: Eine Liste anderer Begriffe/Phrasen, die sich auf diese Zeitdimension beziehen. Muss für alle Synonyme in diesem semantischen Modell eindeutig sein.
description: Eine kurze Beschreibung dieser Dimension, einschließlich der Daten, die sie enthält. Stellen Sie Informationen bereit, die jemandem helfen, der Abfragen mit dieser Tabelle schreibt. Geben Sie zum Beispiel für DATETIME-Spalten die Zeitzone der Daten an.
unique:: Ein boolescher Wert, der angibt, dass diese Spalte eindeutige Werte hat.
sample_values:: Beispielwerte für diese Spalte, falls vorhanden. Fügen Sie alle Werte hinzu, auf die in den Fragen der Benutzer wahrscheinlich Bezug genommen wird. Dieses Feld ist optional.

Fakt¶

A fact describes numerical values, such as revenue, impressions, and salary. Facts used to be called measures in earlier releases of Cortex Analyst. Facts are backward compatible with measures. Facts have the following fields:

Erforderlich

name

Ein beschreibender Name für diesen Fakt.

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

expr

Dieser SQL-Ausdruck kann sich entweder auf eine physische Spalte in der physischen Basistabelle der gleichen logischen Tabelle oder auf eine logische Spalte (Fakt, Dimension oder Zeitdimension) innerhalb dieser logischen Tabelle beziehen.

data_type

Der Datentyp dieses Fakts. Eine Übersicht zu allen Datentypen in Snowflake finden Sie unter Referenz der SQL-Datentypen. Beachten Sie, dass VARIANT, OBJECT, GEOGRAPHY und ARRAY derzeit nicht unterstützt werden.

Optional

The following fields are not required, but should be included whenever possible.

synonyms: Eine Liste anderer Begriffe/Phrasen, die sich auf diese Maßnahme beziehen. Muss für alle Synonyme in diesem semantischen Modell eindeutig sein.
description: Eine kurze Beschreibung dieser Maßnahme, einschließlich der Daten, die diese Spalte enthält.
unique: Ein boolescher Wert, der angibt, dass diese Spalte eindeutige Werte hat.
sample_values: Beispielwerte für diese Spalte, falls vorhanden. Fügen Sie alle Werte hinzu, auf die in den Fragen der Benutzer wahrscheinlich Bezug genommen wird.

Das folgende Feld ist optional. Wenn es nicht enthalten ist, wird standardmäßig public_access verwendet.

access_modifier: Entweder public_access oder private_access. Bei private_access ist der Fakt im semantischen Modell zugänglich, aber nicht für Benutzer.

Filter¶

Ein Filter stellt einen SQL-Ausdruck dar, der zum Filtern verwendet wird. Es hat die folgenden Felder:

Erforderlich

name: Ein beschreibender Name für diesen Filter
expr: Der SQL-Ausdruck dieses Filters, der sich auf logische Spalten bezieht

Optional

Diese Felder sind nicht obligatorisch, sollten aber nach Möglichkeit ausgefüllt werden.

synonyms: Eine Liste anderer Begriffe/Phrasen, die sich auf diesen Filter beziehen. Muss für alle Synonyme in diesem semantischen Modell eindeutig sein.
description: Eine kurze Beschreibung dieses Filters, einschließlich Details darüber, wofür dieser Filter normalerweise verwendet wird.

Kennzahl¶

A metric describes quantifiable measures of business performance, such as total revenue, average order value, or customer count. Metrics can be regular metrics or derived metrics.

Reguläre Kennzahlen sind auf eine logische Tabelle beschränkt und können auf logische Spalten (Fakten, Dimensionen oder Zeitdimensionen) innerhalb derselben logischen Tabelle oder auf logische Spalten aus anderen logischen Tabellen im semantischen Modell verweisen. Im semantischen Modell befindet sich das metric-Element innerhalb eines table-Elements. Reguläre Kennzahlen verwenden Aggregat- und Fensterfunktionen, um die Gesamtwerte für die Tabelle zu berechnen.
Abgeleitete Kennzahlen gelten für das semantische Modell und bieten eine Möglichkeit, andere Kennzahlen zu kombinieren. Im semantischen Modell befindet sich das metric-Element innerhalb des semantic_model-Elements. Sie können sich nur im Ausdruck der Kennzahl auf andere Kennzahlen (einschließlich anderer abgeleiteter Kennzahlen) beziehen.

Metrics have the following fields.

Erforderlich

name

A descriptive name for this metric. This name deterines whether it is a regular metric.

Muss eindeutig sein und den Anforderungen von Bezeichner ohne Anführungszeichen entsprechen. Es darf auch nicht mit den reservierten Schlüsselwörtern von Snowflake in Konflikt stehen.

expr

Der SQL-Ausdruck für diese Spalte. Das Format des Ausdrucks hängt davon ab, ob es sich bei der Kennzahl um eine reguläre Kennzahl oder eine abgeleitete Kennzahl handelt.

Regular metrics, which are scoped to a table, reference a logical column (fact, dimension, or time dimension) in the same logical table or a logical column from another logical table in the semantic model and use aggregate or window functions to calculate overall values.
Abgeleitete Metriken sind skalare Ausdrücke, die auf reguläre Kennzahlen oder andere abgeleitete Kennzahlen verweisen können.

Optional

The following fields are not required, but should be included whenever possible.

synonyms: A list of other terms/phrases used to refer to this metric. Each synonym must be unique across all synonyms in the semantic model.
description: Eine kurze Beschreibung dieser Metrik, einschließlich der Daten, die diese Spalte enthält.
sample_values: Beispielwerte für diese Spalte, falls vorhanden. Fügen Sie alle Werte hinzu, auf die in den Fragen der Benutzer wahrscheinlich Bezug genommen wird.

Das folgende Feld ist optional. Wenn es nicht enthalten ist, wird standardmäßig public_access verwendet.

access_modifier: Entweder public_access oder private_access. Bei private_access ist die Kennzahl im semantischen Modell zugänglich, aber nicht für Benutzer.

Basistabelle¶

Eine Basistabelle wird verwendet, um vollständig qualifizierte Tabellennamen darzustellen. Dies ist die physische Tabelle, der eine logische Tabelle zugeordnet ist. Es hat die folgenden Felder:

Erforderlich

database: Name der Datenbank.
schema: Name des Schemas.
table: Name der Tabelle.

Primärschlüssel¶

Ein Primärschlüssel stellt die Spalten dar, die jede Zeile der Tabelle eindeutig repräsentieren. Der Primärschlüssel ist erforderlich, wenn die Tabelle in einer Beziehung verwendet wird. Es hat die folgenden Felder:

Erforderlich

columns: Eine Liste von Dimensionsspalten, die die Tabelle eindeutig repräsentieren.

Beziehungen¶

Definiert Verknüpfungsbeziehungen zwischen logischen Tabellen. Um eine ordnungsgemäße Verknüpfungsfunktionalität zu gewährleisten, müssen Primärschlüssel für die an den Beziehungen beteiligten Tabellen definiert werden. Es hat die folgenden Felder:

Erforderlich

name: Ein eindeutiger Bezeichner für die Beziehung.
left_table: Logischer Tabellenname, wie zuvor in Ihrer YAML-Datei definiert. Bei Viele-zu-eins-Beziehungen sollte die linke Tabelle die Viele-Seite der Beziehung sein, um eine optimale Leistung zu erzielen.
right_table: Logischer Tabellenname, wie zuvor in Ihrer YAML-Datei definiert. Bei Viele-zu-Eins-Beziehungen muss für eine optimale Leistung die rechte Tabelle die Eins-Seite der Beziehung sein.
relationship_columns: Eine Liste gleicher Spalten aus der linken Tabelle und der rechten Tabelle, die den Verknüpfungspfad darstellen.
join_type: Entweder left_outer oder inner.
relationship_type: Entweder many_to_one oder one_to_one.

Geprüfte Abfragen¶

Unter Cortex Analyst Geprüftes Abfrage-Repository finden Sie Informationen über den Zweck und die Struktur dieses Abschnitts der YAML-Datei.

Kundenspezifische Anweisungen¶

For information about custom instructions, see Benutzerdefinierte Anweisungen in Cortex Analyst.