Utilização dos comandos SQL para criar e gerenciar exibições semânticas¶

Definição das tabelas lógicas¶

No comando CREATE SEMANTIC VIEW, use a cláusula TABLES para definir as tabelas lógicas na visualização. Nessa cláusula, você pode:

• Especificar o nome da tabela física e um alias opcional.

• Identificar as seguintes colunas na tabela lógica:

  • Colunas que servem como chaves primárias.

  • Colunas que contêm valores exclusivos (que não sejam colunas de chave primária).

  Você pode usar essas colunas para definir relações nessa exibição semântica.

• Adicionar sinônimos para a tabela (para melhorar a capacidade de descoberta).

• Incluir um comentário descritivo.

No exemplo apresentado anteriormente, a cláusula TABLES define três tabelas lógicas:

• Uma tabela orders contendo as informações do pedido da tabela TPC-H orders.

• Uma tabela customers contendo as informações do cliente da tabela TPC-H customers.

• Uma tabela line_items contendo os itens de linha em pedidos da tabela TPC-H lineitem.

O exemplo usa a cláusula PRIMARY KEY para identificar as colunas a serem usadas como chaves primárias para cada tabela lógica. As chaves primárias e os valores únicos ajudam a determinar os tipos de relacionamentos entre as tabelas (por exemplo, muitos para um ou um para um).

O exemplo também fornece sinônimos e comentários que descrevem as tabelas lógicas e facilitam a descoberta dos dados.

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

Identificar as relações entre as tabelas lógicas¶

No comando CREATE SEMANTIC VIEW, use a cláusula RELATIONSHIPS para identificar os relacionamentos entre as tabelas na visualização. Para cada relação, você especifica:

• Um nome opcional para a relação.

• O nome da tabela lógica que contém a chave estrangeira.

• As colunas dessa tabela que definem a chave estrangeira.

• O nome da tabela lógica que contém a chave primária ou as colunas com valores exclusivos.

• As colunas dessa tabela que definem a chave primária ou que contêm valores exclusivos.

  • Se você já tiver especificado PRIMARY KEY para a tabela lógica na cláusula TABLES, não precisará especificar a coluna de chave primária na relação.

  • Se houver uma única palavra-chave UNIQUE para a tabela lógica na cláusula TABLES, você não precisará especificar as colunas correspondentes na relação.

  Também é possível especificar uma data, hora, carimbo de data/hora ou coluna numérica, se quiser unir as colunas em um intervalo.

No exemplo apresentado anteriormente, a cláusula RELATIONSHIPS especifica duas relações:

• Uma relação entre as tabelas orders e customers. Na tabela orders, o_custkey é a chave estrangeira que se refere à chave primária na tabela customers (c_custkey).

• Uma relação entre as tabelas line_items e orders. Na tabela line_items, l_orderkey é a chave estrangeira que se refere à chave primária na tabela 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)
)

Como usar uma data, hora, carimbo de data/hora ou intervalo numérico para unir tabelas lógicas¶

Por padrão, quando você especifica uma relação entre duas tabelas lógicas, as tabelas são unidas em uma condição de igualdade.

Se você precisar unir duas tabelas lógicas em um intervalo de data, hora, carimbo de data/hora ou numérico (onde os valores em uma coluna de uma tabela precisam estar no mesmo intervalo que os valores em uma coluna de outra tabela), você pode especificar a palavra-chave ASOF com o nome da coluna na cláusula REFERENCES:

RELATIONSHIPS(
  my_relationship AS
    logical_table_1(
      col_table_1
    )
    REFERENCES
    logical_table_2(
      ASOF col_table_2
    )
)

Uma consulta da exibição semântica definida acima produz um ASOF JOIN que utiliza o perador de comparação >= na cláusula MATCH_CONDITION. Isto une as duas tabelas para que os valores em col_table_1 fiquem maiores ou iguais aos valores em col_table_2:

...
FROM logical_table_1 ASOF JOIN logical_table_2
  MATCH_CONDITION(
    logical_table_1.col_table_1 >= logical_table_2.col_table_2
  )
...

Você pode usar a palavra-chave ASOF para colunas dos mesmos tipos que você pode usar com ASOF JOIN.

Por exemplo, suponha que você tenha tabelas contendo dados de cliente, endereço do cliente e pedido:

CREATE OR REPLACE TABLE customer(
  c_cust_id VARCHAR,
  c_first_name VARCHAR,
  c_last_name VARCHAR);

INSERT INTO customer VALUES
  ('cust001', 'Mary', 'Smith'),
  ('cust002', 'Bill', 'Wilson');

CREATE OR REPLACE TABLE customer_address(
  ca_cust_id VARCHAR,
  ca_zipcode VARCHAR,
  ca_street_addr VARCHAR,
  ca_start_date DATE,
  ca_end_date DATE
);

INSERT INTO customer_address VALUES
  ('cust001', '94025', '100 Main Street', '2024-01-01', '2024-03-31'),
  ('cust001', '94026', '200 Main Street', '2024-04-01', '2024-06-30'),
  ('cust001', '94027', '300 Main Street', '2024-07-01', NULL),
  ('cust002', '94028', '400 Main Street', '2024-01-01', '2024-04-30'),
  ('cust002', '94029', '500 Main Street', '2024-05-01', '2024-07-31'),
  ('cust002', '94030', '600 Main Street', '2024-08-01', NULL);

CREATE OR REPLACE TABLE orders(
  o_ord_id VARCHAR,
  o_cust_id VARCHAR,
  o_ord_date DATE,
  o_amount NUMBER
);

INSERT INTO orders VALUES
  ('ord100', 'cust001', '2024-02-01', 100),
  ('ord101', 'cust001', '2024-02-02', 200),
  ('ord102', 'cust001', '2024-05-01', 300),
  ('ord103', 'cust001', '2024-05-02', 400),
  ('ord104', 'cust001', '2024-08-01', 500),
  ('ord105', 'cust001', '2024-08-02', 600),
  ('ord106', 'cust002', '2024-03-01', 100),
  ('ord107', 'cust002', '2024-03-02', 200),
  ('ord108', 'cust002', '2024-06-01', 300),
  ('ord109', 'cust002', '2024-06-02', 400),
  ('ord110', 'cust002', '2024-09-01', 500),
  ('ord111', 'cust002', '2024-09-02', 600);

Neste exemplo, a tabela customer_address tem uma coluna ca_start_date, que indica quando o cliente começou a residir no endereço especificado. A tabela orders tem uma coluna o_ord_date, que é a data do pedido.

Suponha que você queira poder consultar informações sobre os pedidos dos clientes e recuperar os códigos postais correspondentes ao local onde o cliente residia quando os pedidos foram feitos.

É possível definir uma exibição semântica que especifique uma junção ASOF entre as colunas ca_start_date e o_ord_date:

CREATE OR REPLACE SEMANTIC VIEW customer_orders_view
  TABLES (
    customer_address UNIQUE (ca_cust_id, ca_start_date),
    customer UNIQUE (c_cust_id),
    orders UNIQUE (o_ord_id)
  )
  RELATIONSHIPS (
    customer_address(ca_cust_id) REFERENCES customer,
    -- Defines an ASOF JOIN on the date columns.
    orders(o_cust_id, o_ord_date)
      REFERENCES
        customer_address(ca_cust_id, ASOF ca_start_date)
  )
  FACTS (
    customer_address.f_zipcode AS ca_zipcode
  )
  DIMENSIONS (
    -- Relies on the ASOF join to retrieve the zip code
    -- where the order date is greater than or equal to
    -- the address starting date.
    orders.f_cust_zipcode AS customer_address.f_zipcode,
    orders.dim_year_month AS DATE_TRUNC('month', o_ord_date)
  )
  METRICS (
    orders.m_order_amount AS SUM(o_amount)
  );

Suponha que você consulte essa exibição semântica para retornar a soma dos valores dos pedidos por mês para cada código postal:

SELECT * FROM SEMANTIC_VIEW(
  customer_orders_view
  DIMENSIONS orders.dim_year_month, orders.f_cust_zipcode
  METRICS orders.m_order_amount
);

+----------------+----------------+----------------+
| DIM_YEAR_MONTH | F_CUST_ZIPCODE | M_ORDER_AMOUNT |
|----------------+----------------+----------------|
| 2024-02-01     | 94025          |            300 |
| 2024-05-01     | 94026          |            700 |
| 2024-08-01     | 94027          |           1100 |
| 2024-03-01     | 94028          |            300 |
| 2024-09-01     | 94030          |           1100 |
| 2024-06-01     | 94029          |            700 |
+----------------+----------------+----------------+

A consulta efetivamente usa ASOF JOIN para unir as tabelas nas colunas de datas, em que a data do pedido é maior ou igual à data de início do endereço:

...
FROM orders ASOF JOIN customer_address
  MATCH_CONDITION(
    orders.o_ord_date >= customer_address.ca_start_date
  )
  ON
    orders.o_cust_id = customer_address.ca_cust_id
...

Unindo tabelas lógicas que contêm intervalos de valores¶

Você pode usar uma junção de intervalo quando quiser unir uma tabela a outra tabela que define um intervalo de valores possíveis na primeira tabela. Por exemplo, suponha que uma tabela represente pedidos de vendas e tenha uma coluna com o carimbo de data/hora em que o pedido foi feito. Suponha que outra tabela represente trimestres fiscais e contenha os intervalos de tempo distintos que representam esses trimestres. Você pode criar uma exibição semântica para unir as duas tabelas de modo que a linha de um pedido inclua o trimestre fiscal em que o pedido foi feito.

Na tabela que contém os intervalos, cada intervalo deve ser distinto. Dois intervalos não podem se sobrepor.

Nos dados da tabela, se você quiser especificar o menor valor possível ou o maior valor possível para o intervalo, use NULL.

Por exemplo, a tabela a seguir define um conjunto de intervalos de horas que não se sobrepõem:

• A primeira linha cobre o intervalo que inclui tudo até (mas sem incluir) 1º de janeiro de 2024.

• A última linha cobre o intervalo que inclui tudo de 20 de março de 2024 em diante.

+----------------+------------------+-------------------------+-------------------------+
| TIME_PERIOD_ID | TIME_PERIOD_NAME | START_TIME              | END_TIME                |
|----------------+------------------+-------------------------+-------------------------|
|              1 | Before_January   | NULL                    | 2024-01-01 00:00:00.000 |
|              2 | Early_January    | 2024-01-01 00:00:00.000 | 2024-01-15 00:00:00.000 |
|              3 | Late_January     | 2024-01-15 00:00:00.000 | 2024-02-01 00:00:00.000 |
|              4 | Early_February   | 2024-02-01 00:00:00.000 | 2024-02-15 00:00:00.000 |
|              5 | Late_February    | 2024-02-15 00:00:00.000 | 2024-03-01 00:00:00.000 |
|              6 | Early_March      | 2024-03-01 00:00:00.000 | 2024-03-20 00:00:00.000 |
|              7 | After_March20    | 2024-03-20 00:00:00.000 | NULL                    |
+----------------+------------------+-------------------------+-------------------------+

Para casos como esses, você pode configurar uma exibição semântica compatível com consultas de junção de intervalo. Ao criar a exibição semântica, você deve fazer o seguinte:

1. Para a tabela lógica contendo as horas de início e de término de um período, defina uma restrição que especifique que dois intervalos não podem se sobrepor.

   Na cláusula TABLE do comando CREATE SEMANTIC VIEW, especifique a cláusula CONSTRAINT na definição da tabela lógica. Para saber a sintaxe, consulte a documentação de CONSTRAINT no tópico CREATE SEMANTIC VIEW.

2. Defina um relacionamento entre a coluna que contém o carimbo de data/hora em uma tabela e as colunas de horas de início e de término na outra tabela.

   Na cláusula RELATIONSHIPS do comando CREATE SEMANTIC VIEW, use a cláusula BETWEEN para especificar as colunas que contêm as horas de início e de término. Para saber a sintaxe, consulte a documentação de RELATIONSHIP no tópico CREATE SEMANTIC VIEW.

Por exemplo, suponha que a tabela my_time_periods defina períodos de tempo distintos:

CREATE OR REPLACE TABLE my_time_periods (
  time_period_id INT PRIMARY KEY,
  time_period_name VARCHAR(50),
  start_time TIMESTAMP,
  end_time TIMESTAMP
);

INSERT INTO my_time_periods (
    time_period_id, time_period_name, start_time, end_time
  ) VALUES
    (1, 'Before_January', NULL, '2024-01-01 00:00:00'::TIMESTAMP),
    (2, 'Early_January', '2024-01-01 00:00:00'::TIMESTAMP, '2024-01-15 00:00:00'::TIMESTAMP),
    (3, 'Late_January', '2024-01-15 00:00:00'::TIMESTAMP, '2024-02-01 00:00:00'::TIMESTAMP),
    (4, 'Early_February', '2024-02-01 00:00:00'::TIMESTAMP, '2024-02-15 00:00:00'::TIMESTAMP),
    (5, 'Late_February', '2024-02-15 00:00:00'::TIMESTAMP, '2024-03-01 00:00:00'::TIMESTAMP),
    (6, 'Early_March', '2024-03-01 00:00:00'::TIMESTAMP, '2024-03-20 00:00:00'::TIMESTAMP),
    (7, 'After_March20', '2024-03-20 00:00:00'::TIMESTAMP, NULL);

Suponha que a tabela my_events capture eventos que ocorreram dentro desses períodos de tempo:

CREATE OR REPLACE TABLE my_events (
  event_id INTEGER PRIMARY KEY,
  event_timestamp TIMESTAMP,
  event_name VARCHAR
);

INSERT INTO my_events (event_id, event_name, event_timestamp) VALUES
  (1, 'Login', '2024-01-15 10:00:00'::TIMESTAMP),
  (2, 'Purchase', '2024-01-15 14:30:00'::TIMESTAMP),
  (3, 'Logout', '2024-01-15 18:45:00'::TIMESTAMP),
  (4, 'Review', '2024-02-10 12:00:00'::TIMESTAMP),
  (5, 'Support', '2024-02-20 09:30:00'::TIMESTAMP),
  (6, 'Upgrade', '2024-03-05 16:00:00'::TIMESTAMP),
  (7, 'Feedback', '2024-03-25 11:00:00'::TIMESTAMP);

Você pode definir uma exibição semântica que una as tabelas. As linhas em my_events são unidas às linhas em my_time_periods, em que o valor na coluna event_timestamp em my_events está dentro do intervalo especificado pelas colunas start_time e end_time em my_time_periods.

CREATE OR REPLACE SEMANTIC VIEW my_semantic_view_range_join
  TABLES (
    my_events PRIMARY KEY (event_id),
    my_time_periods UNIQUE (start_time, end_time)
      CONSTRAINT my_time_period_range DISTINCT RANGE BETWEEN start_time AND end_time EXCLUSIVE
  )
  RELATIONSHIPS (
    my_time_periods_for_events AS
      my_events(event_timestamp) REFERENCES
        my_time_periods(BETWEEN start_time AND end_time EXCLUSIVE)
  )
  DIMENSIONS (
    my_events.dim_event_name AS event_name,
    my_events.dim_event_timestamp AS event_timestamp,
    my_time_periods.dim_time_period_name AS time_period_name
  )
  METRICS (
    my_events.m_event_count AS COUNT(*)
  );

A consulta a seguir demonstra como as linhas são unidas:

SELECT
    sv.dim_event_name,
    sv.dim_event_timestamp,
    sv.dim_time_period_name,
    sv.m_event_count
  FROM SEMANTIC_VIEW(
    my_semantic_view_range_join
    METRICS my_events.m_event_count
    DIMENSIONS
      my_events.dim_event_name,
      my_events.dim_event_timestamp,
      my_time_periods.dim_time_period_name
  ) AS sv
  ORDER BY
    sv.dim_event_timestamp,
    sv.dim_time_period_name;

+----------------+-------------------------+----------------------+---------------+
| DIM_EVENT_NAME | DIM_EVENT_TIMESTAMP     | DIM_TIME_PERIOD_NAME | M_EVENT_COUNT |
|----------------+-------------------------+----------------------+---------------|
| Login          | 2024-01-15 10:00:00.000 | Late_January         |             1 |
| Purchase       | 2024-01-15 14:30:00.000 | Late_January         |             1 |
| Logout         | 2024-01-15 18:45:00.000 | Late_January         |             1 |
| Review         | 2024-02-10 12:00:00.000 | Early_February       |             1 |
| Support        | 2024-02-20 09:30:00.000 | Late_February        |             1 |
| Upgrade        | 2024-03-05 16:00:00.000 | Early_March          |             1 |
| Feedback       | 2024-03-25 11:00:00.000 | After_March20        |             1 |
+----------------+-------------------------+----------------------+---------------+

Como mostrado nos exemplos, a dimensão dim_time_period_name para cada linha nos resultados é o nome do período no qual a dimensão dim_event_timestamp se enquadra.

Definição de fatos, dimensões e métricas¶

No comando CREATE SEMANTIC VIEW, use as cláusulas FACTS, DIMENSIONS e METRICS para definir os fatos, as dimensões e as métricas na exibição semântica.

Você deve definir pelo menos uma dimensão ou métrica na exibição semântica.

Para cada fato, dimensão ou métrica, você deve especificar:

• A tabela lógica à qual pertence.

  Nota

  Se quiser definir uma métrica derivada (uma métrica que não seja específica de uma tabela lógica), é necessário omitir o nome da tabela lógica. Consulte Definição de métricas derivadas.

• Um nome para o fato, a dimensão ou a métrica.

• A expressão SQL para calculá-lo.

  Nota

  Para dimensões, você pode especificar um Cortex Search Service para usar na dimensão. Para obter mais informações, consulte Definição de uma dimensão que usa um Cortex Search Service.

• Sinônimos e comentários opcionais.

O exemplo apresentado anteriormente define vários fatos, dimensões e métricas:

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

Definição de uma dimensão que usa um Cortex Search Service¶

Para definir uma dimensão que usa um Cortex Search Service, defina a cláusula WITH CORTEX SEARCH SERVICE com o nome do Cortex Search Service. Se o serviço estiver em um banco de dados ou esquema diferente, qualifique o nome do serviço. Por exemplo:

DIMENSIONS (
  my_table.my_dimension AS my_dimension_expression
    WITH CORTEX SEARCH SERVICE my_db.my_schema.my_dimension_search_service
)

Definição de métricas derivadas¶

Ao definir uma métrica, você especifica o nome da tabela lógica à qual a métrica pertence. Essa é a tabela lógica na qual a métrica é agregada.

Se quiser definir uma métrica baseada em métricas de diferentes tabelas lógicas, você poderá definir uma métrica derivada. Uma métrica derivada é uma métrica com escopo definido para a exibição semântica (em vez de para uma tabela lógica específica). Uma métrica derivada pode combinar métricas de vários tabelas lógicas.

Na definição de uma métrica derivada, omita o nome da tabela lógica.

Por exemplo, suponha que você queira definir uma métrica my_derived_metric_1 que é a soma das métricas table_1.metric_1 e table_2.metric_2. Quando você definir my_derived_metric_1, não qualifique o nome com nenhum nome de tabela lógica:

CREATE SEMANTIC VIEW sv_with_derived_metrics
  TABLES (
    table_1 PRIMARY KEY (column_1),
    table_2 PRIMARY KEY (column_2)
  )
  ...
  METRICS (
    table_1.metric_1 AS SUM(...),
    table_2.metric_2 AS SUM(...),
    my_derived_metric_1 AS table_1.metric_1 + table_2.metric_2
  )
 ...

Você pode usar outras métricas derivadas na expressão. Por exemplo:

METRICS (
  ...
  my_derived_metric_1 AS table_1.metric_1 + table_2.metric_2,
  my_view_metric_2 AS my_derived_metric_1 + table_3.metric_3
)

Observe as seguintes restrições ao definir uma métrica derivada:

• Você não pode usar o mesmo nome para uma métrica derivada e uma métrica regular.

• A expressão para uma métrica derivada pode usar:

  • Agregações de dimensões e fatos definidos em qualquer tabela lógica na exibição semântica.

  • Expressões escalares de métricas definidas em qualquer tabela lógica na exibição semântica.

  • Outras métricas derivadas.

  No seguinte exemplo:

  • derived_metric_1 usa uma expressão escalar com duas métricas.

  • derived_metric_2 usa uma agregação de uma dimensão.

  • derived_metric_3 adiciona uma agregação de uma dimensão a outra métrica derivada.

  CopyExpand

  CREATE OR REPLACE SEMANTIC VIEW sv_derived_metrics
    TABLES (t1)
    DIMENSIONS (t1.dim1 AS t1.col1)
    METRICS (
      t1.m1 AS SUM(t1.col1),
      t2.m2 AS SUM(t1.col2),
      derived_metric_1 AS t1.m1 + t2.m2,
      derived_metric_2 AS SUM(t1.dim1),
      derived_metric_3 AS SUM(t1.dim1) + derived_metric_2
    )
    ...
  

  Show lessSee more

  Scroll to top

• Você não precisará qualificar o nome de uma métrica na dimensão nem o fato na expressão se o nome não for ambíguo. Por exemplo:

  CopyExpand

  METRICS (
    table_1.metric_1 AS ...,
    table_1.my_unique_metric_name AS ...,
    table_2.metric_1 AS ...,
    my_derived_metric_1 AS table_1.metric_1 + my_unique_metric_name
  )
  

  Show lessSee more

  Scroll to top

  Observe que metric_1 precisa ser qualificado por table_1 porque há duas métricas chamadas metric_1, mas my_unique_metric_name não precisa ser qualificado porque o nome é exclusivo.

• Na expressão para uma métrica derivada, você não pode usar o seguinte:

  • Agregações de métricas.

  • Funções de janela.

  • Referências a colunas físicas.

  • Referências a fatos ou dimensões que não são agregados.

• Você não pode usar uma métrica derivada na expressão para uma métrica, dimensão ou fato regular. Somente outra métrica derivada pode usar uma métrica derivada em sua expressão.

Especificando o relacionamento de uma métrica quando há vários caminhos de relacionamento¶

Em alguns casos, vários caminhos de relacionamento podem existir entre duas tabelas lógicas específicas em uma exibição semântica. Nesses casos, ao definir uma métrica, você deve especificar o caminho de relacionamento a ser usado.

CREATE OR REPLACE TABLE airports (
  airport_code VARCHAR PRIMARY KEY,
  city_name VARCHAR,
  airport_region_code VARCHAR
);

INSERT INTO airports VALUES
  ('SEA', 'Seattle', 'NA'),
  ('SFO', 'San Fransico', 'NA'),
  ('PVG', 'Shanghai', 'AS');

SELECT * FROM airports;

+--------------+--------------+---------------------+
| AIRPORT_CODE | CITY_NAME    | AIRPORT_REGION_CODE |
|--------------+--------------+---------------------|
| SEA          | Seattle      | NA                  |
| SFO          | San Fransico | NA                  |
| PVG          | Shanghai     | AS                  |
+--------------+--------------+---------------------+

CREATE OR REPLACE TABLE flights (
  flight_id INTEGER PRIMARY KEY,
  departure_airport VARCHAR,
  arrival_airport VARCHAR,
  is_late BOOLEAN,
  aircraft_id INTEGER,
  departure_time DATETIME,
  arrival_time DATETIME
);

INSERT INTO flights VALUES
  (1, 'SFO', 'SEA', true, 1, '2025-01-03 06:00:00', '2025-01-03 11:00:00'),
  (2, 'SEA', 'SFO', false, 2, '2025-01-03 11:00:00', '2025-01-03 16:00:00'),
  (3, 'SEA', 'PVG', false, 3, '2025-01-03 11:00:00', '2025-01-04 11:00:00'),
  (4, 'SFO', 'PVG', true, 1, '2025-01-03 06:00:00', '2025-01-04 11:00:00');

SELECT * FROM flights;

+-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------+
| FLIGHT_ID | DEPARTURE_AIRPORT | ARRIVAL_AIRPORT | IS_LATE | AIRCRAFT_ID | DEPARTURE_TIME          | ARRIVAL_TIME            |
|-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------|
|         1 | SFO               | SEA             | True    |           1 | 2025-01-03 06:00:00.000 | 2025-01-03 11:00:00.000 |
|         2 | SEA               | SFO             | False   |           2 | 2025-01-03 11:00:00.000 | 2025-01-03 16:00:00.000 |
|         3 | SEA               | PVG             | False   |           3 | 2025-01-03 11:00:00.000 | 2025-01-04 11:00:00.000 |
|         4 | SFO               | PVG             | True    |           1 | 2025-01-03 06:00:00.000 | 2025-01-04 11:00:00.000 |
+-----------+-------------------+-----------------+---------+-------------+-------------------------+-------------------------+

CREATE OR REPLACE SEMANTIC VIEW flights_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id)
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_sv
  METRICS flights.m_flight_count
  DIMENSIONS airports.city_name
);

010246 (42601): SQL compilation error:
Invalid dimension specified: Multi-path relationship between the dimension entity 'AIRPORTS'
  and the base metric or dimension entity 'FLIGHTS' is not supported.

METRICS (
  <table_alias>.<metric>
    [ USING ( <relationship_name> [ , ... ] )
    AS <sql_expr>
  [ , ... ]
)

CREATE OR REPLACE SEMANTIC VIEW flights_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS airports.city_name
);

+------------------------+--------------------------+--------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | CITY_NAME    |
|------------------------+--------------------------+--------------|
|                      1 |                        2 | San Fransico |
|                      1 |                        2 | Seattle      |
|                      2 |                     NULL | Shanghai     |
+------------------------+--------------------------+--------------+

CREATE OR REPLACE TABLE regions (
  region_code VARCHAR PRIMARY KEY,
  region_name VARCHAR
);

INSERT INTO regions VALUES
  ('NA', 'North America'),
  ('AS', 'Asia');

SELECT * FROM regions;

+-------------+---------------+
| REGION_CODE | REGION_NAME   |
|-------------+---------------|
| NA          | North America |
| AS          | Asia          |
+-------------+---------------+

CREATE OR REPLACE SEMANTIC VIEW flights_by_regions_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code),
    regions PRIMARY KEY (region_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code),
    airport_region AS airports(airport_region_code) REFERENCES regions(region_code)
  ) DIMENSIONS (
    airports.city_name AS city_name,
    regions.region_name AS region_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_by_regions_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS regions.region_name
);

+------------------------+--------------------------+---------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | REGION_NAME   |
|------------------------+--------------------------+---------------|
|                      2 |                        4 | North America |
|                      2 |                     NULL | Asia          |
+------------------------+--------------------------+---------------+

CREATE OR REPLACE TABLE weather (
  airport_code VARCHAR PRIMARY KEY,
  weather_condition VARCHAR,
  start_date DATETIME,
  end_date DATETIME
);

INSERT INTO weather VALUES
  ('SEA', 'rainy', '2025-01-01 10:00:00', '2025-01-01 12:00:00'),
  ('SEA', 'rainy', '2025-01-03 10:00:00', '2025-01-03 12:00:00'),
  ('SFO', 'sunny', '2025-01-03 05:00:00', '2025-01-03 09:00:00'),
  ('SFO', 'sunny', '2025-01-03 10:00:00', '2025-01-03 18:00:00'),
  ('PVG', 'cloudy', '2025-01-04 10:00:00', '2025-01-04 12:00:00');

SELECT * FROM weather;

+--------------+-------------------+-------------------------+-------------------------+
| AIRPORT_CODE | WEATHER_CONDITION | START_DATE              | END_DATE                |
|--------------+-------------------+-------------------------+-------------------------|
| SEA          | rainy             | 2025-01-01 10:00:00.000 | 2025-01-01 12:00:00.000 |
| SEA          | rainy             | 2025-01-03 10:00:00.000 | 2025-01-03 12:00:00.000 |
| SFO          | sunny             | 2025-01-03 05:00:00.000 | 2025-01-03 09:00:00.000 |
| SFO          | sunny             | 2025-01-03 10:00:00.000 | 2025-01-03 18:00:00.000 |
| PVG          | cloudy            | 2025-01-04 10:00:00.000 | 2025-01-04 12:00:00.000 |
+--------------+-------------------+-------------------------+-------------------------+

CREATE OR REPLACE SEMANTIC VIEW flights_and_weather_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code),
    weather PRIMARY KEY (airport_code, start_date, end_date)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code),
    flight_departure_weather AS flights(departure_airport, departure_time) REFERENCES weather(airport_code, BETWEEN start_date AND end_date EXCLUSIVE),
    flight_arrival_weather AS flights(arrival_airport, arrival_time) REFERENCES weather(airport_code, BETWEEN start_date AND end_date EXCLUSIVE)
  ) DIMENSIONS (
    airports.city_name AS city_name,
    weather.weather_condition AS weather_condition
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport, flight_departure_weather) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport, flight_arrival_weather) AS flights.m_flight_count
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_by_regions_sv
  METRICS flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS weather.weather_condition
);

+------------------------+--------------------------+-------------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | WEATHER_CONDITION |
|------------------------+--------------------------+-------------------|
|                      2 |                     NULL | cloudy            |
|                      1 |                        2 | sunny             |
|                      1 |                        2 | rainy             |
+------------------------+--------------------------+-------------------+

CREATE OR REPLACE SEMANTIC VIEW flights_derived_metrics_sv
  TABLES (
    flights PRIMARY KEY (flight_id),
    airports PRIMARY KEY (airport_code)
  ) RELATIONSHIPS (
    flight_departure_airport AS flights(departure_airport) REFERENCES airports(airport_code),
    flight_arrival_airport AS flights(arrival_airport) REFERENCES airports(airport_code)
  ) DIMENSIONS (
    airports.city_name AS city_name
  ) METRICS (
    flights.m_flight_count AS COUNT(flight_id),
    flights.m_flight_departure_count USING (flight_departure_airport) AS flights.m_flight_count,
    flights.m_flight_arrival_count USING (flight_arrival_airport) AS flights.m_flight_count,
    global_m_departure_arrival_ratio AS DIV0(flights.m_flight_departure_count, flights.m_flight_arrival_count),
    global_m_departure_arrival_sum AS flights.m_flight_departure_count + flights.m_flight_arrival_count
  );

SELECT * FROM SEMANTIC_VIEW (
  flights_derived_metrics_sv
  METRICS global_m_departure_arrival_ratio,
    flights.m_flight_arrival_count, flights.m_flight_departure_count
  DIMENSIONS airports.city_name
);

+------------------------+--------------------------+----------------------------------+--------------+
| M_FLIGHT_ARRIVAL_COUNT | M_FLIGHT_DEPARTURE_COUNT | GLOBAL_M_DEPARTURE_ARRIVAL_RATIO | CITY_NAME    |
|------------------------+--------------------------+----------------------------------+--------------|
|                      1 |                        2 |                         2.000000 | Seattle      |
|                      1 |                        2 |                         2.000000 | San Fransico |
|                      2 |                     NULL |                             NULL | Shanghai     |
+------------------------+--------------------------+----------------------------------+--------------+

Identificando as dimensões que devem ser não aditivas para uma métrica¶

Em alguns casos, uma métrica não deve ser agregada em dimensões específicas. Nesses casos, você pode marcar as dimensões como não aditivas.

CREATE OR REPLACE TABLE bank_accounts (
  customer_id VARCHAR,
  account_type VARCHAR,
  year NUMBER,
  month NUMBER,
  day NUMBER,
  balance NUMBER
);

INSERT INTO bank_accounts VALUES
  ('cust-001', 'checking', 2024, 01, 01, 100),
  ('cust-001', 'savings', 2024, 01, 01, 110),
  ('cust-001', 'checking', 2024, 02, 10, 140),
  ('cust-001', 'savings', 2024, 02, 10, 150),
  ('cust-001', 'checking', 2024, 03, 15, 200),
  ('cust-001', 'savings', 2024, 03, 30, 210),
  ('cust-001', 'checking', 2025, 02, 15, 280),
  ('cust-001', 'savings', 2025, 02, 15, 290),
  ('cust-001', 'checking', 2025, 03, 20, 300),
  ('cust-001', 'savings', 2025, 03, 20, 310),
  ('cust-002', 'checking', 2025, 03, 30, 200),
  ('cust-002', 'savings', 2025, 03, 30, 310);

SELECT * FROM bank_accounts;

+-------------+--------------+------+-------+-----+---------+
| CUSTOMER_ID | ACCOUNT_TYPE | YEAR | MONTH | DAY | BALANCE |
|-------------+--------------+------+-------+-----+---------|
| cust-001    | checking     | 2024 |     1 |   1 |     100 |
| cust-001    | savings      | 2024 |     1 |   1 |     110 |
| cust-001    | checking     | 2024 |     2 |  10 |     140 |
| cust-001    | savings      | 2024 |     2 |  10 |     150 |
| cust-001    | checking     | 2024 |     3 |  15 |     200 |
| cust-001    | savings      | 2024 |     3 |  30 |     210 |
| cust-001    | checking     | 2025 |     2 |  15 |     280 |
| cust-001    | savings      | 2025 |     2 |  15 |     290 |
| cust-001    | checking     | 2025 |     3 |  20 |     300 |
| cust-001    | savings      | 2025 |     3 |  20 |     310 |
| cust-002    | checking     | 2025 |     3 |  30 |     200 |
| cust-002    | savings      | 2025 |     3 |  30 |     310 |
+-------------+--------------+------+-------+-----+---------+

CREATE OR REPLACE SEMANTIC VIEW bank_accounts_sv
  TABLES (
    bank_accounts
  )
  DIMENSIONS (
    bank_accounts.customer_id_dim AS bank_accounts.customer_id,
    bank_accounts.account_type_dim AS bank_accounts.account_type,
    bank_accounts.year_dim AS bank_accounts.year,
    bank_accounts.month_dim AS bank_accounts.month,
    bank_accounts.day_dim AS bank_accounts.day
  )
  METRICS (
    bank_accounts.m_account_balance AS SUM(balance)
  );

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS customer_id_dim, year_dim
  )
  ORDER BY customer_id_dim, year_dim;

+-------------------+-----------------+----------+
| M_ACCOUNT_BALANCE | CUSTOMER_ID_DIM | YEAR_DIM |
|-------------------+-----------------+----------|
|               910 | cust-001        |     2024 |
|              1180 | cust-001        |     2025 |
|               510 | cust-002        |     2025 |
+-------------------+-----------------+----------+

CREATE OR REPLACE SEMANTIC VIEW bank_accounts_sv
  TABLES (
    bank_accounts
  )
  DIMENSIONS (
    bank_accounts.customer_id_dim AS bank_accounts.customer_id,
    bank_accounts.account_type_dim AS bank_accounts.account_type,
    bank_accounts.year_dim AS bank_accounts.year,
    bank_accounts.month_dim AS bank_accounts.month,
    bank_accounts.day_dim AS bank_accounts.day
  )
  METRICS (
    bank_accounts.m_account_balance
      NON ADDITIVE BY (year_dim, month_dim, day_dim)
      AS SUM(balance)
  );

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS customer_id_dim, year_dim
  )
  ORDER BY customer_id_dim, year_dim;

+-------------------+-----------------+----------+
| M_ACCOUNT_BALANCE | CUSTOMER_ID_DIM | YEAR_DIM |
|-------------------+-----------------+----------|
|               210 | cust-001        |     2024 |
|               610 | cust-001        |     2025 |
|               510 | cust-002        |     2025 |
+-------------------+-----------------+----------+

SELECT * FROM SEMANTIC_VIEW(
    bank_accounts_sv
    METRICS bank_accounts.m_account_balance
    DIMENSIONS year_dim
  )
  ORDER BY year_dim;

+-------------------+----------+
| M_ACCOUNT_BALANCE | YEAR_DIM |
|-------------------+----------|
|               210 |     2024 |
|               510 |     2025 |
+-------------------+----------+

METRICS (
  bank_accounts.m_account_balance
    NON ADDITIVE BY (year_dim DESC, month_dim DESC, day_dim DESC)
    AS SUM(balance)
);

METRICS (
  bank_accounts.m_account_balance
    NON ADDITIVE BY (
      year_dim DESC NULLS FIRST,
      month_dim DESC NULLS FIRST,
      day_dim DESC NULLS FIRST
    )
    AS SUM(balance)

Marcação de fato ou métrica como privado¶

Se você estiver definindo um fato ou métrica apenas para uso em cálculos na exibição semântica e não quiser que o fato ou métrica seja retornado em uma consulta, poderá especificar a palavra-chave PRIVATE para marcar o fato ou métrica como privado. Por exemplo:

FACTS (
  PRIVATE my_private_fact AS ...
)

METRICS (
  PRIVATE my_private_metric AS ...
)

Ao consultar uma exibição semântica com fatos ou métricas privados, você não pode especificar um fato ou uma métrica privada nas seguintes cláusulas:

• A lista SELECT

• FACTS na cláusula SEMANTIC_VIEW

• METRICS na cláusula SEMANTIC_VIEW

• METRICS

• WHERE na instrução SELECT ou na cláusula SEMANTIC_VIEW

Alguns comandos e funções incluem fatos e métricas privados:

• Os fatos e as métricas privados aparecem na saída do comando DESCRIBE SEMANTIC VIEW. As linhas de fatos e métricas privados têm PRIVATE na coluna access_modifier.

• Os fatos e as métricas privados são listados no valor de retorno de uma chamada de função GET_DDL, como indicado em Obtenção da instrução SQL para uma exibição semântica.

Alguns comandos e funções incluem fatos e métricas privados somente em condições específicas:

• Os fatos e métricas privados serão listados nas exibições INFORMATION_SCHEMA SEMANTIC_FACTS e SEMANTIC_METRICS somente se você usar uma função que tenha recebido o privilégio REFERENCES ou OWNERSHIP na exibição semântica.

  Caso contrário, essas exibições listarão apenas os fatos e métricas públicos.

Outros comandos e funções não incluem fatos e métricas privados:

• Os fatos privados não aparecem na saída do comando SHOW SEMANTIC FACTS.

• As métricas privadas não aparecem na saída do comando SHOW SEMANTIC METRICS.

Fornecendo instruções personalizadas para o Cortex Analyst¶

Em uma exibição semântica, você pode fornecer instruções para o Cortex Analyst que explicam como:

• Gerar a instrução SQL

• Classificar perguntas e enviar prompt de informações adicionais

Para fornecer as instruções personalizadas, use as seguintes cláusulas:

• Para obter instruções sobre como gerar a instrução SQL, use a cláusula AI_SQL_GENERATION no comando CREATE SEMANTIC VIEW.

  Por exemplo, para solicitar que o Cortex Analyst gere a instrução SQL para que todas as colunas numéricas sejam arredondadas para duas casas decimais, especifique o seguinte:

  CopyExpand

  CREATE SEMANTIC VIEW my_semantic_view
    ...
    -- Definitions of logical tables, relationships, dimensions, facts, and metrics
    ...
    AI_SQL_GENERATION 'Ensure that all numeric columns are rounded to 2 decimal points.'
    ...
    -- Additional clauses
  

  Show lessSee more

  Scroll to top

• Para obter instruções sobre como classificar perguntas, use a cláusula AI_QUESTION_CATEGORIZATION.

  Por exemplo, para solicitar que o Cortex Analyst rejeite perguntas sobre usuários, especifique o seguinte:

  CopyExpand

  CREATE SEMANTIC VIEW my_semantic_view
    ...
    -- Definitions of logical tables, relationships, dimensions, facts, and metrics
    ...
    AI_QUESTION_CATEGORIZATION 'Reject all questions asking about users. Ask users to contact their admin.'
    ...
    -- Additional clauses
  

  Show lessSee more

  Scroll to top

  Você também pode fornecer instruções para solicitar mais detalhes, se a pergunta não for clara. Por exemplo:

  CopyExpand

  AI_QUESTION_CATEGORIZATION 'If the question asks for users without providing a product_type, consider this question UNCLEAR and ask the user to specify product_type.'
  

  Show lessSee more

  Scroll to top