CREATE TRANSFORM

CREATE TRANSFORM
Anterior	Acima	Comandos SQL	Principal	Próxima

CREATE TRANSFORM — define uma nova transformação

Sinopse

CREATE [ OR REPLACE ] TRANSFORM FOR nome_do_tipo_de_dados
  LANGUAGE nome_da_linguagem (
    FROM SQL WITH FUNCTION nome_da_função_do_sql
      [ (tipo_de_dados_do_argumento [, ...]) ],
    TO SQL WITH FUNCTION nome_da_função_para_o_sql
      [ (tipo_de_dados_do_argumento [, ...]) ]
);

Descrição

O comando CREATE TRANSFORM define uma nova transformação ^[142]. O comando CREATE OR REPLACE TRANSFORM define uma nova transformação, ou substitui uma definição existente.

Uma transformação especifica como adaptar um tipo de dados a uma linguagem procedural. Por exemplo, ao escrever uma função em PL/Python usando o tipo de dados hstore, o PL/Python não tem conhecimento prévio de como representar valores hstore no ambiente Python. As implementações de linguagem geralmente usam como padrão a representação textual, mas isto é inconveniente quando, por exemplo, uma matriz associativa ou uma lista seria mais apropriada.

Uma transformação especifica duas funções:

Uma função “do SQL”, que converte o tipo de dados do ambiente SQL para a linguagem. Esta função será chamada nos argumentos da função escrita na linguagem.
Uma função “para o SQL”, que converte o tipo de dados da linguagem para o ambiente SQL. Esta função será chamada no valor de retorno da função escrita na linguagem.

Não é necessário fornecer estas duas funções. Se uma delas não for especificada, o comportamento padrão específico da linguagem será usado, se necessário. (Para evitar que uma transformação em uma determinada direção aconteça, deve-se também escrever uma função de transformação que sempre apresenta erros.)

Para poder criar uma transformação, é necessário ser o dono e ter o privilégio USAGE no tipo de dados, ter o privilégio USAGE na linguagem, e ser o dono e ter o privilégio EXECUTE nas funções “do SQL” e “para o SQL”, se estas forem especificadas.

Parâmetros

nome_do_tipo_de_dados: O nome do tipo de dados da transformação.
nome_da_linguagem: O nome da linguagem da transformação.
nome_da_função_do_sql[ (tipo_de_dados_do_argumento [, ...])]: O nome da função para converter o tipo de dados do ambiente SQL para a linguagem. Deve receber um argumento do tipo de dados internal, e retornar o tipo de dados internal. O argumento real será do tipo de dados para a transformação, e a função deve ser codificada como se assim fosse. (Mas não é permitido declarar uma função no nível do SQL retornando internal, sem ter pelo menos um argumento do tipo de dados internal.) O valor retornado real será algo específico para a implementação da linguagem. Se não for especificada nenhuma lista de argumentos, o nome da função deverá ser único em seu esquema.
nome_da_função_para_o_sql[ (tipo_de_dados_do_argumento [, ...])]: O nome da função para converter o tipo de dados da linguagem para o ambiente SQL. Deve receber um argumento do tipo de dados internal, e retornar o tipo de dados que é o tipo de dados para a transformação. O valor real do argumento será algo específico para a implementação da linguagem. Se não for especificada nenhuma lista de argumentos, o nome da função deverá ser único em seu esquema.

Notas

Deve-se usar o comando DROP TRANSFORM para remover transformações.

Exemplos

Para criar uma transformação para o tipo de dados hstore e a linguagem plpython3u, primeiro deve ser configurado o tipo de dados e a linguagem:

CREATE TYPE hstore ...;

CREATE EXTENSION plpython3u;

Em seguida, criadas as funções necessárias:

CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
LANGUAGE C STRICT IMMUTABLE
AS ...;

CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
LANGUAGE C STRICT IMMUTABLE
AS ...;

E, finalmente, criada a transformação para conectá-los todos juntos:

CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
    FROM SQL WITH FUNCTION hstore_to_plpython(internal),
    TO SQL WITH FUNCTION plpython_to_hstore(internal)
);

Na prática, estes comandos seriam empacotados em uma extensão.

O diretório contrib da distribuição do código-fonte contém várias extensões que fornecem transformações, que podem servir como exemplos do mundo real.

Conformidade

Esta forma do comando CREATE TRANSFORM é uma extensão do PostgreSQL. Existe o comando CREATE TRANSFORM no padrão SQL, mas é para adaptar os tipos de dados às linguagens do cliente. Este uso não tem suporte pelo PostgreSQL.

Veja também

CREATE FUNCTION, CREATE LANGUAGE, CREATE TYPE, DROP TRANSFORM

^[142] O comando CREATE TRANSFORM define funções de transformação, identificadas por um nome de grupo, que são usadas para trocar valores de tipo de dados estruturados com programas da linguagem hospedeira e com funções externas. IBM DB2 12.1.x – CREATE TRANSFORM statement (N. T.)