COPY

Name

COPY  --  Copies data between files and tables ファイルとテーブル間でデータをコピーします。

Synopsis

COPY [ BINARY ] table [ WITH OIDS ]
    FROM { 'filename' |
   stdin }
    [ USING DELIMITERS 'delimiter' ]
COPY [ BINARY ] table [ WITH OIDS ]
    TO { 'filename' |
   stdout }
    [ USING DELIMITERS 'delimiter' ]
  

入力

BINARY

Changes the behavior of field formatting, forcing all data to be stored or read as binary objects rather than as text.

フィールドのフォーマットを全てのデータをテキストではなく バイナリで読み書きするように設定します。

table

The name of an existing table.

存在するテーブルの名前です。

WITH OIDS

Copies the internal unique object id (OID) for each row.

それぞれの行に対して内部的に一意のオブジェクト id (OID) を コピーします。

ファイル名

The absolute Unix pathname of the input or output file.

Unix の入力または出力ファイルの絶対パス名です。

stdin

Specifies that input comes from a pipe or terminal.

入力がパイプ経由となるのか、端末からなのかを指定します。

stdout

Specifies that output goes to a pipe or terminal.

出力がパイプ経由の指定先になるのか、端末なのか を指定します。

デリミタ

A character that delimits the input or output fields.

入力または出力のフィールドを区切る一つの文字です。

出力

COPY

The copy completed successfully.

コピーは」正常に終了しました。

ERROR: error message

The copy failed for the reason stated in the error message.

エラーメッセージに記述された理由によってコピーは失敗しました。

説明

COPY moves data between Postgres tables and standard Unix files. COPY instructs the Postgres backend to directly read from or write to a file. The file must be directly visible to the backend and the name must be specified from the viewpoint of the backend. If stdin or stdout are specified, data flows through the client frontend to the backend.

COPYPostgres の テーブルと標準 Unix ファイル間でデータを移動します。 COPYPostgres バックエンドに対し、直接、ファイルへの読み書きをするように 通告します。ファイルはバックエンドが直接見える形で、その名前も バックエンドの観点から指定されていなければなりません。 stdin または stdout が指定されている場合は、データはクライアントのフロントエンドから バックエンドに流れます。

注意事項

The BINARY keyword will force all data to be stored/read as binary objects rather than as text. It is somewhat faster than the normal copy command, but is not generally portable, and the files generated are somewhat larger, although this factor is highly dependent on the data itself. By default, a text copy uses a tab ("\t") character as a delimiter. The delimiter may also be changed to any other single character with the keyword phrase USING DELIMITERS. Characters in data fields which happen to match the delimiter character will be quoted.

キーワード BINARY は全てのデータをテキストではなくバイナリ オブジェクトとして書き込まれたり読み込まれるようにします。 普通のコピー命令より速いですが、一般的には移植性がなく、 この要素がデータそのものに大いに依存するとしても、 出来上がったファイルはいくぶん大きくなります。 デフォルトではテキストコピーはデリミタとしてタブ ("\t") 文字を使います。デリミタはキーワード句 USING DELIMITERS で 他のどのような一文字に変更することも出来ます。デリミタ文字 にたまたま一致するデータフィールド中の文字は引用符が付けられ ます。

You must have select access on any table whose values are read by COPY, and either insert or update access to a table into which values are being inserted by COPY. The backend also needs appropriate Unix permissions for any file read or written by COPY.

COPY によって既に値が読み込まれている 何らかのテーブルへのアクセスが選択されなければなりません。 そして、 COPY によって読み込まれる値を 持っているいかなるテーブルに対しても select 権限があり、 また COPY によって値が挿入されるテーブル に対しては、挿入または更新の権限がなければなりません。 バックエンドには、同時に COPY によって 読み書きされるファイルに適切な Unix のパーミッションが与え られている必要があります。

The keyword phrase USING DELIMITERS specifies a single character to be used for all delimiters between columns. If multiple characters are specified in the delimiter string, only the first character is used.

キーワード句 USING DELIMITERS はカラム間で使用される 全てのデリミタ一文字を指定します。 複数の文字がデリミタ文で指定された場合、初めの一文字が使用 されます。

Tip: Do not confuse COPY with the psql instruction \copy.

psql\copy 命令 と COPY を混同してはいけません。

ファイル形式

テキスト形式

When COPY TO is used without the BINARY option, the file generated will have each row (instance) on a single line, with each column (attribute) separated by the delimiter character. Embedded delimiter characters will be preceded by a backslash character ("\"). The attribute values themselves are strings generated by the output function associated with each attribute type. The output function for a type should not try to generate the backslash character; this will be handled by COPY itself.

BINARY オプションなしで COPY TO が使用されると、 生成されたファイルは、それぞれのカラム(属性)がデリミタ文字で区切 られた一行ごとの行(インスタンス)から成ります。 組み込まれたデリミタ文字の始めにはバックスラッシュ文字 ("\") が 付きます。属性値そのものはそれぞれの属性の型に対応した出力関数 によって生成された文字列です。型の出力関数はバックスラッシュ 文字の生成に関与してはなりません。COPY 自身 がこれを取り扱うからです。

The actual format for each instance is

それぞれのインスタンスの実際の形式は以下のようになります。

<attr1><separator><attr2><separator>...<separator><attrn><newline>
    
The oid is placed on the beginning of the line if WITH OIDS is specified. WITH OIDS が指定された場合、oid が行の先頭に付きます。

If COPY is sending its output to standard output instead of a file, it will send a backslash("\") and a period (".") followed immediately by a newline, on a separate line, when it is done. Similarly, if COPY is reading from standard input, it will expect a backslash ("\") and a period (".") followed by a newline, as the first three characters on a line to denote end-of-file. However, COPY will terminate (followed by the backend itself) if a true EOF is encountered before this special end-of-file pattern is found.

COPY がその出力をファイルではなく標準 出力に出す場合、処理の結果、それぞれ分離した行の改行のすぐ 後にバックスラッシュ ("\") と ピリオド(".") を送出します。 同様 COPY が標準入力からデータを読み込む 場合は、 ファイルの終了 (end-of-file) を規定する行の始めの 3 文字 として、改行とそれに引き続くバックスラッシュ ("\") と ピリオド(".") をがあることを前提にします。とは言っても、COPY は この特殊なファイル終了の様式が検出される 以前に正規の EOF を見付けた場合終了します。(バックエンド自身も 引き続いて終了します。)

The backslash character has other special meanings. NULL attributes are represented as "\N". A literal backslash character is represented as two consecutive backslashes ("\\"). A literal tab character is represented as a backslash and a tab. A literal newline character is represented as a backslash and a newline. When loading text data not generated by Postgres, you will need to convert backslash characters ("\") to double-backslashes ("\\") to ensure that they are loaded properly.

バックスラッシュには別の特別な意味があります。NULL 属性は "\N" と表現されます。リテラルのバックスラッシュは二つの続いた バックスラッシュ ("\\") と表現されます。リテラルのタブ文字は バックスラッシュとタブで表現されます。リテラルの改行はバック スラッシュと改行で表現されます。Postgres で 生成されていないテキストデータを読み込む時は、正常に読み込みが 出来るようにバックスラッシュ文字 ("\") を二つのバックスラッシュ ("\\") に変換する必要があります。

バイナリ形式

In the case of COPY BINARY, the first four bytes in the file will be the number of instances in the file. If this number is zero, the COPY BINARY command will read until end of file is encountered. Otherwise, it will stop reading when this number of instances has been read. Remaining data in the file will be ignored.

COPY BINARY の場合、ファイルの初めの 4 バイト はそのファイルの中のインスタンスの数を示しています。 この数がゼロの場合は、COPY BINARY はファイル の終了までデータを読み込みに行きます。数が指定されていると、 その数のインスタンスが読み込まれた時点で読み込みを中止します。 ファイル内に残っているデータは無視されます。

The format for each instance in the file is as follows. Note that this format must be followed exactly. Unsigned four-byte integer quantities are called uint32 in the table below.

ファイルの中のそれぞれのインスタンスの形式は以下のようになって います。この形式は全くこのままでなくては なりません。符号なしの 4 バイト整数の値は下記のテーブルで uint32 と呼ばれています。

Table 14-1. バイナリコピーファイルの内容

ファイルの先頭
uint32タプルの数
For each tuple
uint32タプルデータの総ての長さ
uint32(指定されている場合) oid
uint32null 属性の数
[uint32,...,uint32]0 から数え始めた属性の属性番号
-<tuple data>

バイナリデータの整頓

On Sun-3s, 2-byte attributes are aligned on two-byte boundaries, and all larger attributes are aligned on four-byte boundaries. Character attributes are aligned on single-byte boundaries. On most other machines, all attributes larger than 1 byte are aligned on four-byte boundaries. Note that variable length attributes are preceded by the attribute's length; arrays are simply contiguous streams of the array element type.

Sun-3 系では 2 バイトの属性は 2 バイトとして整頓され それ以上大きな属性は 4 バイトとして整頓されます。 文字属性は 1 バイトとして整頓されます。ほかの多くのマシン では、1 バイトより大きい属性は 4 バイトとして整頓されます。 変数の長さの属性には属性の長さが先頭に付きます。 配列は単に隣接する配列要素の型の並びです。

使用法

The following example copies a table to standard output, using a vertical bar ("|") as the field delimiter:

次の例ではフィールドのデリミタとして縦棒 ("|") を使って テーブルを標準出力に出します。

COPY country TO stdout USING DELIMITERS '|';
  

To copy data from a Unix file into a table "country":

Unix ファイルからデータをテーブル "country" にコピーします。

COPY country FROM '/usr1/proj/bray/sql/country_data';
  

Here is a sample of data suitable for copying into a table from stdin (so it has the termination sequence on the last line):

この例は stdin からテーブルにコピー する時の有効なデータを示しています。 (したがって、最終行に終結の指定があります。)

   AF      AFGHANISTAN
   AL      ALBANIA
   DZ      ALGERIA
   ...
   ZM      ZAMBIA
   ZW      ZIMBABWE
   \.
  

The same data, output in binary format on a Linux/i586 machine. The data is shown after filtering through the Unix utility od -c. The table has three fields; the first is char(2) and the second is text. All the rows have a null value in the third field. Notice how the char(2) field is padded with nulls to four bytes and the text field is preceded by its length:

Linux/i586 マシンでのバイナリ形式による同じデータの出力です。 データは Unix のユーティリティ od -c で フィルタをかけた後のものです。テーブルには 3 つのフィールドが あります。初めは char(2) で二番目は text です。全ての行は第三番目のフィールド に null 値を持っています。 char(2) が null で埋められて 4 バイトに そしてテキストのフィールドはその長さが前に来ていることに注意 して下さい。

   355  \0  \0  \0 027  \0  \0  \0 001  \0  \0  \0 002  \0  \0  \0
   006  \0  \0  \0   A   F  \0  \0 017  \0  \0  \0   A   F   G   H
     A   N   I   S   T   A   N 023  \0  \0  \0 001  \0  \0  \0 002
    \0  \0  \0 006  \0  \0  \0   A   L  \0  \0  \v  \0  \0  \0   A
     L   B   A   N   I   A 023  \0  \0  \0 001  \0  \0  \0 002  \0
    \0  \0 006  \0  \0  \0   D   Z  \0  \0  \v  \0  \0  \0   A   L
     G   E   R   I   A
   ...              \n  \0  \0  \0   Z   A   M   B   I   A 024  \0
    \0  \0 001  \0  \0  \0 002  \0  \0  \0 006  \0  \0  \0   Z   W
    \0  \0  \f  \0  \0  \0   Z   I   M   B   A   B   W   E
  

バグと主要点

COPY neither invokes rules nor acts on column defaults. It does invoke triggers, however.

COPY はカラムのデフォルトに対し、ルールも アクションも呼び出しません。しかし、トリガは呼び出されます。

COPY stops operation at the first error. This should not lead to problems in the event of a COPY FROM, but the target relation will, of course, be partially modified in a COPY TO. The VACUUM query should be used to clean up after a failed copy.

COPY は最初のエラーで操作を打ち切ります。 このことは COPY FROM イベントでは問題に なりませんが、COPY TO ではもちろん 目的リレーションが一部修正されます。 コピーが失敗した場合 VACUUM 問合せ で掃除してください。

Because the Postgres backend's current working directory is not usually the same as the user's working directory, the result of copying to a file "foo" (without additional path information) may yield unexpected results for the naive user. In this case, foo will wind up in $PGDATA/foo. In general, the full pathname as it would appear to the backend server machine should be used when specifying files to be copied.

Postgres バックエンドの現在の作業ディレクトリは通常 ユーザの作業ディレクトリと異なりますので、(追加した パスの情報がないい限り)ファイル "foo" への コピーは疑うことを知らないユーザに予期せぬ結果をもたらす ことがあります。この場合、 foo は 最終的に $PGDATA/foo になります。 一般的に、バックエンドサーバマシンに出て来るフルパス名を コピーするファイルの指定時に使用しなければなりません。

Files used as arguments to COPY must reside on or be accessible to the database server machine by being either on local disks or on a networked file system.

COPY に対する引数として使用される ファイルはローカルディスク上またはネットワークファイル システムとしてデータベースサーバマシンがアクセスできる 様になっているか、存在していなければなりません。

When a TCP/IP connection from one machine to another is used, and a target file is specified, the target file will be written on the machine where the backend is running rather than the user's machine.

あるマシンから他のマシンに TCP/IP 接続がされているとき、そして 目的ファイルが指定されているとき、その目的ファイルはユーザの マシンではなくバックエンドが走っているマシン上に書かれます。

互換性

SQL92

There is no COPY statement in SQL92.

SQL92 に COPY 文はありません。