Cortex Analyst-Spezifikation des semantischen Modells¶

Warum sollten Sie semantische Modelle verwenden?¶

Cortex Analyst ermöglicht es Benutzern, Fragen zu Snowflake-Daten in natürlicher Sprache zu stellen. In der Regel besteht eine Diskrepanz zwischen dem Vokabular, das von Benutzern bei Datenfragen verwendet wird, und dem Vokabular, das im Datenbankschema verwendet wird. Diese Benutzer verwenden in der Regel geschäfts- oder domänenspezifische Begriffe, während das Datenbankschema möglicherweise Abkürzungen oder Begriffe verwendet, die häufig in ETL-Pipelines verwendet werden. Datenbankschemas enthalten oft auch keine semantischen Details, die jemandem, der mit einem Datensatz nicht vertraut ist, helfen, die Daten zu verstehen. Dieser Unterschied im Vokabular macht es für Cortex Analyst schwierig, Datenfragen mit hoher Präzision zu beantworten.

Ein semantisches Modell ist ein einfacher Mechanismus, der diese Probleme löst, indem er die Angabe zusätzlicher semantischer Details zu einem Datenset ermöglicht. Diese zusätzlichen semantischen Details, wie aussagekräftigere Namen oder Synonyme, ermöglichen es Cortex Analyst, Datenfragen viel zuverlässiger zu beantworten.

Bemerkung

Semantische Modelle werden als Metadaten betrachtet.

Die wichtigsten Konzepte¶

Bemerkung

In diesem Thema werden die Artefakte der Basisdatenbank als „physische“ Artefakte und die Artefakte des semantischen Modells als „logische“ Artefakte bezeichnet.

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.

Ein Kernkonzept der semantischen Modelle von Snowflake ist die logische Tabelle. Eine logische Tabelle kann man sich als eine einfache Ansicht einer physischen Datenbanktabelle oder Ansicht vorstellen. Jede logische Tabelle ist eine Sammlung von logischen Spalten, die in dimensions, time_dimensions und measures unterteilt sind.

Eine logische Spalte kann entweder eine Referenz auf eine zugrunde liegende physische Spalte sein oder ein Ausdruck, der eine oder mehrere physische Spalten zusammenfasst. Der Ausdruck kann einfach sein, wie eine Zeichenfolge oder eine mathematische Operation, oder er kann Aggregationsausdrücke enthalten. Sie können zum Beispiel einen Ausdruck wie SUM(click)/SUM(spend) verwenden, um die Kosten pro Klick zu berechnen (CPC).

Das semantische Modell kann auch ein Geprüftes Abfrage-Repository (VQR) enthalten, das dazu beitragen kann, die Präzision und Vertrauenswürdigkeit der Ergebnisse zu verbessern, indem es eine Sammlung von Fragen und entsprechenden SQL-Abfragen zu deren Beantwortung bereitstellt.

Das semantische Modell für die Cortex Analyst-Spezifikation finden Sie unter YAML. Es liefert die notwendigen semantischen Informationen, um Fragen in natürlicher Sprache mit hoher Präzision zu beantworten.

Die allgemeine Syntax ist wie folgt:

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

# 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_name: <string>

    # 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>

    # Measure columns in the logical table.
    measures:
      - name: <name>
        synonyms: <array of strings>
        description: <string>
        expr: <SQL expression>
        data_type: <data type>
        default_aggregation: <aggregate function>

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

# Example questions and queries that answer them
verified_queries:

# Verified Query (1 of n)
- 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

Generator für semantische Modelle¶

Sie können das Tool Generator für semantische Modelle verwenden, um ein semantisches Modell zur Verwendung mit Cortex Analyst zu erstellen. Das Tool bietet mehrere Möglichkeiten zur Generierung semantischer Modelle: über eine Streamlit-App, über die Befehlszeile oder direkt in Ihrem Python-Code. Besonders praktisch ist die Streamlit-App, mit der Sie semantische Modelle von Grund auf erstellen oder bestehende Modelle, die in einen Snowflake Stagingbereich hochgeladen wurden, iterieren können.

Tipps für die Erstellung eines semantischen Modells¶

Organisieren Sie Ihre Datei YAML 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 für die semantische Modelldatei ( 1MB ) fest, um die Größe API-Eingaben zu begrenzen.
Cortex Analyst führt den Abruf von Beispielwerten und verifizierten Abfragen im Speicher durch, die dem semantischen YAML hinzugefügt wurden. Nach dem Entfernen aller Beispiele und verifizierten Abfragen kann das semantische Modell 32-K-Token nicht überschreiten (etwa 4 × 32 K Zeichen oder ungefähr 128 KB). Sie können den Befehl zur Validierung des semantischen Modells verwenden, um sicherzustellen, dass Ihre Datei innerhalb dieser Beschränkungen bleibt. Die Beschränkungen können sich erhöhen, wenn die Unterstützung für Modelle mit größeren Kontextfenstern hinzugefügt wird.

Spezifikation¶

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 (empfohlen)

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

Tabelle¶

Eine logische Tabelle kann man sich als eine Ansicht einer physischen 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 (empfohlen)

synonyms: Eine Liste anderer Begriffe/Phrasen, die sich auf diese Tabelle beziehen. Muss für alle Synonyme innerhalb der logischen Tabelle eindeutig sein.
description: Eine Beschreibung dieser Tabelle.
dimensions: Eine Liste der Dimensionsspalten in dieser Tabelle.
time_dimensions: Eine Liste der Zeitdimensionsspalten in dieser Tabelle
measures: Eine Liste der Maßnahmen 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 (empfohlen)

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.
cortex_search_service_name: Name des Cortex Search Service, der die literalen Werte in der Spalte durchsucht. Wenn sowohl ein Dienstname als auch sample_values angegeben sind, werden die Werte im Feld sample_values ignoriert.

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 (empfohlen)

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.

Maßnahme¶

Eine Kennzahl beschreibt numerische Werte, wie z. B. Umsatz, Impressionen und Gehalt. Es hat die folgenden Felder:

Erforderlich

name

Ein beschreibender Name für diese Maßnahme

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 Maßnahme. 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 (empfohlen)

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.
default_aggregation: Die Standardaggregation, die auf diese Spalte im Kontext einer Gruppierung angewendet wird. Einige Beispielwerte sind sum, avg, min, max, median, count, count_distinct usw.
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.

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

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 dieses Filters, der sich auf logische Spalten bezieht

Optional (empfohlen)

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.

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.

Geprüfte Abfragen¶

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

Beispiel YAML¶

Dieser Abschnitt zeigt ein Beispiel für ein semantisches YAML-Modell.

In diesem Beispiel wird davon ausgegangen, dass Sie die folgende Tabelle in Ihrem Schema haben:

CREATE TABLE sales.public.sd_data (
    id INT PRIMARY KEY,
    dt DATETIME,
    cat VARCHAR(255),
    loc VARCHAR(255),
    cntry VARCHAR(255),
    chn VARCHAR(50),
    amt DECIMAL(10, 2),
    unts INT,
    cst DECIMAL(10, 2)
);

Copy

Diese Tabelle hat kryptische Spaltennamen und nicht viele semantische Informationen über die Spalten. Im Folgenden finden Sie ein semantisches YAML-Modell, das weitere semantische Informationen über diese Tabelle enthält:

# Name and description of the semantic model.
name: Sales Data
description: This semantic model can be used for asking questions over the sales data.

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

  # A logical table on top of the 'sd_data' base table.
  - name: sales_data
    description: A logical table capturing daily sales information across different store locations and product categories.

    # The fully qualified name of the base table.
    base_table:
      database: sales
      schema: public
      table: sd_data

    # Dimension columns in the logical table.
    dimensions:
      - name: product_category
        synonyms:
          - "item_category"
          - "product_type"
        description: The category of the product sold.
        expr: cat
        data_type: NUMBER
        unique: false
        sample_values:
          - "501"
          - "544"

      - name: store_country
        description: The country where the sale took place.
        expr: cntry
        data_type: TEXT
        unique: false
        sample_values:
          - "USA"
          - "GBR"

      - name: sales_channel
        synonyms:
          - "channel"
          - "distribution_channel"
        description: The channel through which the sale was made.
        expr: chn
        data_type: TEXT
        unique: false
        sample_values:
          - "FB"
          - "GOOGLE"

    # Time dimension columns in the logical table.
    time_dimensions:
      - name: sale_timestamp
        synonyms:
          - "time_of_sale"
          - "transaction_time"
        description: The time when the sale occurred. In UTC.
        expr: dt
        data_type: TIMESTAMP
        unique: false

    # Measure columns in the logical table.
    measures:
      - name: sales_amount
        synonyms:
          - "revenue"
          - "total_sales"
        description: The total amount of money generated from the sale.
        expr: amt
        data_type: NUMBER
        default_aggregation: sum

      - name: sales_tax
        description: The sales tax paid for this sale.
        expr: amt * 0.0975
        data_type: NUMBER
        default_aggregation: sum

      - name: units_sold
        synonyms:
          - "quantity_sold"
          - "number_of_units"
        description: The number of units sold in the transaction.
        expr: unts
        data_type: NUMBER
        default_aggregation: sum

      - name: cost
        description: The cost of the product sold.
        expr: cst
        data_type: NUMBER
        default_aggregation: sum

      - name: profit
        synonyms:
          - "earnings"
          - "net income"
        description: The profit generated from a sale.
        expr: amt - cst
        data_type: NUMBER
        default_aggregation: sum

    # A table can define commonly used filters over it. These filters can then be referenced in user questions directly.
    filters:
      - name: north_america
        synonyms:
          - "North America"
          - "N.A."
          - "NA"
        description: "A filter to restrict only to north american countries"
        expr: cntry IN ('canada', 'mexico', 'usa')

Copy