Utiliser des commandes SQL pour créer et gérer des vues sémantiques

Cette rubrique explique comment utiliser les commandes SQL suivantes pour créer et gérer des vues sémantiques :

Cette rubrique explique également comment appeler la procédure stockée et la fonction suivantes pour créer une vue sémantique à partir d’une spécification de modèle sémantique et obtenir la spécification d’une vue sémantique :

Privilèges requis pour créer une vue sémantique

Pour créer une vue sémantique, vous devez utiliser un rôle disposant des privilèges suivants :

  • CREATE SEMANTIC VIEW sur le schéma dans lequel vous créez la vue sémantique.

  • USAGE sur la base de données et le schéma dans lesquels vous créez la vue sémantique.

  • SELECT sur les tables et les vues utilisées dans la vue sémantique.

Pour plus d’informations sur les privilèges exigés pour interroger une vue sémantique, voir Privilèges requis pour interroger une vue sémantique.

Créer une vue sémantique

Pour créer une vue sémantique, vous pouvez soit :

La vue sémantique doit être valide. Voir Comment Snowflake valide les vues sémantiques.

Les sections suivantes expliquent comment créer un budget personnalisé :

Avec la commande CREATE SEMANTIC VIEW

L’exemple suivant utilise la commande CREATE SEMANTIC VIEW pour créer une vue sémantique.

L’exemple utilise les données d’échantillon TPC-H disponibles dans Snowflake. Cet ensemble de données contient des tables qui représentent un scénario commercial simplifié avec des clients, des commandes et des éléments de ligne.

Modèle de données des tables utilisées dans l'échantillon de données TPC-H

L’exemple crée une vue sémantique nommée tpch_rev_analysis en utilisant les tables de l’ensemble de données TPC-H. La vue sémantique définit :

  • Trois tables logiques (orders, customers et line_items).

  • Une relation entre les tables orders et customers.

  • Une relation entre les tables line_items et orders.

  • Des faits qui seront utilisés pour calculer les métriques.

  • Des dimensions pour le nom du client, la date de la commande et l’année au cours de laquelle la commande a été passée.

  • Les métriques correspondant à la valeur moyenne d’une commande et au nombre de lignes moyen d’une commande.

CREATE SEMANTIC VIEW tpch_rev_analysis

  TABLES (
    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
      PRIMARY KEY (o_orderkey)
      WITH SYNONYMS ('sales orders')
      COMMENT = 'All orders table for the sales domain',
    customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
      PRIMARY KEY (c_custkey)
      COMMENT = 'Main table for customer data',
    line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
      PRIMARY KEY (l_orderkey, l_linenumber)
      COMMENT = 'Line items in orders'
  )

  RELATIONSHIPS (
    orders_to_customers AS
      orders (o_custkey) REFERENCES customers,
    line_item_to_orders AS
      line_items (l_orderkey) REFERENCES orders
  )

  FACTS (
    line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
    orders.count_line_items AS COUNT(line_items.line_item_id),
    line_items.discounted_price AS l_extendedprice * (1 - l_discount)
      COMMENT = 'Extended price after discount'
  )

  DIMENSIONS (
    customers.customer_name AS customers.c_name
      WITH SYNONYMS = ('customer name')
      COMMENT = 'Name of the customer',
    orders.order_date AS o_orderdate
      COMMENT = 'Date when the order was placed',
    orders.order_year AS YEAR(o_orderdate)
      COMMENT = 'Year when the order was placed'
  )

  METRICS (
    customers.customer_count AS COUNT(c_custkey)
      COMMENT = 'Count of number of customers',
    orders.order_average_value AS AVG(orders.o_totalprice)
      COMMENT = 'Average order value across all orders',
    orders.average_line_items_per_order AS AVG(orders.count_line_items)
      COMMENT = 'Average number of line items per order'
  )

  COMMENT = 'Semantic view for revenue analysis';
Copy

Les sections suivantes expliquent cet exemple plus en détail :

Note

Pour un exemple complet, voir Exemple d’utilisation de SQL pour créer une vue sémantique.

Définir les tables logiques

Dans la commande CREATE SEMANTIC VIEW, utilisez la clause TABLES pour définir les tables logiques de la vue. Dans cette clause, vous pouvez :

  • Indiquer le nom de la table physique et un alias facultatif.

  • Identifiez les colonnes suivantes dans la table logique :

    • Les colonnes utilisées comme clés primaires.

    • Les colonnes qui contiennent des valeurs uniques (autres que les colonnes de clé primaire).

    Vous pouvez utiliser ces colonnes pour définir les relations dans cette vue sémantique.

  • Ajouter des synonymes pour la table (afin d’améliorer la découvrabilité).

  • Ajouter un commentaire descriptif.

Note

S’il existe plusieurs façons par lesquelles deux tables peuvent être jointes, vous devez définir une table logique distincte pour chacune de ces manières. Pour plus d’informations, voir Définition de différentes tables logiques pour différents chemins qui joint deux tables.

Dans l”exemple présenté plus haut, la clause TABLES définit trois tables logiques :

  • Une table orders contenant les informations sur les commandes de la table TPC-H orders.

  • Une table customers contenant les informations sur les clients de la table TPC-H customers.

  • Une table line_item contenant les lignes des commandes de la table TPC-H lineitem.

L’exemple identifie les colonnes à utiliser comme clés primaires pour chaque table logique, afin que vous puissiez identifier les relations entre les tables.

L’exemple fournit également des synonymes et des commentaires qui décrivent les tables logiques et facilitent la découverte des données.

TABLES (
  orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
    PRIMARY KEY (o_orderkey)
    WITH SYNONYMS ('sales orders')
    COMMENT = 'All orders table for the sales domain',
  customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
    PRIMARY KEY (c_custkey)
    COMMENT = 'Main table for customer data',
  line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
    PRIMARY KEY (l_orderkey, l_linenumber)
    COMMENT = 'Line items in orders'
Copy

Définition de différentes tables logiques pour différents chemins qui joint deux tables

S’il existe plusieurs chemins que vous pouvez utiliser pour joindre deux tables physiques, vous devez définir des tables logiques et des relations distinctes pour chaque chemin.

Par exemple, dans les données d’échantillonTPC-H disponibles dans Snowflake, il existe deux façons de joindre les tables region et lineitem :

  • region -> nation -> supplier -> partsupp -> lineitem

  • region -> nation -> customer -> orders -> lineitem

Le premier chemin représente la région du fournisseur et le deuxième chemin représente la région du client.

Bien que vous puissiez utiliser une seule table logique pour region et une seule table logique pour nation, vous devez définir des tables logiques distinctes pour la région du fournisseur, la région du client, la pays du fournisseur et la pays du client :

TABLES (
  supplier_region AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.REGION PRIMARY KEY (r_regionkey).
  customer_region AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.REGION PRIMARY KEY (r_regionkey),
  supplier_nation AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NATION PRIMARY KEY (n_nationkey),
  customer_nation AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NATION PRIMARY KEY (n_nationkey),
  ...
)
Copy

Ensuite, définissez des relations distinctes qui représentent les différents chemins :

RELATIONSHIPS (
  supplier_nation (n_regionkey) REFERENCES supplier_region,
  customer_nation (n_regionkey) REFERENCES customer_region,
  ...
)
Copy

Identifier les relations entre les tables logiques

Dans la commande CREATE SEMANTIC VIEW, utilisez la clause RELATIONSHIPS pour identifier les relations entre les tables de la vue. Pour chaque relation, vous spécifiez :

  • Un nom facultatif pour la relation

  • Le nom de la table logique contenant la clé étrangère

  • Les colonnes de cette table qui définissent la clé étrangère

  • Le nom de la table logique contenant la clé primaire ou les colonnes à valeurs uniques

  • Les colonnes de cette table qui définissent la clé primaire ou qui contiennent des valeurs uniques.

    • Si vous avez déjà spécifié PRIMARY KEY pour la table logique dans la clause TABLES, vous n’avez pas besoin de spécifier la colonne de clé primaire dans la relation.

    • S’il existe un seul mot-clé UNIQUE pour la table logique dans la clause TABLES, vous n’avez pas besoin de spécifier les colonnes correspondantes dans la relation.

Dans l”exemple présenté plus haut, la clause RELATIONSHIPS spécifie deux relations :

  • Une relation entre les tables orders et customers. Dans la table orders, o_custkey est la clé étrangère qui renvoie à la clé primaire de la table customers (c_custkey).

  • Une relation entre les tables line_items et orders. Dans la table line_items, l_orderkey est la clé étrangère qui renvoie à la clé primaire de la table orders (o_orderkey).

RELATIONSHIPS (
  orders_to_customers AS
    orders (o_custkey) REFERENCES customers (c_custkey),
  line_item_to_orders AS
    line_items (l_orderkey) REFERENCES orders (o_orderkey)
)
Copy

Définir les faits, les dimensions et les métriques

Dans la commande CREATE SEMANTIC VIEW, utilisez les clauses FACTS, DIMENSIONS et METRICS pour définir les faits, les dimensions et les métriques de la vue sémantique.

Vous devez définir au moins une dimension ou une métrique dans la vue sémantique.

Pour chaque fait, dimension ou métrique, vous spécifiez :

  • La table logique à laquelle il appartient

  • Un nom pour le fait, la dimension ou la métrique

  • L’expression SQL pour le calculer

  • Des synonymes et commentaires facultatifs

L”exemple présenté plus haut définit plusieurs faits, dimensions et mesures :

FACTS (
  line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
  orders.count_line_items AS COUNT(line_items.line_item_id),
  line_items.discounted_price AS l_extendedprice * (1 - l_discount)
    COMMENT = 'Extended price after discount'
)

DIMENSIONS (
  customers.customer_name AS customers.c_name
    WITH SYNONYMS = ('customer name')
    COMMENT = 'Name of the customer',
  orders.order_date AS o_orderdate
    COMMENT = 'Date when the order was placed',
  orders.order_year AS YEAR(o_orderdate)
    COMMENT = 'Year when the order was placed'
)

METRICS (
  customers.customer_count AS COUNT(c_custkey)
    COMMENT = 'Count of number of customers',
  orders.order_average_value AS AVG(orders.o_totalprice)
    COMMENT = 'Average order value across all orders',
  orders.average_line_items_per_order AS AVG(orders.count_line_items)
    COMMENT = 'Average number of line items per order'
)
Copy

Note

Pour des directives supplémentaires sur la définition des métriques qui utilisent des fonctions de fenêtre, voir Définition et requête des métriques des fonctions de fenêtre.

Marquer un fait ou une métrique comme privé

Si vous définissez un fait ou un indicateur uniquement pour une utilisation dans les calculs de la vue sémantique et que vous ne souhaitez pas que le fait ou la métrique soit renvoyé dans une requête, vous pouvez spécifier le mot-clé PRIVATE pour marquer le fait ou la métrique comme privé. Par exemple :

FACTS (
  PRIVATE my_private_fact AS ...
)

METRICS (
  PRIVATE my_private_metric AS ...
)
Copy

Note

Vous ne pouvez pas marquer une dimension comme privée. Les dimensions sont toujours publiques.

Lorsque vous interrogez une vue sémantique comportant des faits ou des métriques privés, vous ne pouvez pas spécifier de fait ou de métrique privé dans les clauses suivantes :

Certaines commandes et fonctions incluent des faits et des métriques privés :

Certaines commandes et fonctions incluent des faits et des métriques privés uniquement dans des conditions spécifiques :

Les autres commandes et fonctions n’incluent pas de faits et de métriques privés :

Création d’une vue sémantique à partir d’une spécification YAML

Pour créer une vue sémantique à partir d’une spécificationYAML pour un modèle sémantique, vous pouvez appeler la procédure stockée SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML.

Tout d’abord, passez TRUE comme troisième argument pour vérifier que vous pouvez créer la vue sémantique à partir de la spécification YAML.

L’exemple suivant vérifie que vous pouvez utiliser une spécification de modèle sémantique donnée dans YAML pour créer une vue sémantique nommée tpch_analysis dans la base de données my_db et le schéma my_schema :

CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(
  'my_db.my_schema',
  $$
  name: TPCH_REV_ANALYSIS
  description: Semantic view for revenue analysis
  tables:
    - name: CUSTOMERS
      description: Main table for customer data
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: CUSTOMER
      primary_key:
        columns:
          - C_CUSTKEY
      dimensions:
        - name: CUSTOMER_NAME
          synonyms:
            - customer name
          description: Name of the customer
          expr: customers.c_name
          data_type: VARCHAR(25)
        - name: C_CUSTKEY
          expr: C_CUSTKEY
          data_type: VARCHAR(134217728)
      metrics:
        - name: CUSTOMER_COUNT
          description: Count of number of customers
          expr: COUNT(c_custkey)
    - name: LINE_ITEMS
      description: Line items in orders
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: LINEITEM
      primary_key:
        columns:
          - L_ORDERKEY
          - L_LINENUMBER
      dimensions:
        - name: L_ORDERKEY
          expr: L_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: L_LINENUMBER
          expr: L_LINENUMBER
          data_type: VARCHAR(134217728)
      facts:
        - name: DISCOUNTED_PRICE
          description: Extended price after discount
          expr: l_extendedprice * (1 - l_discount)
          data_type: "NUMBER(25,4)"
        - name: LINE_ITEM_ID
          expr: "CONCAT(l_orderkey, '-', l_linenumber)"
          data_type: VARCHAR(134217728)
    - name: ORDERS
      synonyms:
        - sales orders
      description: All orders table for the sales domain
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: ORDERS
      primary_key:
        columns:
          - O_ORDERKEY
      dimensions:
        - name: ORDER_DATE
          description: Date when the order was placed
          expr: o_orderdate
          data_type: DATE
        - name: ORDER_YEAR
          description: Year when the order was placed
          expr: YEAR(o_orderdate)
          data_type: "NUMBER(4,0)"
        - name: O_ORDERKEY
          expr: O_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: O_CUSTKEY
          expr: O_CUSTKEY
          data_type: VARCHAR(134217728)
      facts:
        - name: COUNT_LINE_ITEMS
          expr: COUNT(line_items.line_item_id)
          data_type: "NUMBER(18,0)"
      metrics:
        - name: AVERAGE_LINE_ITEMS_PER_ORDER
          description: Average number of line items per order
          expr: AVG(orders.count_line_items)
        - name: ORDER_AVERAGE_VALUE
          description: Average order value across all orders
          expr: AVG(orders.o_totalprice)
  relationships:
    - name: LINE_ITEM_TO_ORDERS
      left_table: LINE_ITEMS
      right_table: ORDERS
      relationship_columns:
        - left_column: L_ORDERKEY
          right_column: O_ORDERKEY
      relationship_type: many_to_one
    - name: ORDERS_TO_CUSTOMERS
      left_table: ORDERS
      right_table: CUSTOMERS
      relationship_columns:
        - left_column: O_CUSTKEY
          right_column: C_CUSTKEY
      relationship_type: many_to_one
  $$,
TRUE);
Copy

Si la spécification est valide, la procédure stockée renvoie le message suivant :

+----------------------------------------------------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML                                            |
|----------------------------------------------------------------------------------|
| YAML file is valid for creating a semantic view. No object has been created yet. |
+----------------------------------------------------------------------------------+

Si la syntaxe YAML n’est pas valide, la procédure stockée lève une exception. Par exemple, s’il manque un deux-points :

relationships
  - name: LINE_ITEM_TO_ORDERS
Copy

la procédure stockée lève une exception, indiquant que la syntaxe YAML n’est pas valide :

392400 (22023): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  Invalid semantic model YAML: while scanning a simple key
   in 'reader', line 90, column 3:
        relationships
        ^
  could not find expected ':'
   in 'reader', line 91, column 11:
          - name: LINE_ITEM_TO_ORDERS
                ^

Si la spécification fait référence à une table physique qui n’existe pas, la procédure stockée lève une exception :

base_table:
  database: SNOWFLAKE_SAMPLE_DATA
  schema: TPCH_SF1
  table: NONEXISTENT
Copy
002003 (42S02): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  SQL compilation error:
  Table 'SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.NONEXISTENT' does not exist or not authorized.

De même, si la spécification fait référence à une colonne de clé primaire qui n’existe pas, la procédure stockée lève une exception :

primary_key:
  columns:
    - NONEXISTENT
Copy
000904 (42000): Uncaught exception of type 'EXPRESSION_ERROR' on line 3 at position 23 :
  SQL compilation error: error line 0 at position -1
  invalid identifier 'NONEXISTENT'

Vous pouvez ensuite appeler la procédure stockée sans transmettre le troisième argument pour créer la vue sémantique.

L’exemple suivant crée une vue sémantique nommée tpch_analysis dans la base de données my_db et le schéma my_schema :

CALL SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML(
  'my_db.my_schema',
  $$
  name: TPCH_REV_ANALYSIS
  description: Semantic view for revenue analysis
  tables:
    - name: CUSTOMERS
      description: Main table for customer data
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: CUSTOMER
      primary_key:
        columns:
          - C_CUSTKEY
      dimensions:
        - name: CUSTOMER_NAME
          synonyms:
            - customer name
          description: Name of the customer
          expr: customers.c_name
          data_type: VARCHAR(25)
        - name: C_CUSTKEY
          expr: C_CUSTKEY
          data_type: VARCHAR(134217728)
      metrics:
        - name: CUSTOMER_COUNT
          description: Count of number of customers
          expr: COUNT(c_custkey)
    - name: LINE_ITEMS
      description: Line items in orders
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: LINEITEM
      primary_key:
        columns:
          - L_ORDERKEY
          - L_LINENUMBER
      dimensions:
        - name: L_ORDERKEY
          expr: L_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: L_LINENUMBER
          expr: L_LINENUMBER
          data_type: VARCHAR(134217728)
      facts:
        - name: DISCOUNTED_PRICE
          description: Extended price after discount
          expr: l_extendedprice * (1 - l_discount)
          data_type: "NUMBER(25,4)"
        - name: LINE_ITEM_ID
          expr: "CONCAT(l_orderkey, '-', l_linenumber)"
          data_type: VARCHAR(134217728)
    - name: ORDERS
      synonyms:
        - sales orders
      description: All orders table for the sales domain
      base_table:
        database: SNOWFLAKE_SAMPLE_DATA
        schema: TPCH_SF1
        table: ORDERS
      primary_key:
        columns:
          - O_ORDERKEY
      dimensions:
        - name: ORDER_DATE
          description: Date when the order was placed
          expr: o_orderdate
          data_type: DATE
        - name: ORDER_YEAR
          description: Year when the order was placed
          expr: YEAR(o_orderdate)
          data_type: "NUMBER(4,0)"
        - name: O_ORDERKEY
          expr: O_ORDERKEY
          data_type: VARCHAR(134217728)
        - name: O_CUSTKEY
          expr: O_CUSTKEY
          data_type: VARCHAR(134217728)
      facts:
        - name: COUNT_LINE_ITEMS
          expr: COUNT(line_items.line_item_id)
          data_type: "NUMBER(18,0)"
      metrics:
        - name: AVERAGE_LINE_ITEMS_PER_ORDER
          description: Average number of line items per order
          expr: AVG(orders.count_line_items)
        - name: ORDER_AVERAGE_VALUE
          description: Average order value across all orders
          expr: AVG(orders.o_totalprice)
  relationships:
    - name: LINE_ITEM_TO_ORDERS
      left_table: LINE_ITEMS
      right_table: ORDERS
      relationship_columns:
        - left_column: L_ORDERKEY
          right_column: O_ORDERKEY
      relationship_type: many_to_one
    - name: ORDERS_TO_CUSTOMERS
      left_table: ORDERS
      right_table: CUSTOMERS
      relationship_columns:
        - left_column: O_CUSTKEY
          right_column: C_CUSTKEY
      relationship_type: many_to_one
  $$
);
Copy
+-----------------------------------------+
| SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML   |
|-----------------------------------------|
| Semantic view was successfully created. |
+-----------------------------------------+

Modification du commentaire d’une vue sémantique existante

Pour modifier le commentaire d’une vue sémantique existante, exécutez la commande ALTER SEMANTIC VIEW. Par exemple :

ALTER SEMANTIC VIEW my_semantic_view SET COMMENT = 'my comment';
Copy

Note

Vous ne pouvez pas utiliser la commande ALTER SEMANTIC VIEW pour modifier des propriétés autres que le commentaire. Pour modifier d’autres propriétés de la vue sémantique, remplacez la vue sémantique. Voir Remplacer une vue sémantique existante.

Vous pouvez également utiliser la commande COMMENT pour définir un commentaire pour une vue sémantique :

COMMENT ON SEMANTIC VIEW my_semantic_view IS 'my comment';
Copy

Remplacer une vue sémantique existante

Pour remplacer une vue sémantique existante (par exemple, pour modifier la définition de la vue), indiquez OR REPLACE lors de l’exécution de CREATE SEMANTIC VIEW. Si vous souhaitez préserver les privilèges accordés à la vue sémantique existante, indiquez COPY GRANTS. Par exemple :

CREATE OR REPLACE SEMANTIC VIEW tpch_rev_analysis

  TABLES (
    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS
      PRIMARY KEY (o_orderkey)
      WITH SYNONYMS ('sales orders')
      COMMENT = 'All orders table for the sales domain',
    customers AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER
      PRIMARY KEY (c_custkey)
      COMMENT = 'Main table for customer data',
    line_items AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM
      PRIMARY KEY (l_orderkey, l_linenumber)
      COMMENT = 'Line items in orders'
  )

  RELATIONSHIPS (
    orders_to_customers AS
      orders (o_custkey) REFERENCES customers,
    line_item_to_orders AS
      line_items (l_orderkey) REFERENCES orders
  )

  FACTS (
    line_items.line_item_id AS CONCAT(l_orderkey, '-', l_linenumber),
    orders.count_line_items AS COUNT(line_items.line_item_id),
    line_items.discounted_price AS l_extendedprice * (1 - l_discount)
      COMMENT = 'Extended price after discount'
  )

  DIMENSIONS (
    customers.customer_name AS customers.c_name
      WITH SYNONYMS = ('customer name')
      COMMENT = 'Name of the customer',
    orders.order_date AS o_orderdate
      COMMENT = 'Date when the order was placed',
    orders.order_year AS YEAR(o_orderdate)
      COMMENT = 'Year when the order was placed'
  )

  METRICS (
    customers.customer_count AS COUNT(c_custkey)
      COMMENT = 'Count of number of customers',
    orders.order_average_value AS AVG(orders.o_totalprice)
      COMMENT = 'Average order value across all orders',
    orders.average_line_items_per_order AS AVG(orders.count_line_items)
      COMMENT = 'Average number of line items per order'
  )

  COMMENT = 'Semantic view for revenue analysis and different comment'
  COPY GRANTS;
Copy

Lister les vues sémantiques

Pour dresser la liste des vues sémantiques du schéma actuel ou d’un schéma spécifié, exécutez la commande SHOW SEMANTIC VIEWS. Par exemple :

SHOW SEMANTIC VIEWS;
Copy
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+
| created_on                    | name                  | database_name | schema_name       | comment                                      | owner           | owner_role_type | extension |
|-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------|
| 2025-03-20 15:06:34.039 -0700 | MY_NEW_SEMANTIC_MODEL | MY_DB         | MY_SCHEMA         | A semantic model created through the wizard. | MY_ROLE         | ROLE            | ["CA"]    |
| 2025-02-28 16:16:04.002 -0800 | O_TPCH_SEMANTIC_VIEW  | MY_DB         | MY_SCHEMA         | NULL                                         | MY_ROLE         | ROLE            | NULL      |
| 2025-03-21 07:03:54.120 -0700 | TPCH_REV_ANALYSIS     | MY_DB         | MY_SCHEMA         | Semantic view for revenue analysis           | MY_ROLE         | ROLE            | NULL      |
+-------------------------------+-----------------------+---------------+-------------------+----------------------------------------------+-----------------+-----------------+-----------+

Vous pouvez également interroger les vues sémantiques des schémas ACCOUNT_USAGE et INFORMATION_SCHEMA.

Dimensions et métriques de l’annonce

Pour dresser la liste des dimensions et des métriques disponibles dans une vue, un schéma, une base de données ou un compte, vous pouvez exécuter les commandes SHOW SEMANTIC DIMENSIONS et SHOW SEMANTIC METRICS.

Par défaut, les commandes répertorient les dimensions et les métriques disponibles dans les vues sémantiques définies dans le schéma actuel :

SHOW SEMANTIC DIMENSIONS;
Copy
+---------------+-------------+--------------------+------------+---------------+--------------+-------------------+--------------------------------+
| database_name | schema_name | semantic_view_name | table_name | name          | data_type    | synonyms          | comment                        |
|---------------+-------------+--------------------+------------+---------------+--------------+-------------------+--------------------------------|
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | CUSTOMER_NAME | VARCHAR(25)  | ["customer name"] | Name of the customer           |
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | C_CUSTKEY     | NUMBER(38,0) | NULL              | NULL                           |
...

SHOW SEMANTIC METRICS;
Copy
+---------------+-------------+--------------------+------------+------------------------------+--------------+----------+----------------------------------------+
| database_name | schema_name | semantic_view_name | table_name | name                         | data_type    | synonyms | comment                                |
|---------------+-------------+--------------------+------------+------------------------------+--------------+----------+----------------------------------------|
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | CUSTOMERS  | CUSTOMER_COUNT               | NUMBER(18,0) | NULL     | Count of number of customers           |
| MY_DB         | MY_SCHEMA   | TPCH_REV_ANALYSIS  | ORDERS     | AVERAGE_LINE_ITEMS_PER_ORDER | NUMBER(36,6) | NULL     | Average number of line items per order |
...

Vous pouvez modifier le champ d’application pour répertorier les dimensions et les métriques définies dans ce qui suit :

  • Vues sémantiques dans la base de données actuelle :

    SHOW SEMANTIC DIMENSIONS IN DATABASE;

SHOW SEMANTIC METRICS IN DATABASE;
    Copy

  • Vues sémantiques dans des schémas ou des bases de données spécifiques.

    SHOW SEMANTIC DIMENSIONS IN SCHEMA my_db.my_other_schema;

SHOW SEMANTIC DIMENSIONS IN DATABASE my_db;

SHOW SEMANTIC METRICS IN SCHEMA my_db.my_other_schema;

SHOW SEMANTIC METRICS IN DATABASE my_db;
    Copy

  • Vues sémantiques dans le compte.

    SHOW SEMANTIC DIMENSIONS IN ACCOUNT;

SHOW SEMANTIC METRICS IN ACCOUNT;
    Copy

  • Une vue sémantique spécifique :

    SHOW SEMANTIC DIMENSIONS IN my_semantic_view;
    Copy

Si vous interrogez une vue sémantique, vous pouvez utiliser la commande SHOW SEMANTIC DIMENSIONS FOR METRIC pour déterminer les dimensions que vous pouvez renvoyer lorsque vous spécifiez une métrique donnée. Pour plus de détails, voir Choix des dimensions que vous pouvez renvoyer pour une métrique donnée.

Afficher les détails d’une vue sémantique

Pour voir les détails d’une vue sémantique, exécutez la commande DESCRIBE SEMANTIC VIEW. Par exemple :

DESCRIBE SEMANTIC VIEW tpch_rev_analysis;
Copy
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+
| object_kind  | object_name                  | parent_entity | property                 | property_value                         |
|--------------+------------------------------+---------------+--------------------------+----------------------------------------|
| NULL         | NULL                         | NULL          | COMMENT                  | Semantic view for revenue analysis     |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | CUSTOMERS                    | NULL          | BASE_TABLE_NAME          | CUSTOMER                               |
| TABLE        | CUSTOMERS                    | NULL          | PRIMARY_KEY              | ["C_CUSTKEY"]                          |
| TABLE        | CUSTOMERS                    | NULL          | COMMENT                  | Main table for customer data           |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | TABLE                    | CUSTOMERS                              |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | EXPRESSION               | customers.c_name                       |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | DATA_TYPE                | VARCHAR(25)                            |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | SYNONYMS                 | ["customer name"]                      |
| DIMENSION    | CUSTOMER_NAME                | CUSTOMERS     | COMMENT                  | Name of the customer                   |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | LINE_ITEMS                   | NULL          | BASE_TABLE_NAME          | LINEITEM                               |
| TABLE        | LINE_ITEMS                   | NULL          | PRIMARY_KEY              | ["L_ORDERKEY","L_LINENUMBER"]          |
| TABLE        | LINE_ITEMS                   | NULL          | COMMENT                  | Line items in orders                   |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | REF_TABLE                | ORDERS                                 |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | FOREIGN_KEY              | ["L_ORDERKEY"]                         |
| RELATIONSHIP | LINE_ITEM_TO_ORDERS          | LINE_ITEMS    | REF_KEY                  | ["O_ORDERKEY"]                         |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | EXPRESSION               | l_extendedprice * (1 - l_discount)     |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | DATA_TYPE                | NUMBER(25,4)                           |
| FACT         | DISCOUNTED_PRICE             | LINE_ITEMS    | COMMENT                  | Extended price after discount          |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | TABLE                    | LINE_ITEMS                             |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | EXPRESSION               | CONCAT(l_orderkey, '-', l_linenumber)  |
| FACT         | LINE_ITEM_ID                 | LINE_ITEMS    | DATA_TYPE                | VARCHAR(134217728)                     |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_DATABASE_NAME | SNOWFLAKE_SAMPLE_DATA                  |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_SCHEMA_NAME   | TPCH_SF1                               |
| TABLE        | ORDERS                       | NULL          | BASE_TABLE_NAME          | ORDERS                                 |
| TABLE        | ORDERS                       | NULL          | SYNONYMS                 | ["sales orders"]                       |
| TABLE        | ORDERS                       | NULL          | PRIMARY_KEY              | ["O_ORDERKEY"]                         |
| TABLE        | ORDERS                       | NULL          | COMMENT                  | All orders table for the sales domain  |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | TABLE                    | ORDERS                                 |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | REF_TABLE                | CUSTOMERS                              |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | FOREIGN_KEY              | ["O_CUSTKEY"]                          |
| RELATIONSHIP | ORDERS_TO_CUSTOMERS          | ORDERS        | REF_KEY                  | ["C_CUSTKEY"]                          |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | TABLE                    | ORDERS                                 |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | EXPRESSION               | AVG(orders.count_line_items)           |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | DATA_TYPE                | NUMBER(36,6)                           |
| METRIC       | AVERAGE_LINE_ITEMS_PER_ORDER | ORDERS        | COMMENT                  | Average number of line items per order |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | TABLE                    | ORDERS                                 |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | EXPRESSION               | COUNT(line_items.line_item_id)         |
| FACT         | COUNT_LINE_ITEMS             | ORDERS        | DATA_TYPE                | NUMBER(18,0)                           |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | TABLE                    | ORDERS                                 |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | EXPRESSION               | AVG(orders.o_totalprice)               |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | DATA_TYPE                | NUMBER(30,8)                           |
| METRIC       | ORDER_AVERAGE_VALUE          | ORDERS        | COMMENT                  | Average order value across all orders  |
| DIMENSION    | ORDER_DATE                   | ORDERS        | TABLE                    | ORDERS                                 |
| DIMENSION    | ORDER_DATE                   | ORDERS        | EXPRESSION               | o_orderdate                            |
| DIMENSION    | ORDER_DATE                   | ORDERS        | DATA_TYPE                | DATE                                   |
| DIMENSION    | ORDER_DATE                   | ORDERS        | COMMENT                  | Date when the order was placed         |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | TABLE                    | ORDERS                                 |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | EXPRESSION               | YEAR(o_orderdate)                      |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | DATA_TYPE                | NUMBER(4,0)                            |
| DIMENSION    | ORDER_YEAR                   | ORDERS        | COMMENT                  | Year when the order was placed         |
+--------------+------------------------------+---------------+--------------------------+----------------------------------------+

Récupérer l’instruction SQL correspondant à une vue sémantique

Vous pouvez appeler la fonction GET_DDL pour récupérer l’instruction DDL qui a créé une vue sémantique.

Note

Pour appeler cette fonction de vue sémantique, vous devez utiliser un rôle qui s’est vu accorder le privilège REFERENCES ou OWNERSHIP sur la vue sémantique.

Lorsque vous appelez GET_DDL, indiquez 'SEMANTIC_VIEW' comme type d’objet. Par exemple :

SELECT GET_DDL('SEMANTIC_VIEW', 'tpch_rev_analysis', TRUE);
Copy
+-----------------------------------------------------------------------------------+
| GET_DDL('SEMANTIC_VIEW', 'TPCH_REV_ANALYSIS', TRUE)                               |
|-----------------------------------------------------------------------------------|
| create or replace semantic view DYOSHINAGA_DB.DYOSHINAGA_SCHEMA.TPCH_REV_ANALYSIS |
|     tables (                                                                                                                                                                       |
|             ORDERS primary key (O_ORDERKEY) with synonyms=('sales orders') comment='All orders table for the sales domain',                                                                                                                                                                       |
|             CUSTOMERS as CUSTOMER primary key (C_CUSTKEY) comment='Main table for customer data',                                                                                                                                                                       |
|             LINE_ITEMS as LINEITEM primary key (L_ORDERKEY,L_LINENUMBER) comment='Line items in orders'                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     relationships (                                                                                                                                                                       |
|             ORDERS_TO_CUSTOMERS as ORDERS(O_CUSTKEY) references CUSTOMERS(C_CUSTKEY),                                                                                                                                                                       |
|             LINE_ITEM_TO_ORDERS as LINE_ITEMS(L_ORDERKEY) references ORDERS(O_ORDERKEY)                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     facts (                                                                                                                                                                       |
|             ORDERS.COUNT_LINE_ITEMS as COUNT(line_items.line_item_id),                                                                                                                                                                       |
|             LINE_ITEMS.DISCOUNTED_PRICE as l_extendedprice * (1 - l_discount) comment='Extended price after discount',                                                                                                                                                                       |
|             LINE_ITEMS.LINE_ITEM_ID as CONCAT(l_orderkey, '-', l_linenumber)                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     dimensions (                                                                                                                                                                       |
|             ORDERS.ORDER_DATE as o_orderdate comment='Date when the order was placed',                                                                                                                                                                       |
|             ORDERS.ORDER_YEAR as YEAR(o_orderdate) comment='Year when the order was placed',                                                                                                                                                                       |
|             CUSTOMERS.CUSTOMER_NAME as customers.c_name with synonyms=('customer name') comment='Name of the customer'                                                                                                                                                                       |
|     )                                                                                                                                                                       |
|     metrics (                                                                                                                                                                       |
|             ORDERS.AVERAGE_LINE_ITEMS_PER_ORDER as AVG(orders.count_line_items) comment='Average number of line items per order',                                                                                                                                                                       |
|             ORDERS.ORDER_AVERAGE_VALUE as AVG(orders.o_totalprice) comment='Average order value across all orders'                                                                                                                                                                       |
|     );                                                                                                                                                                       |
+-----------------------------------------------------------------------------------+

La valeur de retour comprend faits et métriques privés (faits et métriques qui sont marqués avec le mot-clé PRIVATE).

Obtenir la spécification YAML pour une vue sémantique

Pour obtenir la spécification YAML d’un modèle sémantique pour une vue sémantique, appelez la fonction SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW.

L’exemple suivant renvoie la spécification YAML pour la vue sémantique nommée tpch_analysis dans la base de données my_db et le schéma my_schema :

SELECT SYSTEM$READ_YAML_FROM_SEMANTIC_VIEW(
  'my_db.my_schema.tpch_rev_analysis'
);
Copy
+-------------------------------------------------------------+
| READ_YAML_FROM_SEMANTIC_VIEW                                |
|-------------------------------------------------------------|
| name: TPCH_REV_ANALYSIS                                     |
| description: Semantic view for revenue analysis             |
| tables:                                                     |
|   - name: CUSTOMERS                                         |
|     description: Main table for customer data               |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: CUSTOMER                                       |
|     primary_key:                                            |
|       columns:                                              |
|         - C_CUSTKEY                                         |
|     dimensions:                                             |
|       - name: CUSTOMER_NAME                                 |
|         synonyms:                                           |
|           - customer name                                   |
|         description: Name of the customer                   |
|         expr: customers.c_name                              |
|         data_type: VARCHAR(25)                              |
|       - name: C_CUSTKEY                                     |
|         expr: C_CUSTKEY                                     |
|         data_type: VARCHAR(134217728)                       |
|   - name: LINE_ITEMS                                        |
|     description: Line items in orders                       |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: LINEITEM                                       |
|     primary_key:                                            |
|       columns:                                              |
|         - L_ORDERKEY                                        |
|         - L_LINENUMBER                                      |
|     dimensions:                                             |
|       - name: L_ORDERKEY                                    |
|         expr: L_ORDERKEY                                    |
|         data_type: VARCHAR(134217728)                       |
|       - name: L_LINENUMBER                                  |
|         expr: L_LINENUMBER                                  |
|         data_type: VARCHAR(134217728)                       |
|     facts:                                                  |
|       - name: DISCOUNTED_PRICE                              |
|         description: Extended price after discount          |
|         expr: l_extendedprice * (1 - l_discount)            |
|         data_type: "NUMBER(25,4)"                           |
|       - name: LINE_ITEM_ID                                  |
|         expr: "CONCAT(l_orderkey, '-', l_linenumber)"       |
|         data_type: VARCHAR(134217728)                       |
|   - name: ORDERS                                            |
|     synonyms:                                               |
|       - sales orders                                        |
|     description: All orders table for the sales domain      |
|     base_table:                                             |
|       database: SNOWFLAKE_SAMPLE_DATA                       |
|       schema: TPCH_SF1                                      |
|       table: ORDERS                                         |
|     primary_key:                                            |
|       columns:                                              |
|         - O_ORDERKEY                                        |
|     dimensions:                                             |
|       - name: ORDER_DATE                                    |
|         description: Date when the order was placed         |
|         expr: o_orderdate                                   |
|         data_type: DATE                                     |
|       - name: ORDER_YEAR                                    |
|         description: Year when the order was placed         |
|         expr: YEAR(o_orderdate)                             |
|         data_type: "NUMBER(4,0)"                            |
|       - name: O_ORDERKEY                                    |
|         expr: O_ORDERKEY                                    |
|         data_type: VARCHAR(134217728)                       |
|       - name: O_CUSTKEY                                     |
|         expr: O_CUSTKEY                                     |
|         data_type: VARCHAR(134217728)                       |
|     facts:                                                  |
|       - name: COUNT_LINE_ITEMS                              |
|         expr: COUNT(line_items.line_item_id)                |
|         data_type: "NUMBER(18,0)"                           |
|     metrics:                                                |
|       - name: AVERAGE_LINE_ITEMS_PER_ORDER                  |
|         description: Average number of line items per order |
|         expr: AVG(orders.count_line_items)                  |
|       - name: ORDER_AVERAGE_VALUE                           |
|         description: Average order value across all orders  |
|         expr: AVG(orders.o_totalprice)                      |
| relationships:                                              |
|   - name: LINE_ITEM_TO_ORDERS                               |
|     left_table: LINE_ITEMS                                  |
|     right_table: ORDERS                                     |
|     relationship_columns:                                   |
|       - left_column: L_ORDERKEY                             |
|         right_column: O_ORDERKEY                            |
|   - name: ORDERS_TO_CUSTOMERS                               |
|     left_table: ORDERS                                      |
|     right_table: CUSTOMERS                                  |
|     relationship_columns:                                   |
|       - left_column: O_CUSTKEY                              |
|         right_column: C_CUSTKEY                             |
|                                                             |
+-------------------------------------------------------------+

Supprimer une vue sémantique

Pour supprimer une vue sémantique, exécutez la commande DROP SEMANTIC VIEW. Par exemple :

DROP SEMANTIC VIEW tpch_rev_analysis;
Copy

Octroyer des privilèges sur des vues sémantiques

Privilèges de la vue sémantique liste les privilèges que vous pouvez accorder à une vue sémantique.

Pour travailler avec une vue sémantique, vous devez obligatoirement disposer des privilèges suivants sur cette vue :

  • Tout privilège (par exemple, REFERENCES OR SELECT) est nécessaire pour exécuter la commande DESCRIBE SEMANTIC VIEW sur la vue.

  • SELECT est nécessaire pour exécuter SELECT ... FROM SEMANTIC_VIEW().

  • L’un ou l’autre de ces privilèges est exigé pour afficher la vue dans la sortie de la commande SHOW SEMANTIC VIEWS.

Note

Pour interroger une vue sémantique, vous n’avez pas besoin du privilège SELECT sur les tables utilisées dans la vue sémantique. Vous n’avez besoin que du privilège SELECT sur la vue sémantique elle-même.

Ce comportement est cohérent avec les privilèges requis pour interroger les vues standard.

Pour utiliser une vue sémantique dont vous n’êtes pas propriétaire dans Cortex Analyst, vous devez utiliser un rôle qui possède les privilèges REFERENCES et SELECT sur cette vue.

Pour accorder les privilèges REFERENCES et SELECT sur une vue sémantique, utilisez la commande GRANT <privilèges> … TO ROLE. Par exemple, pour accorder au rôle my_analyst_role les privilèges REFERENCES et SELECT sur la vue sémantique nommée my_semantic_view, vous pouvez exécuter l’instruction suivante :

GRANT REFERENCES, SELECT ON SEMANTIC VIEW my_semantic_view TO ROLE my_analyst_role;
Copy

Si vous disposez d’un schéma contenant des vues sémantiques que vous souhaitez partager avec les utilisateurs de Cortex Analyst, vous pouvez utiliser des autorisations futures pour accorder les privilèges sur toute vue sémantique que vous créez dans ce schéma. Par exemple :

GRANT REFERENCES, SELECT ON FUTURE SEMANTIC VIEWS IN SCHEMA my_schema TO ROLE my_analyst_role;
Copy
Langage: Français