CREATE DATA METRIC FUNCTION¶

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

Sintaxe da variante¶

CREATE [ OR ALTER ] DATA METRIC FUNCTION ...

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:

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

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

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