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

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>CREATE TRANSFORM</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE" /><link rel="next" href="sql-createtrigger.html" title="CREATE TRIGGER" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center">CREATE TRANSFORM</th></tr><tr><td width="10%" align="left"><a accesskey="p" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><th width="60%" align="center">SQL Commands</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="sql-createtrigger.html" title="CREATE TRIGGER">Next</a></td></tr></table><hr /></div><div class="refentry" id="SQL-CREATETRANSFORM"><div class="titlepage"></div><a id="id-1.9.3.92.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle">CREATE TRANSFORM</span></h2><p>CREATE TRANSFORM — define a new transform</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><pre class="synopsis">
   3 CREATE [ OR REPLACE ] TRANSFORM FOR <em class="replaceable"><code>type_name</code></em> LANGUAGE <em class="replaceable"><code>lang_name</code></em> (
   4     FROM SQL WITH FUNCTION <em class="replaceable"><code>from_sql_function_name</code></em> [ (<em class="replaceable"><code>argument_type</code></em> [, ...]) ],
   5     TO SQL WITH FUNCTION <em class="replaceable"><code>to_sql_function_name</code></em> [ (<em class="replaceable"><code>argument_type</code></em> [, ...]) ]
   6 );
   7 </pre></div><div class="refsect1" id="SQL-CREATETRANSFORM-DESCRIPTION"><h2>Description</h2><p>
   8    <code class="command">CREATE TRANSFORM</code> defines a new transform.
   9    <code class="command">CREATE OR REPLACE TRANSFORM</code> will either create a new
  10    transform, or replace an existing definition.
  11   </p><p>
  12    A transform specifies how to adapt a data type to a procedural language.
  13    For example, when writing a function in PL/Python using
  14    the <code class="type">hstore</code> type, PL/Python has no prior knowledge how to
  15    present <code class="type">hstore</code> values in the Python environment.  Language
  16    implementations usually default to using the text representation, but that
  17    is inconvenient when, for example, an associative array or a list would be
  18    more appropriate.
  19   </p><p>
  20    A transform specifies two functions:
  21    </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
  22       A <span class="quote">“<span class="quote">from SQL</span>”</span> function that converts the type from the SQL
  23       environment to the language.  This function will be invoked on the
  24       arguments of a function written in the language.
  25      </p></li><li class="listitem"><p>
  26       A <span class="quote">“<span class="quote">to SQL</span>”</span> function that converts the type from the
  27       language to the SQL environment.  This function will be invoked on the
  28       return value of a function written in the language.
  29      </p></li></ul></div><p>
  30    It is not necessary to provide both of these functions.  If one is not
  31    specified, the language-specific default behavior will be used if
  32    necessary.  (To prevent a transformation in a certain direction from
  33    happening at all, you could also write a transform function that always
  34    errors out.)
  35   </p><p>
  36    To be able to create a transform, you must own and
  37    have <code class="literal">USAGE</code> privilege on the type, have
  38    <code class="literal">USAGE</code> privilege on the language, and own and
  39    have <code class="literal">EXECUTE</code> privilege on the from-SQL and to-SQL
  40    functions, if specified.
  41   </p></div><div class="refsect1" id="id-1.9.3.92.6"><h2>Parameters</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>type_name</code></em></span></dt><dd><p>
  42        The name of the data type of the transform.
  43       </p></dd><dt><span class="term"><em class="replaceable"><code>lang_name</code></em></span></dt><dd><p>
  44        The name of the language of the transform.
  45       </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>from_sql_function_name</code></em>[(<em class="replaceable"><code>argument_type</code></em> [, ...])]</code></span></dt><dd><p>
  46        The name of the function for converting the type from the SQL
  47        environment to the language.  It must take one argument of
  48        type <code class="type">internal</code> and return type <code class="type">internal</code>.  The
  49        actual argument will be of the type for the transform, and the function
  50        should be coded as if it were.  (But it is not allowed to declare an
  51        SQL-level function returning <code class="type">internal</code> without at
  52        least one argument of type <code class="type">internal</code>.)  The actual return
  53        value will be something specific to the language implementation.
  54        If no argument list is specified, the function name must be unique in
  55        its schema.
  56       </p></dd><dt><span class="term"><code class="literal"><em class="replaceable"><code>to_sql_function_name</code></em>[(<em class="replaceable"><code>argument_type</code></em> [, ...])]</code></span></dt><dd><p>
  57        The name of the function for converting the type from the language to
  58        the SQL environment.  It must take one argument of type
  59        <code class="type">internal</code> and return the type that is the type for the
  60        transform.  The actual argument value will be something specific to the
  61        language implementation.
  62        If no argument list is specified, the function name must be unique in
  63        its schema.
  64       </p></dd></dl></div></div><div class="refsect1" id="SQL-CREATETRANSFORM-NOTES"><h2>Notes</h2><p>
  65    Use <a class="link" href="sql-droptransform.html" title="DROP TRANSFORM"><code class="command">DROP TRANSFORM</code></a> to remove transforms.
  66   </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-EXAMPLES"><h2>Examples</h2><p>
  67    To create a transform for type <code class="type">hstore</code> and language
  68    <code class="literal">plpython3u</code>, first set up the type and the language:
  69 </p><pre class="programlisting">
  70 CREATE TYPE hstore ...;
  71
  72 CREATE EXTENSION plpython3u;
  73 </pre><p>
  74    Then create the necessary functions:
  75 </p><pre class="programlisting">
  76 CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
  77 LANGUAGE C STRICT IMMUTABLE
  78 AS ...;
  79
  80 CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
  81 LANGUAGE C STRICT IMMUTABLE
  82 AS ...;
  83 </pre><p>
  84    And finally create the transform to connect them all together:
  85 </p><pre class="programlisting">
  86 CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
  87     FROM SQL WITH FUNCTION hstore_to_plpython(internal),
  88     TO SQL WITH FUNCTION plpython_to_hstore(internal)
  89 );
  90 </pre><p>
  91    In practice, these commands would be wrapped up in an extension.
  92   </p><p>
  93    The <code class="filename">contrib</code> section contains a number of extensions
  94    that provide transforms, which can serve as real-world examples.
  95   </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-COMPAT"><h2>Compatibility</h2><p>
  96    This form of <code class="command">CREATE TRANSFORM</code> is a
  97    <span class="productname">PostgreSQL</span> extension.  There is a <code class="command">CREATE
  98    TRANSFORM</code> command in the <acronym class="acronym">SQL</acronym> standard, but it
  99    is for adapting data types to client languages.  That usage is not supported
 100    by <span class="productname">PostgreSQL</span>.
 101   </p></div><div class="refsect1" id="SQL-CREATETRANSFORM-SEEALSO"><h2>See Also</h2><p>
 102    <a class="xref" href="sql-createfunction.html" title="CREATE FUNCTION"><span class="refentrytitle">CREATE FUNCTION</span></a>,
 103    <a class="xref" href="sql-createlanguage.html" title="CREATE LANGUAGE"><span class="refentrytitle">CREATE LANGUAGE</span></a>,
 104    <a class="xref" href="sql-createtype.html" title="CREATE TYPE"><span class="refentrytitle">CREATE TYPE</span></a>,
 105    <a class="xref" href="sql-droptransform.html" title="DROP TRANSFORM"><span class="refentrytitle">DROP TRANSFORM</span></a>
 106   </p></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="sql-createtstemplate.html" title="CREATE TEXT SEARCH TEMPLATE">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="sql-commands.html" title="SQL Commands">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="sql-createtrigger.html" title="CREATE TRIGGER">Next</a></td></tr><tr><td width="40%" align="left" valign="top">CREATE TEXT SEARCH TEMPLATE </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> CREATE TRIGGER</td></tr></table></div></body></html>