CREATE CAST <refpurpose>define a new cast</refpurpose> — 新しいキャストを定義する
CREATE CAST (source_typeAStarget_type) WITH FUNCTIONfunction_name[ (argument_type[, ...]) ] [ AS ASSIGNMENT | AS IMPLICIT ] CREATE CAST (source_typeAStarget_type) WITHOUT FUNCTION [ AS ASSIGNMENT | AS IMPLICIT ] CREATE CAST (source_typeAStarget_type) WITH INOUT [ AS ASSIGNMENT | AS IMPLICIT ]
<command>CREATE CAST</command> defines a new cast. A cast
specifies how to perform a conversion between
two data types. For example,
CREATE CASTを使用すると、新しいキャストを定義できます。
キャストは、2つのデータ型間の変換処理方法を指定するものです。
以下に例を示します。
SELECT CAST(42 AS float8);
converts the integer constant 42 to type <type>float8</type> by
invoking a previously specified function, in this case
<literal>float8(int4)</literal>. (If no suitable cast has been defined, the
conversion fails.)
この文を実行すると、事前に指定された関数（この場合float8(int4)）が呼び出され、整数定数42がfloat8型に変換されます。
（適切なキャストが定義されていない場合、変換処理は失敗します。）
Two types can be <firstterm>binary coercible</firstterm>, which
means that the conversion can be performed <quote>for free</quote>
without invoking any function. This requires that corresponding
values use the same internal representation. For instance, the
types <type>text</type> and <type>varchar</type> are binary
coercible both ways. Binary coercibility is not necessarily a
symmetric relationship. For example, the cast
from <type>xml</type> to <type>text</type> can be performed for
free in the present implementation, but the reverse direction
requires a function that performs at least a syntax check. (Two
types that are binary coercible both ways are also referred to as
binary compatible.)
2つのデータ型をバイナリ強制互換とすることができます。
これは、関数をまったく呼び出さなくても、「自由に」変換を行うことができることを意味します。
これには、対応する値は、同じ内部表現を使用している必要があります。
例えば、データ型textとvarcharには、両方向でバイナリ互換性があります。
バイナリ強制互換性は必ずしも対称関係ではありません。
例えば、現在の実装ではxmlからtextへのキャストは自由に行うことができますが、逆方向では少なくとも構文検査を行う関数が必要です。
（2つの型が両方向でバイナリ強制互換であることは、バイナリ互換性と呼ばれます。）
You can define a cast as an <firstterm>I/O conversion cast</firstterm> by using
the <literal>WITH INOUT</literal> syntax. An I/O conversion cast is
performed by invoking the output function of the source data type, and
passing the resulting string to the input function of the target data type.
In many common cases, this feature avoids the need to write a separate
cast function for conversion. An I/O conversion cast acts the same as
a regular function-based cast; only the implementation is different.
WITH INOUT構文を使用してI/O変換キャストとしてキャスト定義を行うことができます。
I/O変換キャストは、元データ型の出力関数を呼び出し、その結果文字列を対象データ型の入力関数に渡すことで行われます。
多くの一般的な場合では、この機能により変換用に別個のキャスト関数を作成する必要性がなくなります。
I/O変換キャストは通常の関数を基にしたキャストと同様に動作します。ただ実装が異なるだけです。
By default, a cast can be invoked only by an explicit cast request,
that is an explicit <literal>CAST(<replaceable>x</replaceable> AS
<replaceable>typename</replaceable>)</literal> or
<replaceable>x</replaceable><literal>::</literal><replaceable>typename</replaceable>
construct.
デフォルトでは、キャストは明示的なキャスト要求があった場合のみ発生します。
明示的なキャスト要求の構文は、CAST(、もしくは、x AS typename)x::typename式です。
If the cast is marked <literal>AS ASSIGNMENT</literal> then it can be invoked
implicitly when assigning a value to a column of the target data type.
For example, supposing that <literal>foo.f1</literal> is a column of
type <type>text</type>, then:
キャストにAS ASSIGNMENTオプションを付けると、対象データ型の列に代入する際、暗黙的にそのキャストを発生させることができます。
例えば、foo.f1がtext型の列であるとします。
INSERT INTO foo (f1) VALUES (42);
will be allowed if the cast from type <type>integer</type> to type
<type>text</type> is marked <literal>AS ASSIGNMENT</literal>, otherwise not.
(We generally use the term <firstterm>assignment
cast</firstterm> to describe this kind of cast.)
integer型をtext型に変換するキャストにAS ASSIGNMENTオプションが付けられていれば、上記のSQL文が実行できます。
しかし、AS ASSIGNMENTオプションが付いていなければ、実行できません。
（一般的に、この種のキャストを代入キャストと呼びます。）
If the cast is marked <literal>AS IMPLICIT</literal> then it can be invoked
implicitly in any context, whether assignment or internally in an
expression. (We generally use the term <firstterm>implicit
cast</firstterm> to describe this kind of cast.)
For example, consider this query:
キャストにAS IMPLICITオプションを付けると、代入の場合だけでなく、式の中にある場合でも、全てのコンテキストで暗黙的にそのキャストを呼び出すことができます。
（一般的に、この種のキャストを暗黙キャストと呼びます。）
例えば次のような問い合わせを考えてみます。
SELECT 2 + 4.0;
The parser initially marks the constants as being of type <type>integer</type>
and <type>numeric</type> respectively. There is no <type>integer</type>
<literal>+</literal> <type>numeric</type> operator in the system catalogs,
but there is a <type>numeric</type> <literal>+</literal> <type>numeric</type> operator.
The query will therefore succeed if a cast from <type>integer</type> to
<type>numeric</type> is available and is marked <literal>AS IMPLICIT</literal> —
which in fact it is. The parser will apply the implicit cast and resolve
the query as if it had been written
パーサはまず定数にそれぞれintegerとnumericであると印を付けます。
システムカタログには、integer + numericという演算子はありませんが、numeric + numericという演算子は存在します。
したがって、integerからnumericへのキャストが利用可能であり、そのキャストにAS IMPLICITが付いていればこの問い合わせは成功します（実際このようになっています）。
パーサは暗黙的なキャストを行い、問い合わせをあたかも次のように記載されたものとして解決します。
SELECT CAST ( 2 AS numeric ) + 4.0;
Now, the catalogs also provide a cast from <type>numeric</type> to
<type>integer</type>. If that cast were marked <literal>AS IMPLICIT</literal> —
which it is not — then the parser would be faced with choosing
between the above interpretation and the alternative of casting the
<type>numeric</type> constant to <type>integer</type> and applying the
<type>integer</type> <literal>+</literal> <type>integer</type> operator. Lacking any
knowledge of which choice to prefer, it would give up and declare the
query ambiguous. The fact that only one of the two casts is
implicit is the way in which we teach the parser to prefer resolution
of a mixed <type>numeric</type>-and-<type>integer</type> expression as
<type>numeric</type>; there is no built-in knowledge about that.
ここで、カタログはまたnumericからintegerへのキャストも提供しています。
もしこのキャストにAS IMPLICITが付いていたら（実際は付いていません）、パーサは上のように解釈するか、それとも、numeric定数をintegerにキャストし、integer + integerという演算子を適用するかを選択しなければなりません。
どちらがより良いかという知見がなければ、選択をあきらめ、問い合わせがあいまいであると宣告します。
2つのキャストの内1つのみが暗黙的であるという事実が、パーサに、numericとintegerが混在する式をnumericとして扱うという適切な解決方法を知らせる方法です。
これに関する組み込まれた知見は存在しません。
It is wise to be conservative about marking casts as implicit. An
overabundance of implicit casting paths can cause
<productname>PostgreSQL</productname> to choose surprising
interpretations of commands, or to be unable to resolve commands at
all because there are multiple possible interpretations. A good
rule of thumb is to make a cast implicitly invokable only for
information-preserving transformations between types in the same
general type category. For example, the cast from <type>int2</type> to
<type>int4</type> can reasonably be implicit, but the cast from
<type>float8</type> to <type>int4</type> should probably be
assignment-only. Cross-type-category casts, such as <type>text</type>
to <type>int4</type>, are best made explicit-only.
暗黙キャストは、多用しない方が賢明です。
暗黙的キャストを使用し過ぎると、PostgreSQLがコマンドを思わぬ意味に解釈してしまう原因になります。
また、複数の解釈が可能なため、コマンドをまったく解読できなくなってしまう可能性もあります。
経験的には、2つのデータ型が同一の一般的なデータ型のカテゴリに属しており、変換によって情報が保持される場合のみ、暗黙キャストを呼び出し可能にするのが良い方法と思われます。
例えば、int2型からint4型へのキャストは、暗黙キャストにするのが妥当ですが、float8型からint4型へのキャストは、おそらく代入キャストのみにすべきでしょう。
text型からint4型への変換のような、カテゴリを越えるデータ型のキャストは、明示的にのみ使用するのが適切です。
Sometimes it is necessary for usability or standards-compliance reasons to provide multiple implicit casts among a set of types, resulting in ambiguity that cannot be avoided as above. The parser has a fallback heuristic based on <firstterm>type categories</firstterm> and <firstterm>preferred types</firstterm> that can help to provide desired behavior in such cases. See <xref linkend="sql-createtype"/> for more information. 型の集合の中で複数の暗黙的なキャストを提供することが、有用性や標準との互換性上の理由により必要となることがあり、これにより、上で説明した通り防ぐことができないあいまいさが引き起こされます。 パーサは、こうした状況でも望ましい動作の提供を補助できる型カテゴリと優先される型に基づいた発見的手法を用意しています。 詳細はCREATE TYPEを参照してください。
To be able to create a cast, you must own the source or the target data type
and have <literal>USAGE</literal> privilege on the other type. To create a
binary-coercible cast, you must be superuser. (This restriction is made
because an erroneous binary-coercible cast conversion can easily crash the
server.)
キャストを作成するためには、変換元または変換先（の内の一方）のデータ型を所有し、もう一方の型に対するUSAGE権限を持つ必要があります。
また、バイナリ強制互換性を持つキャストを作成できるのは、スーパーユーザでなければなりません。
（バイナリ強制互換性があるキャスト変換を誤って使用するとサーバがクラッシュしてしまう可能性が高いことから、この制限が付けられました）。
source_typeThe name of the source data type of the cast. キャストする変換元のデータ型の名前です。
target_typeThe name of the target data type of the cast. キャストする変換先のデータ型の名前です。
function_name[(argument_type [, ...])]The function used to perform the cast. The function name can be schema-qualified. If it is not, the function will be looked up in the schema search path. The function's result data type must match the target type of the cast. Its arguments are discussed below. If no argument list is specified, the function name must be unique in its schema. キャストを実行するために使用される関数です。 関数名はスキーマ修飾することができます。 スキーマ修飾されていない場合、関数はスキーマ検索パスから検索されます。 関数の結果のデータ型は、キャストの変換先のデータ型と一致する必要があります。 引数については後で説明します。 引数リストが指定されない場合、関数名はスキーマ内で一意でなければなりません。
WITHOUT FUNCTIONIndicates that the source type is binary-coercible to the target type, so no function is required to perform the cast. 変換元データ型から変換先データ型への間に、バイナリ強制互換性があることを示します。 この場合、キャストを実行するのに関数は必要ありません。
WITH INOUTIndicates that the cast is an I/O conversion cast, performed by invoking the output function of the source data type, and passing the resulting string to the input function of the target data type. キャストが、変換元データ型の出力関数を呼び出し、その結果の文字列を変換先データ型の入力関数に渡すことで行われる、I/O変換キャストであることを示します。
AS ASSIGNMENTIndicates that the cast can be invoked implicitly in assignment contexts. 代入コンテキストで、暗黙的にキャストを呼び出せることを示します。
AS IMPLICITIndicates that the cast can be invoked implicitly in any context. 任意のコンテキストで、暗黙的にキャストを呼び出せることを示します。
Cast implementation functions can have one to three arguments.
The first argument type must be identical to or binary-coercible from
the cast's source type. The second argument,
if present, must be type <type>integer</type>; it receives the type
modifier associated with the destination type, or <literal>-1</literal>
if there is none. The third argument,
if present, must be type <type>boolean</type>; it receives <literal>true</literal>
if the cast is an explicit cast, <literal>false</literal> otherwise.
(Bizarrely, the SQL standard demands different behaviors for explicit and
implicit casts in some cases. This argument is supplied for functions
that must implement such casts. It is not recommended that you design
your own data types so that this matters.)
キャストを実装する関数は1〜3個の引数を取ることができます。
1番目の引数型はキャストの変換元データ型と同一、または、変換元データ型からのバイナリ強制互換を持つ型でなければなりません。
2番目の引数（もしあれば）は、integer型でなければなりません。変換先の型に関連付けられた型修飾子を指定します。
型修飾子がない場合は-1を指定します。
3番目の引数（もしあれば）は、boolean型でなければなりません。キャストが明示的なキャストであればtrueを、それ以外であればfalseを指定します。
（奇妙な話ですが、標準SQLでは、明示的キャストと暗黙的キャストとの間で異なる振舞いを要求する場合があります。
この引数はそのようなキャストを実装しなければならない関数用に提供されています。
独自のデータ型をこの流儀に従うように設計することは勧められません。）
The return type of a cast function must be identical to or binary-coercible to the cast's target type. キャスト関数の戻り値は、キャストの対象型と同一またはバイナリ強制互換性を持たなければなりません。
Ordinarily a cast must have different source and target data types. However, it is allowed to declare a cast with identical source and target types if it has a cast implementation function with more than one argument. This is used to represent type-specific length coercion functions in the system catalogs. The named function is used to coerce a value of the type to the type modifier value given by its second argument. 通常、キャストにおける変換元データ型と変換先データ型は異なる必要があります。 しかし、2つ以上の引数を持つ関数でキャストを実装した場合は、変換元と変換先とで同一のデータ型を持つキャストを宣言することができます。 これは、システムカタログにおいて型固有の長さ強制関数を表現するために使用されています。 指定された関数は、型の値を強制的に2番目の引数で与えられた型修飾子の値にするために使用されます。
When a cast has different source and target types and a function that takes more than one argument, it supports converting from one type to another and applying a length coercion in a single step. When no such entry is available, coercion to a type that uses a type modifier involves two cast steps, one to convert between data types and a second to apply the modifier. キャストが変換元と変換先のデータ型が異なり、複数の引数を取る関数を持つ場合、あるデータ型から他のデータ型への変換と長さの強制を1つの操作にまとめたものをサポートします。 引数を1つしか取らない場合は、型修飾子を使用して型を強制するために、データ型間の変換と修飾子の適用という2つのキャスト操作が必要となります。
A cast to or from a domain type currently has no effect. Casting to or from a domain uses the casts associated with its underlying type. ドメイン型へのキャスト、ドメイン型からのキャストは現在は効果がありません。 ドメインへのキャスト、ドメインからのキャストは、基となる型と関連したキャストを使用します。
Use <link linkend="sql-dropcast"><command>DROP CAST</command></link> to remove user-defined casts.
ユーザ定義のキャストを削除するにはDROP CASTを使用してください。
Remember that if you want to be able to convert types both ways you need to declare casts both ways explicitly. データ型を双方向に変更可能にするには、双方向のキャストを明示的に宣言する必要があることに注意してください。
It is normally not necessary to create casts between user-defined types
and the standard string types (<type>text</type>, <type>varchar</type>, and
<type>char(<replaceable>n</replaceable>)</type>, as well as user-defined types that
are defined to be in the string category). <productname>PostgreSQL</productname>
provides automatic I/O conversion casts for that. The automatic casts to
string types are treated as assignment casts, while the automatic casts
from string types are
explicit-only. You can override this behavior by declaring your own
cast to replace an automatic cast, but usually the only reason to
do so is if you want the conversion to be more easily invokable than the
standard assignment-only or explicit-only setting. Another possible
reason is that you want the conversion to behave differently from the
type's I/O function; but that is sufficiently surprising that you
should think twice about whether it's a good idea. (A small number of
the built-in types do indeed have different behaviors for conversions,
mostly because of requirements of the SQL standard.)
ユーザ定義型と標準文字列型（text、varchar、char(）、および文字列カテゴリとして定義されたユーザ定義型との間のキャストを作成することは、通常必要ありません。
PostgreSQLはこのために自動的なI/O変換キャストを提供します。
この文字列への自動キャストは代入キャストとして扱われますが、文字列型からの入出力変換キャストは明示的なキャストのみです。
この振舞いは独自のキャストを宣言して自動キャストを置き換えることで変更することができます。
しかし、通常このようにするのは、この変換を標準の代入のみまたは明示的のみの設定よりもより呼び出しやすくしたい場合に限られます。
他にも、型の入出力関数と異なる動作で変換したいという理由もあるかもしれません。
しかし、これは非常に驚かされるものであり、そうすべきかどうか熟考すべきです。
（組み込み型のごく一部は実際変換用に異なった振舞いをしますが、ほとんどは標準SQLの仕様のためのものです。）
n)
While not required, it is recommended that you continue to follow this old
convention of naming cast implementation functions after the target data
type. Many users are used to being able to cast data types using a
function-style notation, that is
<replaceable>typename</replaceable>(<replaceable>x</replaceable>). This notation is in fact
nothing more nor less than a call of the cast implementation function; it
is not specially treated as a cast. If your conversion functions are not
named to support this convention then you will have surprised users.
Since <productname>PostgreSQL</productname> allows overloading of the same function
name with different argument types, there is no difficulty in having
multiple conversion functions from different types that all use the
target type's name.
必須ではありませんが、キャストを実装する関数には変換先のデータ型の名前を付けるという以前からの慣習に従っておくことを推奨します。
多くのユーザはtypename(x)という関数スタイルの記法でデータ型のキャストを行っています。
この記法は、キャストを実装している関数の呼び出しに他なりません。
キャストとして特別に扱われるわけではないのです。
ユーザが作成した変換関数の名前がこの慣習に従っていないと、他のユーザがとまどうことになります。
PostgreSQLは引数として異なる型を取る同じ名前の関数をオーバーロードすることができるので、様々な型から特定の変換先型への変換関数の名前を全て変換先の型名にしても特に問題は発生しません。
Actually the preceding paragraph is an oversimplification: there are
two cases in which a function-call construct will be treated as a cast
request without having matched it to an actual function.
If a function call <replaceable>name</replaceable>(<replaceable>x</replaceable>) does not
exactly match any existing function, but <replaceable>name</replaceable> is the name
of a data type and <structname>pg_cast</structname> provides a binary-coercible cast
to this type from the type of <replaceable>x</replaceable>, then the call will be
construed as a binary-coercible cast. This exception is made so that
binary-coercible casts can be invoked using functional syntax, even
though they lack any function. Likewise, if there is no
<structname>pg_cast</structname> entry but the cast would be to or from a string
type, the call will be construed as an I/O conversion cast. This
exception allows I/O conversion casts to be invoked using functional
syntax.
実際のところ、前の段落は単純化しすぎたものです。
関数呼び出し式が実際の関数と一致しない状態でキャスト要求として扱われる状況が2つ存在します。
関数呼び出しname(x)が実際の関数に正確に一致せず、nameがデータ型の名前であり、pg_castがxの型からその型へのバイナリ強制互換のキャストを提供する場合、この呼び出しはバイナリ強制互換キャストとして処理されます。
この例外は、実際の関数が存在しなくても、関数のような構文でバイナリ強制互換キャストを呼び出すことができるように作成されました。
同様に、pg_castに項目がないが、文字列型との間のキャストが存在する場合、この呼び出しは入出力変換キャストとして処理されます。
この例外により関数のような構文で入出力変換キャストができるようになります。
There is also an exception to the exception: I/O conversion casts from
composite types to string types cannot be invoked using functional
syntax, but must be written in explicit cast syntax (either
<literal>CAST</literal> or <literal>::</literal> notation). This exception was added
because after the introduction of automatically-provided I/O conversion
casts, it was found too easy to accidentally invoke such a cast when
a function or column reference was intended.
この例外にも例外があります。
複合型から文字列型へのI/O変換キャストでは関数構文を使用して呼び出すことができず、明示的なキャスト構文（CAST記法または::記法のいずれか）で記述しなければなりません。
この例外は、自動提供I/O変換キャストを導入した後、関数または列参照を意図した時に非常に簡単に間違って呼び出されることが判明したため追加されました。
To create an assignment cast from type <type>bigint</type> to type
<type>int4</type> using the function <literal>int4(bigint)</literal>:
関数int4(bigint)を使用したbigint型からint4型への代入キャストを作成します。
CREATE CAST (bigint AS int4) WITH FUNCTION int4(bigint) AS ASSIGNMENT;
(This cast is already predefined in the system.) （このキャストは、システムに既に定義されています。）
The <command>CREATE CAST</command> command conforms to the
<acronym>SQL</acronym> standard,
except that SQL does not make provisions for binary-coercible
types or extra arguments to implementation functions.
<literal>AS IMPLICIT</literal> is a <productname>PostgreSQL</productname>
extension, too.
SQLではバイナリ強制互換性があるデータ型や実装関数の追加の引数について規定されていません。さらに、AS IMPLICITは、PostgreSQLの拡張です。
これらの点以外では、CREATE CASTは標準SQLに準拠しています。