CREATE DATA METRIC FUNCTION

Cria uma nova função de métrica de dados (DMF) no esquema atual ou especificado, ou substitui uma função de métrica de dados existente.

Depois de criar uma DMF, aplique-a a uma coluna da tabela usando um comando ALTER TABLE … ALTER COLUMN ou a uma coluna de exibição usando o comando ALTER VIEW.

Esse comando é compatível com as seguintes variantes:

Consulte também:

Referência de comando de DMF, CREATE OR ALTER <objeto>

Sintaxe

CREATE [ OR REPLACE ] [ SECURE ] DATA METRIC FUNCTION [ IF NOT EXISTS ] <name>
  ( <table_arg> TABLE( <col_arg> <data_type> [ , ... ] )
    [ , <table_arg> TABLE( <col_arg> <data_type> [ , ... ] ) ] )
  RETURNS NUMBER [ [ NOT ] NULL ]
  [ LANGUAGE SQL ]
  [ COMMENT = '<string_literal>' ]
  AS
  '<expression>'
Copy

Sintaxe da variante

CREATE OR ALTER DATA METRIC FUNCTION

Cria uma nova função de métrica de dados, se ela ainda não existir, ou transforma uma função de métrica de dados existente na função definida na instrução. Uma instrução CREATE OR ALTER DATA METRIC FUNCTION segue as regras de sintaxe de uma instrução CREATE DATA METRIC FUNCTION e tem as mesmas limitações de uma instrução ALTER FUNCTION (DMF).

Diferentemente de um comando CREATE OR REPLACE DATA METRIC FUNCTION, um comando CREATE OR ALTER atualiza o objeto sem excluí-lo e recriá-lo.

As alterações de função compatíveis incluem mudanças na propriedade COMMENT.

Para obter mais informações, consulte Notas de uso CREATE OR ALTER DATA METRIC FUNCTION.

CREATE [ OR ALTER ] DATA METRIC FUNCTION ...
Copy

Parâmetros obrigatórios

name

Identificador da DMF; deve ser único para seu esquema.

Além disso, o identificador deve começar com um caractere alfabético e não pode conter espaços ou caracteres especiais, a menos que toda a cadeia de caracteres do identificador esteja entre aspas duplas (por exemplo, "My object"). Os identificadores delimitados por aspas duplas também diferenciam letras maiúsculas de minúsculas.

Para obter mais informações, consulte Requisitos para identificadores.

( table_arg TABLE( col_arg data_type [ , ... ] ) [ , table_arg TABLE( col_arg data_type [ , ... ] ) ] )

A assinatura para a DMF, que é usada como entrada para a expressão.

Você deve especificar:

  • Um nome de argumento para cada tabela (table_arg).

  • Para cada tabela, um nome de argumento para pelo menos uma coluna, juntamente com seu tipo de dados (col_arg data_type).

    Opcionalmente, é possível especificar argumentos para colunas adicionais e seus tipos de dados. As colunas devem estar na mesma tabela e não podem fazer referência a uma tabela diferente.

RETURNS NUMBER

O tipo de dados da saída da função.

O tipo de dados só pode ser NUMBER.

AS expression

A expressão SQL que determina a saída da função. A expressão deve ser determinística e retornar um valor escalar. A expressão pode fazer referência a outros objetos de tabela, como por exemplo, usando uma cláusula WITH ou uma cláusula WHERE.

Os delimitadores em torno de expression podem ser aspas simples ou um par de sinais de cifrão. Usar $$ como delimitador facilita a escrita de expressões com aspas simples.

Se o delimitador para o expression for o caractere de aspas simples, então qualquer aspas simples dentro de expression (por exemplo, literais de cadeia de caracteres) devem ter um escape com aspas simples.

O expression não oferece suporte ao seguinte:

  • Uso de funções não determinísticas (por exemplo, CURRENT_TIME).

  • Referência a um objeto que depende de uma UDF ou UDTF.

  • Retorno de uma saída não escalar.

Parâmetros opcionais

SECURE

Especifica que a função de métrica de dados é segura. Para obter mais informações, consulte Proteção de informações sensíveis com UDFs e procedimentos armazenados seguros.

LANGUAGE SQL

Especifica a linguagem usada para escrever a expressão.

SQL é a única linguagem compatível.

COMMENT = 'string_literal'

Um comentário para a DMF.

Requisitos de controle de acesso

A função usada para executar essa operação deve ter, no mínimo, os seguintes privilégios:

Privilégio

Objeto

Notas

CREATE DATA METRIC FUNCTION

Esquema

O privilégio permite apenas a criação de funções de métricas de dados no esquema.

Se você quiser habilitar a criação de funções definidas pelo usuário, como UDFs SQL ou Java, a função deve ter o privilégio CREATE FUNCTION.

O privilégio USAGE no banco de dados e no esquema pai é necessário para executar operações em qualquer objeto de um esquema.

Para instruções sobre como criar uma função personalizada com um conjunto específico de privilégios, consulte Criação de funções personalizadas.

Para informações gerais sobre concessões de funções e privilégios para executar ações de SQL em objetos protegíveis, consulte Visão geral do controle de acesso.

Notas de uso geral

  • Se você quiser atualizar uma função de métricas de dados existente e precisar consultar a definição atual da função, execute o comando DESCRIBE FUNCTION (DMF) ou chame a função GET_DDL.

  • Em relação aos metadados:

    Atenção

    Os clientes devem garantir que nenhum dado pessoal (exceto para um objeto do usuário), dados sensíveis, dados controlados por exportação ou outros dados regulamentados sejam inseridos como metadados ao usar o serviço Snowflake. Para obter mais informações, consulte Campos de metadados no Snowflake.

Notas de uso CREATE OR ALTER DATA METRIC FUNCTION

  • As seguintes alterações não são compatíveis:

    • Alterar o corpo da função de métrica de dados.

    • Alterar a métrica de dados e a definição da tabela de entrada.

Exemplo: argumento de tabela única

Crie uma DMF que chame a função COUNT para retornar o número total de linhas que têm números positivos nas três primeiras colunas da tabela:

CREATE OR REPLACE DATA METRIC FUNCTION governance.dmfs.count_positive_numbers(
  arg_t TABLE(
    arg_c1 NUMBER,
    arg_c2 NUMBER,
    arg_c3 NUMBER
  )
)
RETURNS NUMBER
AS
$$
  SELECT
    COUNT(*)
  FROM arg_t
  WHERE
    arg_c1>0
    AND arg_c2>0
    AND arg_c3>0
$$;
Copy

Exemplo: vários argumentos de tabela

Retorna o número de registros em que o valor de uma coluna em uma tabela não tem um valor correspondente na coluna de outra tabela:

CREATE OR REPLACE DATA METRIC FUNCTION governance.dmfs.referential_check(
  arg_t1 TABLE (arg_c1 INT), arg_t2 TABLE (arg_c2 INT))
RETURNS NUMBER
AS
$$
  SELECT
    COUNT(*)
    FROM arg_t1
  WHERE
    arg_c1 NOT IN (SELECT arg_c2 FROM arg_t2)
$$;
Copy

Para ver um exemplo que usa essa DMF para validar a integridade referencial, consulte Exemplo: uso de vários argumentos de tabela para realizar verificações referenciais.

Exemplo: alteração de uma função de métrica de dados usando o comando CREATE OR ALTER DATA METRIC FUNCTION

Altera a função de métrica de dados de tabela única criada no exemplo acima para definir a segurança e o comentário.

CREATE OR ALTER SECURE DATA METRIC FUNCTION governance.dmfs.count_positive_numbers(
  arg_t TABLE(
    arg_c1 NUMBER,
    arg_c2 NUMBER,
    arg_c3 NUMBER
  )
)
RETURNS NUMBER
COMMENT = "count positive numbers"
AS
$$
  SELECT
    COUNT(*)
  FROM arg_t
  WHERE
    arg_c1>0
    AND arg_c2>0
    AND arg_c3>0
$$;
Copy