begriffs open source - ai-pg/blob - full-docs/txt/sql-createtransform.txt

   1
   2 CREATE TRANSFORM
   3
   4    CREATE TRANSFORM — define a new transform
   5
   6 Synopsis
   7
   8 CREATE [ OR REPLACE ] TRANSFORM FOR type_name LANGUAGE lang_name (
   9     FROM SQL WITH FUNCTION from_sql_function_name [ (argument_type [, ...]) ],
  10     TO SQL WITH FUNCTION to_sql_function_name [ (argument_type [, ...]) ]
  11 );
  12
  13 Description
  14
  15    CREATE TRANSFORM defines a new transform. CREATE OR REPLACE TRANSFORM
  16    will either create a new transform, or replace an existing definition.
  17
  18    A transform specifies how to adapt a data type to a procedural
  19    language. For example, when writing a function in PL/Python using the
  20    hstore type, PL/Python has no prior knowledge how to present hstore
  21    values in the Python environment. Language implementations usually
  22    default to using the text representation, but that is inconvenient
  23    when, for example, an associative array or a list would be more
  24    appropriate.
  25
  26    A transform specifies two functions:
  27      * A “from SQL” function that converts the type from the SQL
  28        environment to the language. This function will be invoked on the
  29        arguments of a function written in the language.
  30      * A “to SQL” function that converts the type from the language to the
  31        SQL environment. This function will be invoked on the return value
  32        of a function written in the language.
  33
  34    It is not necessary to provide both of these functions. If one is not
  35    specified, the language-specific default behavior will be used if
  36    necessary. (To prevent a transformation in a certain direction from
  37    happening at all, you could also write a transform function that always
  38    errors out.)
  39
  40    To be able to create a transform, you must own and have USAGE privilege
  41    on the type, have USAGE privilege on the language, and own and have
  42    EXECUTE privilege on the from-SQL and to-SQL functions, if specified.
  43
  44 Parameters
  45
  46    type_name
  47           The name of the data type of the transform.
  48
  49    lang_name
  50           The name of the language of the transform.
  51
  52    from_sql_function_name[(argument_type [, ...])]
  53           The name of the function for converting the type from the SQL
  54           environment to the language. It must take one argument of type
  55           internal and return type internal. The actual argument will be
  56           of the type for the transform, and the function should be coded
  57           as if it were. (But it is not allowed to declare an SQL-level
  58           function returning internal without at least one argument of
  59           type internal.) The actual return value will be something
  60           specific to the language implementation. If no argument list is
  61           specified, the function name must be unique in its schema.
  62
  63    to_sql_function_name[(argument_type [, ...])]
  64           The name of the function for converting the type from the
  65           language to the SQL environment. It must take one argument of
  66           type internal and return the type that is the type for the
  67           transform. The actual argument value will be something specific
  68           to the language implementation. If no argument list is
  69           specified, the function name must be unique in its schema.
  70
  71 Notes
  72
  73    Use DROP TRANSFORM to remove transforms.
  74
  75 Examples
  76
  77    To create a transform for type hstore and language plpython3u, first
  78    set up the type and the language:
  79 CREATE TYPE hstore ...;
  80
  81 CREATE EXTENSION plpython3u;
  82
  83    Then create the necessary functions:
  84 CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
  85 LANGUAGE C STRICT IMMUTABLE
  86 AS ...;
  87
  88 CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
  89 LANGUAGE C STRICT IMMUTABLE
  90 AS ...;
  91
  92    And finally create the transform to connect them all together:
  93 CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
  94     FROM SQL WITH FUNCTION hstore_to_plpython(internal),
  95     TO SQL WITH FUNCTION plpython_to_hstore(internal)
  96 );
  97
  98    In practice, these commands would be wrapped up in an extension.
  99
 100    The contrib section contains a number of extensions that provide
 101    transforms, which can serve as real-world examples.
 102
 103 Compatibility
 104
 105    This form of CREATE TRANSFORM is a PostgreSQL extension. There is a
 106    CREATE TRANSFORM command in the SQL standard, but it is for adapting
 107    data types to client languages. That usage is not supported by
 108    PostgreSQL.
 109
 110 See Also
 111
 112    CREATE FUNCTION, CREATE LANGUAGE, CREATE TYPE, DROP TRANSFORM