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.

Die wichtigsten Konzepte¶

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

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

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:

1. Bereitstellung einer Beschreibung mit grundlegenden Informationen über das Modell.

2. Bereitstellung der Datenquelle, die Sie zur Erstellung des Modells verwenden. Sie müssen mindestens eine Tabelle oder Ansicht bereitstellen.

3. 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:

1. Wählen Sie in Snowsight die Option AI & ML aus.

2. Wählen Sie neben Cortex Analyst die Option Try.

3. 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:

1. 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.

2. (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.

3. 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.

4. 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:

1. Wählen Sie Open semantic model aus.

2. Wählen Sie Open aus.

3. Wählen Sie Select from stage aus.

4. Wählen Sie die Datenbank und das Schema aus.

5. Klicken Sie außerhalb des Dialogfelds.

6. Wählen Sie den Stagingbereich, in dem Sie die Datei gespeichert haben.

7. Wählen Sie Öffnen.

Definieren von Verknüpfungen¶

Cortex Analyst unterstützt SQL-Verknüpfungen, die eine erweiterte Datenanalyse über mehrere Tabellen hinweg ermöglichen. Mit diesem Feature können Sie ganz einfach Daten aus Faktentabellen und zugehörigen Dimensionstabellen abfragen.

relationships:
  - name: <string>
    left_table: <string>
    right_table: <string>
    relationship_columns:
      - left_column: <string>
        right_column: <string>
      - left_column: <string>
        right_column: <string>
    join_type: <join_type>
    relationship_type: <relationship_type>

tables:
  - name: orders
    primary_key:
      columns:
        - order_id
        - location_id

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¶

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)
);

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')