CREATE SEMANTIC VIEW

Crée une nouvelle vue sémantique dans le schéma actuel/spécifié.

La vue sémantique doit être conforme à ces règles de validation.

Voir aussi ::

ALTER SEMANTIC VIEW , DESCRIBE SEMANTIC VIEW , DROP SEMANTIC VIEW , SHOW SEMANTIC VIEWS , SHOW SEMANTIC DIMENSIONS , SHOW SEMANTIC DIMENSIONS FOR METRIC , SHOW SEMANTIC FACTS , SHOW SEMANTIC METRICS , SYSTEM$CREATE_SEMANTIC_VIEW_FROM_YAML

Syntaxe

CREATE [ OR REPLACE ] SEMANTIC VIEW [ IF NOT EXISTS ] <name>
  TABLES ( logicalTable [ , ... ] )
  [ RELATIONSHIPS ( relationshipDef [ , ... ] ) ]
  [ FACTS ( factExpression [ , ... ] ) ]
  [ DIMENSIONS ( dimensionExpression [ , ... ] ) ]
  [ METRICS ( { metricExpression | windowFunctionMetricExpression } [ , ... ] ) ]
  [ COMMENT = '<comment_about_semantic_view>' ]
  [ AI_SQL_GENERATION '<instructions_for_sql_generation>' ]
  [ AI_QUESTION_CATEGORIZATION '<instructions_for_question_categorization>' ]
  [ COPY GRANTS ]

où :

  • Les paramètres pour les tables logiques sont :

    logicalTable ::=
  [ <table_alias> AS ] <table_name>
  [ PRIMARY KEY ( <primary_key_column_name> [ , ... ] ) ]
  [
    UNIQUE ( <unique_column_name> [ , ... ] )
    [ ... ]
  ]
  [
    CONSTRAINT [ <constraint_name> ]
      DISTINCT RANGE BETWEEN <start_column> AND <end_column> EXCLUSIVE
  ]
  [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
  [ COMMENT = '<comment_about_table>' ]

  • Les paramètres pour les relations sont :

    relationshipDef ::=
  [ <relationship_identifier> AS ]
  <table_alias> ( <column_name> [ , ... ] )
  REFERENCES
  <ref_table_alias> [ (
    [ ASOF ] <ref_column_name> [ , ... ] |
    BETWEEN <start_column> AND <end_column> EXCLUSIVE
  ) ]

  • Les paramètres pour les expressions dans les définitions des faits sont :

    factExpression ::=
  [ { PRIVATE | PUBLIC } ] <table_alias>.<fact> AS <sql_expr>
  [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
  [ COMMENT = '<comment_about_the_fact>' ]

  • Les paramètres pour les expressions dans les définitions des dimensions sont :

    dimensionExpression ::=
  [ PUBLIC ] <table_alias>.<dimension> AS <sql_expr>
  [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
  [ COMMENT = '<comment_about_the_dimension>' ]
  [ WITH CORTEX SEARCH SERVICE <search_service_name> [ USING <search_service_column_name> ] ]

  • Les paramètres pour les expressions dans les définitions des métriques sont :

    metricExpression ::=
  [ { PRIVATE | PUBLIC } ] <table_alias>.<metric>
    [ USING ( <relationship_name> [ , ... ] ) ]
    [
      NON ADDITIVE BY (
        <dimension> [ { ASC | DESC } ] [ NULLS { FIRST | LAST } ]
        [ , ... ]
      )
    ]
    AS <sql_expr>
  [ WITH SYNONYMS [ = ] ( '<synonym>' [ , ... ] ) ]
  [ COMMENT = '<comment_about_the_metric>' ]

  • Vous pouvez définir une métrique qui utilise une fonction de fenêtre (une métrique de fonction de fenêtre) en utilisant la syntaxe suivante :

    windowFunctionMetricExpression ::=
  [ { PRIVATE | PUBLIC } ] <table_alias>.<metric> AS
    <window_function>( <metric> ) OVER (
      [ PARTITION BY { <exprs_using_dimensions_or_metrics> | EXCLUDING <dimensions> } ]
      [ ORDER BY <exprs_using_dimensions_or_metrics> [ ASC | DESC ] [ NULLS { FIRST | LAST } ] [, ...] ]
      [ <windowFrameClause> ]
    )

    Pour plus d’informations sur cette syntaxe, voir Paramètres pour les métriques de la fonction de fenêtre.

Note

L’ordre des clauses est important. Par exemple, vous devez spécifier la clause FACTS avant la clause DIMENSIONS.

Vous pouvez faire référence à des expressions sémantiques définies dans des clauses ultérieures. Par exemple, même si fact_2 est défini après fact_1, vous pouvez toujours utiliser fact_2 dans la définition de fact_1.

Paramètres requis

name

Spécifie le nom de la vue sémantique ; le nom doit être unique pour le schéma dans lequel la table est créée.

De plus, l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (par exemple, "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

Paramètres facultatifs

COMMENT = 'comment_about_semantic_view'

Spécifie un commentaire sur la vue sémantique.

AI_SQL_GENERATION 'instructions_for_sql_generation'

Spécifie les Instructions pour Cortex Analyst qui expliquent comment générer l’instruction SQL.

Pour plus d’informations, voir Fournir des instructions personnalisées pour Cortex Analyst.

AI_QUESTION_CATEGORIZATION 'instructions_for_question_categorization'

Spécifie les Instructions pour Cortex Analyst qui expliquent comment classer les questions.

Pour plus d’informations, voir Fournir des instructions personnalisées pour Cortex Analyst.

COPY GRANTS

Lorsque vous spécifiez OR REPLACE pour remplacer une vue sémantique existante par une nouvelle vue sémantique, vous pouvez définir ce paramètre pour copier tous les privilèges accordés à la vue sémantique existante dans la nouvelle vue sémantique.

La commande copie tous les privilèges accordés à l’exception de OWNERSHIP, de la vue sémantique existante vers la nouvelle vue sémantique. Le rôle qui exécute l’instruction CREATE SEMANTIC VIEW est propriétaire de la nouvelle vue.

La nouvelle vue sémantique n’hérite pas des attributions futures définies pour le type d’objet dans le schéma.

L’opération de copie des attributions s’effectue de manière atomique avec l’instruction CREATE SEMANTIC VIEW (en d’autres termes, au sein de la même transaction).

Si vous omettez COPY GRANTS, la nouvelle vue sémantique n’hérite pas des privilèges d’accès explicites accordés à la vue sémantique existante, mais hérite des futures attributions définies pour le type d’objet dans le schéma.

Paramètres pour les tables logiques

Ces paramètres font partie de la syntaxe pour les tables logiques :

table_alias AS

Spécifie un alias facultatif pour la table logique.

  • Si vous spécifiez un alias, vous devez utiliser cet alias lorsque vous référencez la table logique dans les relations, les faits, les dimensions et les métriques.

  • Si vous ne spécifiez pas d’alias, vous utilisez le nom non qualifié de la table logique pour faire référence à la table.

table_name

Spécifie le nom de la table logique.

PRIMARY KEY ( primary_key_column_name [ , ... ] )

Spécifie les noms d’une ou plusieurs colonnes de la table logique qui servent de clé primaire à la table.

UNIQUE ( unique_column_name [ , ... ] )

Spécifie le nom d’une colonne contenant une valeur unique ou les noms des colonnes qui contiennent des combinaisons uniques de valeurs.

Par exemple, si la colonne service_id contient des valeurs uniques, spécifiez :

TABLES(
  ...
  product_table UNIQUE (service_id)

Si la combinaison des valeurs des colonnes product_area_id et product_id est unique, indiquez-le :

TABLES(
  ...
  product_table UNIQUE (product_area_id, product_id)
  ...

Vous pouvez identifier plusieurs colonnes et plusieurs combinaisons de colonnes comme étant uniques dans une table logique donnée :

TABLES(
  ...
  product_table UNIQUE (product_area_id, product_id) UNIQUE (service_id)
  ...

Note

Si vous avez déjà identifié une colonne comme étant une colonne de clé primaire (en utilisant PRIMARY KEY), n’ajoutez pas la clause UNIQUE pour cette colonne.

CONSTRAINT [ constraint_name ] . DISTINCT RANGE BETWEEN start_column AND end_column EXCLUSIVE

Logo Snowflake en noir (sans texte) Fonctionnalité en avant-première — En accès libre

Disponible pour tous les comptes.

Spécifie une contrainte pour une jointure de plage.

constraint_name

Spécifie un nom facultatif pour la contrainte.

Si vous omettez ce nom, la commande utilise un nom généré par le système pour la contrainte.

DISTINCT RANGE BETWEEN start_column AND end_column EXCLUSIVE spécifie que dans chaque ligne, la plage comprise entre start_column et:samp:{end_column} est une plage distincte :

  • La plage est un `intervalle semi-ouvert<https://en.wikipedia.org/wiki/Interval_(mathematics)#Definitions_and_terminology>`_, où la plage est fermée à gauche (start_column) et ouverte à droite (end_column).

    En d’autres termes, l’heure à gauche est incluse dans la plage, mais l’heure à droite en est exclue.

    Par exemple, pour une ligne de cette table, si la valeur dans:samp:{start_column} est``2024-01-15 00:00:00.000`` et la valeur dans end_column est``2024-02-01 00:00:00.000``, la plage est :

    :samp:` 2024-01-15 00:00:00.000 <= {timestamp_from_other_table} < 2024-02-01 00:00:00.000`

    L’horodatage``2024-01-15 00:00:00.000`` est inclus dans cette plage, mais l’horodatage``2024-02-01 00:00:00.000`` ne l’est pas.

  • start_column et:samp:{end_column} doivent être des colonnes physiques de la même table ou des faits ou des dimensions de la même table.

WITH SYNONYMS [ = ] ( 'synonym' [ , ... ] )

Spécifie un ou plusieurs synonymes pour la table logique. Contrairement aux alias, les synonymes sont utilisés à des fins d’information uniquement. Vous n’utilisez pas de synonymes pour faire référence à la table logique dans les relations, les dimensions, les métriques et les faits.

COMMENT = 'comment_about_table'

Spécifie un commentaire sur la table logique.

Paramètres pour les relations

Ces paramètres font partie de la syntaxe pour les relations :

relationship_identifier AS

Spécifie un identificateur facultatif pour la relation.

table_alias ( column_name [ , ... ] )

Spécifie une des tables logiques et une ou plusieurs de ses colonnes qui font référence à des colonnes d’une autre table logique.

ref_table_alias [ ( ... ) ]

Spécifie l’autre table logique référencée par la première table logique.

Vous pouvez spécifier l’un des éléments suivants entre parenthèses, en fonction de la manière dont vous souhaitez joindre les tables :

ref_column_name [ , ... ]

Spécifie une colonne identifiée par la contrainte PRIMARY KEY ou UNIQUE dans la définition de table logique.

ASOF ref_column_name [ , ... ] )

Pour une jointure ASOF, spécifie une colonne de l’un des types pris en charge.

Note

Vous pouvez spécifier au maximum un mot clé ASOF dans la définition d’une relation donnée. Vous pouvez spécifier ce mot-clé avant n’importe quelle colonne de la liste.

BETWEEN start_column AND end_column EXCLUSIVE

Logo Snowflake en noir (sans texte) Fonctionnalité en avant-première — En accès libre

Disponible pour tous les comptes.

Pour une jointure de plage, spécifie la plage de valeurs possibles dans la première table.

start_column . end_column

Spécifie les colonnes qui définissent le début et la fin de la plage.

Note

column_name doit avoir un type de données qui peut être contraint aux types de données pour start_column et:samp:{end_column}.

Paramètres pour les faits, les dimensions et les métriques

Dans une vue sémantique, vous devez définir au moins une dimension ou une métrique, ce qui signifie que vous devez spécifier au moins la clause DIMENSIONS ou METRICS.

Ces paramètres font partie de la syntaxe pour définir un fait,, une dimension ou une métrique :

{ PRIVATE | PUBLIC }

Indique si un fait ou une métrique est privé ou publique. Les faits et les métriques marqués comme privés ne peuvent pas être interrogés ou utilisés dans une condition de requête.

Note

Vous ne pouvez pas marquer une dimension comme privée. Les dimensions sont toujours publiques. Pour une dimension, l’effet est le même que vous spécifiez ou omettiez PUBLIC.

Si vous omettez PRIVATE et PUBLIC, la dimension, le fait ou la métrique est public par défaut.

table_alias.semantic_expression_name

Spécifie un nom pour une dimension, un fait ou une métrique.

USING relationship_name [ , ... ]

Logo Snowflake en noir (sans texte) Fonctionnalité en avant-première — En accès libre

Disponible pour tous les comptes.

Pour les définitions de métriques, spécifie la relation qui doit être utilisée pour joindre les tables et calculer la métrique, lorsque:ref:` plusieurs chemins de relation existent entre deux tables logiques <label-semantic_views_create_logical_tables_relations>`.

Pour définir une métrique dérivée (une métrique qui combine plusieurs métriques de différentes tables logiques), omettez table_alias. du nom.

Voir Comment Snowflake valide les vues sémantiques pour les règles de définition d’une vue sémantique valide.

NON ADDITIVE BY ( dimension [ { ASC | DESC } ] [ NULLS { FIRST | LAST } ] [ , ... ] )

Spécifie une liste de dimensions qui ne doivent pas être utilisées lors de la somme des métriques.

Au lieu de cela, pendant le traitement de la requête, les lignes sont triées par les dimensions non additives et les valeurs des dernières lignes (les derniers instantanés des valeurs) sont agrégées pour calculer la métrique.

{ ASC | DESC }

Trie éventuellement les valeurs des dimensions non additives par ordre croissant (de la plus petite à la plus grande) ou décroissant (de la plus grande à la plus petite), ce qui détermine quel est le dernier instantané.

Par défaut : ASC

NULLS { FIRST | LAST }

Spécifie éventuellement les valeurs NULL triées avant/après les valeurs non NULL, en fonction de l’ordre de tri (ASC ou DESC). L’ordre de tri détermine quel est le dernier instantané.

Par défaut : Dépend de l’ordre de tri (ASC ouDESC) ; voir:ref:` les notes d’utilisation dans la documentation de ORDERBY<label-order_by_nulls>`.

Spécifier la clause NONADDITIVEBY fait de la métrique une métrique semi-additive.

Pour plus d’informations, voir Identification des dimensions qui doivent être non additionnées pour une métrique.

AS sql_expr

Spécifie l’expression SQL pour calculer la dimension, le fait ou la métrique.

Voir Définir les faits, les dimensions et les métriques. Pour les règles de validation de ces expressions, voir:doc:/user-guide/views-semantic/validation-rules.

WITH SYNONYMS [ = ] ( 'synonym' [ , ... ] )

Spécifie un ou plusieurs synonymes facultatifs pour la dimension, le fait ou la métrique. Notez que les synonymes ne sont utilisés qu’à titre d’information. Vous ne pouvez pas utiliser un synonyme pour faire référence à une dimension, un fait ou une métrique dans une autre dimension, un autre fait ou une autre métrique.

COMMENT = 'comment_about_dim_fact_or_metric'

Spécifie un commentaire facultatif sur la dimension, le fait ou la métrique.

WITH CORTEX SEARCH SERVICE search_service_name [ USING search_service_column_name ]

Spécifie le Cortex Search Service à utiliser pour cette dimension.

Vous ne pouvez spécifier ce paramètre que pour les dimensions (et non pour les faits ou les métriques).

Si le Cortex Search Service se trouve dans une autre base de données ou un autre schéma, qualifiez le nom du service (par exemple, my_db.my_schema.my_service).

Vous pouvez définir la clause facultative USING sur le nom de la colonne dans le Cortex Search Service.

Paramètres pour les métriques de la fonction de fenêtre

Ces paramètres font partie de la syntaxe pour définir les métriques de la fonction de fenêtre :

metric

Spécifie une expression de métrique pour cette fonction de fenêtre. Vous pouvez spécifier une métrique ou toute expression de métrique valide que vous pouvez utiliser pour définir une métrique dans cette entité.

PARTITION BY ...

Groupe les lignes en partitions. Vous pouvez effectuer la partition selon un ensemble spécifique d’expressions, ou selon toutes les dimensions (sauf les dimensions sélectionnées) spécifiées dans la requête :

PARTITION BY exprs_using_dimensions_or_metrics

Groupe des lignes en partitions par expressions SQL. Dans l’expression SQL :

  • Toutes les dimensions de l’expression doivent être accessibles à partir de la même entité que celle qui définit la métrique de la fonction de fenêtre.

  • Toutes les métriques doivent appartenir à la même table dans laquelle cette métrique est définie.

  • Vous ne pouvez pas spécifier d’agrégats, de fonctions de fenêtre ou de sous-requêtes.

PARTITION BY EXCLUDING dimensions

Groupe les lignes en partitions selon toutes les dimensions spécifiées dans la clause SEMANTIC_VIEW de la requête, à l’exception des dimensions spécifiées par dimensions.

Les dimensions doivent uniquement faire référence à des dimensions accessibles depuis l’entité qui définit la métrique de la fonction de fenêtre.

Par exemple, supposons que vous excluez la dimension table_1.dimension_1 du partitionnement :

CREATE SEMANTIC VIEW sv
  ...
  METRICS (
    table_1.metric_2 AS SUM(table_1.metric_1) OVER
      (PARTITION BY EXCLUDING table_l.dimension_1 ORDER BY table_1.dimension_2)
  )
  ...

Supposons que vous exécutiez une requête qui spécifie la dimension table_1.dimension_1 :

SELECT * FROM SEMANTIC VIEW(
  sv
  METRICS (
    table_1.metric_2
  )
  DIMENSIONS (
    table_1.dimension_1,
    table_1.dimension_2,
    table_1.dimension_3
  );

Dans la requête, la métrique table_1.metric_2 est évaluée comme suit :

SUM(table_1.metric_1) OVER (
  PARTITION BY table_1.dimension_2, table_1.dimension_3
  ORDER BY table_1.dimension_2
)

Remarquez comment table_1.dimension_1 est exclu de la clause PARTITION BY.

Note

Vous ne pouvez pas utiliser EXCLUDING en dehors des définitions de métriques dans les vues sémantiques. EXCLUDING n’est pas pris en charge dans les appels de fonctions de fenêtre dans un autre contexte.

ORDER BY exprs_using_dimensions_or_metrics  [ ASC | DESC ] [ NULLS FIRST | LAST ] [, ... ]

Ordonne les lignes dans chaque partition. Dans l’expression SQL :

  • Toutes les dimensions de l’expression doivent être accessibles à partir de la même entité que celle qui définit la métrique de la fonction de fenêtre.

  • Toutes les métriques doivent appartenir à la même table dans laquelle cette métrique est définie.

  • Vous ne pouvez pas spécifier d’agrégats, de fonctions de fenêtre ou de sous-requêtes.

windowFrameClause

Voir Syntaxe et utilisation des fonctions de fenêtre.

Pour plus d’informations sur les paramètres des fonctions de fenêtre et des exemples, voir Définition et requête des métriques des fonctions de fenêtre.

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Privilège

Objet

Remarques

CREATE SEMANTIC VIEW

Schéma

Obligatoire pour créer une nouvelle vue sémantique.

SELECT

Table, vue

Exigé pour toutes les tables et/ou vues utilisées dans la définition de la vue sémantique.

Pour effectuer une opération sur un objet dans un schéma, il est nécessaire de disposer d’au moins un privilège sur la base de données parente et d’au moins un privilège sur le schéma parent.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

  • La vue sémantique doit être valide et doit respecter les règles décrites dans Comment Snowflake valide les vues sémantiques.

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

  • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

Exemples

Voir Création d’une vue sémantique à l’aide de la commande CREATE SEMANTIC VIEW.