begriffs open source - ai-pg/blob - full-docs/man7/CREATE_TRANSFORM.7

   1 '\" t
   2 .\"     Title: CREATE TRANSFORM
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE TRANSFORM" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_TRANSFORM \- define a new transform
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE [ OR REPLACE ] TRANSFORM FOR \fItype_name\fR LANGUAGE \fIlang_name\fR (
  36     FROM SQL WITH FUNCTION \fIfrom_sql_function_name\fR [ (\fIargument_type\fR [, \&.\&.\&.]) ],
  37     TO SQL WITH FUNCTION \fIto_sql_function_name\fR [ (\fIargument_type\fR [, \&.\&.\&.]) ]
  38 );
  39 .fi
  40 .SH "DESCRIPTION"
  41 .PP
  42 \fBCREATE TRANSFORM\fR
  43 defines a new transform\&.
  44 \fBCREATE OR REPLACE TRANSFORM\fR
  45 will either create a new transform, or replace an existing definition\&.
  46 .PP
  47 A transform specifies how to adapt a data type to a procedural language\&. For example, when writing a function in PL/Python using the
  48 hstore
  49 type, PL/Python has no prior knowledge how to present
  50 hstore
  51 values in the Python environment\&. Language implementations usually default to using the text representation, but that is inconvenient when, for example, an associative array or a list would be more appropriate\&.
  52 .PP
  53 A transform specifies two functions:
  54 .sp
  55 .RS 4
  56 .ie n \{\
  57 \h'-04'\(bu\h'+03'\c
  58 .\}
  59 .el \{\
  60 .sp -1
  61 .IP \(bu 2.3
  62 .\}
  63 A
  64 \(lqfrom SQL\(rq
  65 function that converts the type from the SQL environment to the language\&. This function will be invoked on the arguments of a function written in the language\&.
  66 .RE
  67 .sp
  68 .RS 4
  69 .ie n \{\
  70 \h'-04'\(bu\h'+03'\c
  71 .\}
  72 .el \{\
  73 .sp -1
  74 .IP \(bu 2.3
  75 .\}
  76 A
  77 \(lqto SQL\(rq
  78 function that converts the type from the language to the SQL environment\&. This function will be invoked on the return value of a function written in the language\&.
  79 .RE
  80 .sp
  81 It is not necessary to provide both of these functions\&. If one is not specified, the language\-specific default behavior will be used if necessary\&. (To prevent a transformation in a certain direction from happening at all, you could also write a transform function that always errors out\&.)
  82 .PP
  83 To be able to create a transform, you must own and have
  84 USAGE
  85 privilege on the type, have
  86 USAGE
  87 privilege on the language, and own and have
  88 EXECUTE
  89 privilege on the from\-SQL and to\-SQL functions, if specified\&.
  90 .SH "PARAMETERS"
  91 .PP
  92 \fItype_name\fR
  93 .RS 4
  94 The name of the data type of the transform\&.
  95 .RE
  96 .PP
  97 \fIlang_name\fR
  98 .RS 4
  99 The name of the language of the transform\&.
 100 .RE
 101 .PP
 102 \fIfrom_sql_function_name\fR[(\fIargument_type\fR [, \&.\&.\&.])]
 103 .RS 4
 104 The name of the function for converting the type from the SQL environment to the language\&. It must take one argument of type
 105 internal
 106 and return type
 107 internal\&. The actual argument will be of the type for the transform, and the function should be coded as if it were\&. (But it is not allowed to declare an SQL\-level function returning
 108 internal
 109 without at least one argument of type
 110 internal\&.) The actual return value will be something specific to the language implementation\&. If no argument list is specified, the function name must be unique in its schema\&.
 111 .RE
 112 .PP
 113 \fIto_sql_function_name\fR[(\fIargument_type\fR [, \&.\&.\&.])]
 114 .RS 4
 115 The name of the function for converting the type from the language to the SQL environment\&. It must take one argument of type
 116 internal
 117 and return the type that is the type for the transform\&. The actual argument value will be something specific to the language implementation\&. If no argument list is specified, the function name must be unique in its schema\&.
 118 .RE
 119 .SH "NOTES"
 120 .PP
 121 Use
 122 \fBDROP TRANSFORM\fR
 123 to remove transforms\&.
 124 .SH "EXAMPLES"
 125 .PP
 126 To create a transform for type
 127 hstore
 128 and language
 129 plpython3u, first set up the type and the language:
 130 .sp
 131 .if n \{\
 132 .RS 4
 133 .\}
 134 .nf
 135 CREATE TYPE hstore \&.\&.\&.;
 136
 137 CREATE EXTENSION plpython3u;
 138 .fi
 139 .if n \{\
 140 .RE
 141 .\}
 142 .sp
 143 Then create the necessary functions:
 144 .sp
 145 .if n \{\
 146 .RS 4
 147 .\}
 148 .nf
 149 CREATE FUNCTION hstore_to_plpython(val internal) RETURNS internal
 150 LANGUAGE C STRICT IMMUTABLE
 151 AS \&.\&.\&.;
 152
 153 CREATE FUNCTION plpython_to_hstore(val internal) RETURNS hstore
 154 LANGUAGE C STRICT IMMUTABLE
 155 AS \&.\&.\&.;
 156 .fi
 157 .if n \{\
 158 .RE
 159 .\}
 160 .sp
 161 And finally create the transform to connect them all together:
 162 .sp
 163 .if n \{\
 164 .RS 4
 165 .\}
 166 .nf
 167 CREATE TRANSFORM FOR hstore LANGUAGE plpython3u (
 168     FROM SQL WITH FUNCTION hstore_to_plpython(internal),
 169     TO SQL WITH FUNCTION plpython_to_hstore(internal)
 170 );
 171 .fi
 172 .if n \{\
 173 .RE
 174 .\}
 175 .sp
 176 In practice, these commands would be wrapped up in an extension\&.
 177 .PP
 178 The
 179 contrib
 180 section contains a number of extensions that provide transforms, which can serve as real\-world examples\&.
 181 .SH "COMPATIBILITY"
 182 .PP
 183 This form of
 184 \fBCREATE TRANSFORM\fR
 185 is a
 186 PostgreSQL
 187 extension\&. There is a
 188 \fBCREATE TRANSFORM\fR
 189 command in the
 190 SQL
 191 standard, but it is for adapting data types to client languages\&. That usage is not supported by
 192 PostgreSQL\&.
 193 .SH "SEE ALSO"
 194 .PP
 195 CREATE FUNCTION (\fBCREATE_FUNCTION\fR(7)),
 196 CREATE LANGUAGE (\fBCREATE_LANGUAGE\fR(7)),
 197 CREATE TYPE (\fBCREATE_TYPE\fR(7)),
 198 DROP TRANSFORM (\fBDROP_TRANSFORM\fR(7))