PostgreSQL 8.0.0 文書
前のページ | 巻戻し |  | 早送り | 次のページ

# COPY

## 名前

COPY -- ファイルとテーブルの間でのデータのコピー

## 概要

    COPY tablename [ ( column [, ...] ) ]
        FROM { 'filename' | STDIN }
        [ [ WITH ]
              [ BINARY ]
              [ OIDS ]
              [ DELIMITER [ AS ] 'delimiter' ]
              [ NULL [ AS ] 'null string' ]
              [ CSV [ QUOTE [ AS ] 'quote' ]
                    [ ESCAPE [ AS ] 'escape' ]
                    [ FORCE NOT NULL column [, ...] ]

    COPY tablename [ ( column [, ...] ) ]
        TO { 'filename' | STDOUT }
        [ [ WITH ]
              [ BINARY ]
              [ OIDS ]
              [ DELIMITER [ AS ] 'delimiter' ]
              [ NULL [ AS ] 'null string' ]
              [ CSV [ QUOTE [ AS ] 'quote' ]
                    [ ESCAPE [ AS ] 'escape' ]
                    [ FORCE QUOTE column [, ...] ]

## 説明

`COPY`コマンドは、PostgreSQLのテーブルと標準のファイルシステムのファイル間でデータを移動します。 `COPY TO`コマンドはテーブルの内容をファイルにコピーします。 また、`COPY FROM`コマンドは、ファイルからテーブルへとデータをコピーします (この時、すでにテーブルにあるデータにコピーした内容を追加します）。

列のリストが指定されている場合、`COPY`は、指定された列のデータとファイルの間のコピーのみを行います。 列リストに入っていない列がテーブル内にある場合、`COPY FROM`は、それらの列にデフォルトの値を挿入します。

ファイル名付きの`COPY`コマンドは、PostgreSQLサーバに対して直接ファイルへの読み書きをするように伝えます。 そのファイルは必ずサーバからアクセスでき、またファイル名はサーバから見たように指定されなければなりません。 `STDIN`や`STDOUT`が指定された場合、データはクライアントとサーバ間を流れます。

## パラメータ

`tablename`

  既存のテーブルの名前です (スキーマ修飾も可)。

`column`

  省略可能な、コピーする列のリストです。 列のリストが指定されていない場合は、全ての列が使用されます。

`filename`

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

`STDIN`

  入力がクライアントアプリケーションからのものであることを指定します。

`STDOUT`

  出力がクライアントアプリケーションへのものであることを指定します。

`BINARY`

  全てのデータをテキストではなくバイナリ書式で読み書きするように設定します。 バイナリモードでは`DELIMITER`、`NULL`、あるいは`CSV`オプションを指定することはできません。

`OIDS`

  各行のOIDをコピーすることを指定します。 (OIDを持たないテーブルに`OIDS`を指定するとエラーが発生します。)

`delimiter`

  ファイルの各行（ライン）の列を区切る一文字を指定します。 デフォルトは、テキストモードではタブ文字、`CSV`モードではカンマです。

`null string`

  NULL値を表す文字列です。 デフォルトは、テキストモードでは`\N`（バックスラッシュ N）、`CSV`モードでは引用符の無い空値です。 しかし、NULL値と空文字列を区別する必要がない場合では、テキストモードであっても空文字列の方がよいかもしれません。

  > 注意: `COPY FROM`の場合、この文字列と一致するデータ要素はNULL値として格納されます。 従って、その時には、`COPY TO`実行時に使用した同じ文字列を使用しているかどうか確認してください。

`CSV`

  カンマ区切り変数(`CSV`)モードを選択します。

`quote`

  `CSV`における引用符用の文字列を指定します。 デフォルトは二重引用符です。

`escape`

  `CSV`モードにおけるデータ文字列内の`QUOTE`の前に現れる文字列を指定します。 デフォルトは`QUOTE`の値(通常は二重引用符)です。

`FORCE QUOTE`

  `CSV`モードの`COPY TO`において、指定された各列内にある全ての非`NULL`値を強制的に引用符で括ります。 `NULL`出力は引用符で括られません。

`FORCE NOT NULL`

  `CSV`モードの`COPY FROM`において、指定された各列を引用符で括られているものとみなし、`NULL`値でないかのように処理します。 `CSV`モードのデフォルトのNULL文字列(`''`)の場合、これにより値が喪失し、空文字列として入力されてしまいます。

## 注釈

`COPY`は通常のテーブルに対してのみ使用することができます。 ビューに対しては使用することができません。

`BINARY`キーワードは全てのデータをテキストではなく、バイナリ書式として書き込み/読み込みするように指定します。 通常のテキストモードより多少速く動作しますが、バイナリ書式のファイルを、異なるマシンアーキテクチャで使用することや他のバージョンのPostgreSQLで使用することはできません。

`COPY TO`の場合は値を読み込むテーブル上にSELECT権限が、`COPY FROM`の場合は、値を挿入するテーブル上にINSERT権限が必要です。

`COPY` コマンドで指名されたファイルはクライアントアプリケーションではなく、サーバが直接読み込み/書き込みを行います。 従って、それらはクライアントではなく、データベースサーバマシン上に存在するか、または、データベースサーバマシンからアクセス可能である必要があります。 また、クライアントではなく PostgreSQLユーザ（サーバを実行しているユーザID）でアクセスと読み書きができる必要もあります。 サーバがアクセス権限を持つ全てのファイルへの読み込み、書き込みを可能にするため、`COPY`でファイルを指名するのは、データベースのスーパーユーザのみに許可されています。

`COPY`はpsqlの`\copy`とは異なるものであることに注意してください。 `\copy`は`COPY FROM STDIN`や`COPY TO STDOUT`を呼び出し、psqlクライアントからアクセスできるファイルにデータの書き込み/読み込みを行います。 従って、`\copy`コマンドが使用された場合には、ファイルへのアクセスとアクセス権限は、サーバではなく、クライアント側に依存します。

`COPY`で指定されるファイル名を常に絶対パスで記述することをお勧めします。 `COPY TO`コマンドの場合ではサーバによって強制的にそうなりますが、`COPY FROM`コマンドでは相対パスによって指定されたファイルを読み込むことも可能となっています。 そのパスは、クライアントの作業ディレクトリではなく、サーバプロセスの作業ディレクトリ（データディレクトリの下のどこか）から相対的なディレクトリとして解釈されます。

`COPY FROM`は、宛先テーブル上で任意のトリガとチェック制約を呼び出しますが、ルールは呼び出しません。

`COPY`の入出力は`DateStyle`の影響を受けます。 デフォルト以外の`DateStyle`を設定している可能性があるPostgreSQLインストレーションとの移植を確実に行いたい場合は、`COPY`を使う前に`DateStyle`を`ISO`に設定しなければなりません。

`COPY`では、最初のエラーで処理を停止させます。 これは、`COPY TO`コマンドを実行している際には何ら問題はありませんが、`COPY FROM`の場合は、対象となるテーブルは始めの方の行を既に受け取っています。 これらの行は見えませんし、アクセスすることもできませんが、ディスク領域を占有します。 大きなコピー処理に何度も失敗した場合には、無視できないほど無駄なディスク領域が増えてしまいます。 この無駄な領域を取り戻すために、`VACUUM`を行う必要があります。

## ファイルの書式

### テキスト書式

`COPY`を `BINARY`または`CSV`オプションなしで使用した場合、読み書きされるデータはテーブルの1つの行を1行で表したテキストファイルとなります。 行内の列は区切り文字で区切られます。 属性値自体は、その属性のデータ型の出力関数で生成された、または、その入力関数で受け付け可能な文字列です。 指定されたNULL値文字列は、列がNULLの場所で使用されます。 入力ファイルの行にある列数が予期されていたよりも多かったり少なかったりすると、`COPY FROM` はエラーを発生します。 `OIDS`が指定された場合、OIDは、ユーザデータの列の前にある、1番目の列として読み書きされます。

データの終了は、バックスラッシュ-ピリオド(`\.`) だけから構成される 1 行で表されます。 ファイルの終了によって、完全に同じ機能を提供することができますので、データ終了マークは、ファイルから読み込む際には不要です。 しかし、3.0以前のクライアントプロトコルを使用したクライアントアプリケーションへ、または、クライアントアプリケーションからのデータコピーの場合だけは、終了マークを与えなければなりません。

バックスラッシュ文字 (`\`) は `COPY` 対象データ内で、行や列の区切り文字と判定されてしまう可能性があるデータ文字列を引用符付けすることに使用することができます。 特に、バックスラッシュ自体、改行、使用中の区切り文字といった文字が列値の一部となっている場合は 必ず バックスラッシュを前に付けなければなりません。

以下の特別なバックスラッシュから始まる文字の並びは、`COPY FROM` によって解釈されます。

文字の並び | 表現
--- | ---
`\b` | バックスペース (ASCII 8)
`\f` | 改ページ (ASCII 12)
`\n` | 改行 (ASCII 10)
`\r` | 復帰 (ASCII 13)
`\t` | タブ (ASCII 9)
`\v` | 垂直タブ (ASCII 11)
`\``数字` | バックスラッシュに続き、1 から 3 個の 8 進数で表す数字によって、そのコード番号が示す文字を指定します。

現在、`COPY TO`は8進数数字のバックスラッシュ並びを出力することはありませんが、上記一覧に存在しない制御文字には、これを使用します。

`N`またはピリオド(`.`)というデータ文字の前には、バックスラッシュを決して付けないでください。 この組み合わせは、それぞれ、NULL文字とデータ終了マークのデフォルトと間違って解釈されてしまいます。 上で示した以外のバックスラッシュ文字はそのまま解釈されます。

`COPY`データを生成するアプリケーションは、データ内の改行と復帰をそれぞれ、`\n`と`\r`に変換することを強く推奨されています。 現在のところ、バックスラッシュと復帰でデータ内の復帰を表すことも、バックスラッシュと改行でデータ内の改行を表すことも可能です。 しかし、こういった表現は今後のリリースにてデフォルトでは受け付けられなくなります。 また、`COPY`ファイルが異なるマシンを跨って転送される場合、破損のおそれがかなりあります。 (例えば、UnixからWindows、あるいはその逆。)

`COPY TO` は各行の行末にUnix形式の改行("`\n`")を出力します。 なお、Microsoft Windowsで稼働するサーバの場合は、サーバ上のファイルへの`COPY`の場合にのみ復帰/改行("`\r\n`")を出力します。 プラットフォームを跨る一貫性のために、サーバのプラットフォームに関わらず、`COPY TO STDOUT` は常に"`\n`"を送信します。 `COPY FROM`は、改行、復帰、復帰/改行を行末として扱うことができます。 データを意図するバックスラッシュの無い改行や復帰によるエラーという危険性を減らすために、`COPY FROM` は、入力行の行末が全て共通でない場合に警告を発します。

### CSV 書式

この書式は、スプレッドシートなど他の多くのプログラムで使用されるカンマ区切り値(`CSV`)ファイル書式をインポート、エキスポートするために使用されます。 PostgreSQLの標準テキストモードで使用されるエスケープの代わりに、一般的なCSVのエスケープ機構を生成、認識します。

各レコードの値は`DELIMITER`文字で区切られます。 区切り文字、`QUOTE`文字、`NULL`文字列、復帰、改行文字を含む値の場合、全体の値の前後に`QUOTE`文字が付与され、値の中で`QUOTE` 文字や`ESCAPE`文字が現れる所には、その前にエスケープ用の文字が付与されます。 また、`FORCE QUOTE`を使用して、特定列内の非`NULL`値を出力する時に強制的に引用符を付与することもできます。

`CSV`書式には`NULL`値と空文字列とを区別する標準的な方法はありません。 PostgreSQLのCOPYは、引用符によりこれを扱います。 `NULL`は`NULL`文字列として出力され、引用符で括られません。 一方、`NULL`文字列に一致するデータ値は引用符で括られます。 その結果、デフォルトの設定を使用すると、`NULL`は引用符で括られない空文字列として、一方、空文字列は二重引用符で括られて(`""`)出力されます。 データの読み込みの際も同様の規則に従います。 `FORCE NOT NULL`を使用して、特定列に対し`NULL`入力の比較を行なわないようにすることができます。

> 注意: CSVモードは、復帰文字や改行文字が埋め込まれ引用符で括られた値を含むCSVファイルを認識し、生成します 従って、このファイルは、テキストモードのように1つのテーブル行が1行で表されているとは限りません。 しかし、PostgreSQLは、CSVファイル自身の行末記法と一致しない行末文字が埋め込まれたフィールドがあると、`COPY`入力を拒絶します。 通常は、行末文字列が埋め込まれたデータをインポートする場合は、CSVよりもテキスト書式やバイナリ書式の方がより安全です。

> 注意: 奇妙な、時には間違ったCSVファイルを生成するプログラムは多くありますので、このファイル書式には標準よりも多くの慣習があります。 従って、この機構を使用してインポートすることができないファイルが存在するかもしれませんし、`COPY`が他のプログラムで処理できないファイルを生成するかもしれません。

### バイナリ形式

`COPY BINARY` で使用されるファイル書式は PostgreSQL 7.4 で変更されました。 新しい書式は、ファイルヘッダ、行データを含むゼロ以上のタプル、ファイルトレーラから構成されます。 ヘッダとデータは、ネットワークバイトオーダになりました。

#### ファイルヘッダ

ファイルヘッダは15バイトの固定フィールドとその後に続く可変長ヘッダ拡張領域から構成されます。 固定フィールドは以下の通りです。

署名

  `PGCOPY\n\377\r\n\0`という11バイトの並びです。 ヌルバイトがこの署名の必須部分となっていることに注意してください。 (この署名は、8ビットを通過させない転送によって破損してしまったファイルを容易に識別できるように設計されています。 この署名は改行コード変換やヌルバイトの削除、上位ビット落ち、パリティの変更などによって変わってしまいます。)

フラグフィールド

  このファイル書式の重要な部分となる32ビット整数のビットマスクです。 ビットは0(LSB) から 31 (MSB)までの番号が付いています。 このフィールドは、このファイル書式で使用される他の全ての整数フィールドと同様、(最大バイトが最初に現れる)ネットワークバイトオーダで保存されていることに注意してください。 ファイル書式における致命的な問題を表すために、16-31ビットは予約されています。 この範囲に想定外のビットが設定されていることが判明した場合、読み込み先は処理を中断しなければなりません。 後方互換書式問題を通知するために、0-15ビットは予約されています。 この範囲に想定外のビットが設定されていても、読み込み先は単に無視すべきです。 現在、1つのフラグビットのみが定義されており、残りは0でなければなりません。

  ビット16

    1ならば、OIDがデータに含まれています。 0ならば、含まれていません。

ヘッダ拡張領域長

  32ビット整数であり、それ自身を含まない、ヘッダの残り部分のバイト長です。 現在、これは0で、すぐ後に最初のタプルが続きます。 今後、ヘッダ内に追加データを格納できるような書式の変更があるかもしれません。 読み込み先では、どのように扱うか分からない、全てのヘッダ拡張データを単に飛ばさなければなりません。

ヘッダ拡張領域は、それ自身で認識することができる塊の並びを保持するために考えられています。 フラグフィールドは読み込み先に拡張領域の内容を知らせるものではありません。 ヘッダ拡張内容の特定の設計は後のリリースのために残してあります。

この設計は、後方互換性のあるヘッダの追加（ヘッダ拡張チャンクの追加や下位フラグビットの設定）と後方互換性のない変更（変更を知らせるための高位フラグビットの設定や必要に応じた拡張領域へのサポート情報追加）に有効です。

#### タプル

全てのタプルはタプル内のフィールド数を表す16ビット整数から始まります（現時点では、テーブル内の全てのタプルは同一のフィールド数を持つようになっていますが、常にそうであるとは限りません）。 その後に、タプル中のそれぞれのフィールドが、フィールドデータが何バイトあるかを表す32ビット長のワードの後に、繰り返し続きます。 (このバイト長ワードにはそれ自身は含まれず、0になることもあります。) 特殊な場合として、-1 はNULLフィールドを表す値です。 このNULLの場合、値用のバイトはありません。

フィールド間には整列用の詰めものやその他余計なデータはありません。

現在、`COPY BINARY` ファイル内の全てのデータ値は、バイナリ書式(書式コード1)であると仮定されています。 将来の拡張によって、列単位の書式コードを指定できるようなヘッダフィールドが追加されることを予想したものです。

実際のタプルデータに適切なバイナリ書式を決定するためには、PostgreSQLのソース、特に各列のデータ型用の`*send` 関数と `*recv`関数(通常配布物内の`src/backend/utils/adt`ディレクトリにあります)を調べなければなりません。

このファイルにOIDが含まれる場合、OIDフィールドがフィールド数ワードのすぐ後に続きます。 これは、フィールドカウントを持たない点を除いて、通常のフィールドです。 特に、これには長さワードがあり、このワードにより、苦労すること無く、4バイトのOIDも8バイトのOIDも扱うことができます。 また、これにより、それが望ましいと判れば、OIDをNULLとして表示することができます。

#### ファイルトレーラ

ファイルトレーラは、-1を含んだ、16ビット整数ワードで構成されます。 これはタプルのフィールドカウントワードを使用することによって容易に見分けることができます。

読み込み先は、フィールドカウントワードが-1でもなく、想定した列数でもなかった場合はエラーを報告しなければなりません。 これによりは、何らかの理由でデータとの同期が取れなくなったことを判定する特別な検査を行うことができます。

## 例

以下の例では、フィールド区切り文字として縦棒(`|`)を使用してテーブルをクライアントにコピーします。

    COPY country TO STDOUT WITH DELIMITER '|';

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

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

これは`STDIN`からテーブルにコピーするのに適したデータの例です。

    AF      AFGHANISTAN
    AL      ALBANIA
    DZ      ALGERIA
    ZM      ZAMBIA
    ZW      ZIMBABWE

各行の空白文字は実際にはタブ文字であることに注意してください。

以下は同一のデータをバイナリ書式で出力したものです。 データをUnixユーティリティ`od -c`を使ってフィルタしたものを示しています。 テーブルには3列あり、最初のデータ型は`char(2)`、2番目は`text`、3番目は`integer`です。 全ての行の3列目はNULL値です。

    0000000   P   G   C   O   P   Y  \n 377  \r  \n  \0  \0  \0  \0  \0  \0
    0000020  \0  \0  \0  \0 003  \0  \0  \0 002   A   F  \0  \0  \0 013   A
    0000040   F   G   H   A   N   I   S   T   A   N 377 377 377 377  \0 003
    0000060  \0  \0  \0 002   A   L  \0  \0  \0 007   A   L   B   A   N   I
    0000100   A 377 377 377 377  \0 003  \0  \0  \0 002   D   Z  \0  \0  \0
    0000120 007   A   L   G   E   R   I   A 377 377 377 377  \0 003  \0  \0
    0000140  \0 002   Z   M  \0  \0  \0 006   Z   A   M   B   I   A 377 377
    0000160 377 377  \0 003  \0  \0  \0 002   Z   W  \0  \0  \0  \b   Z   I
    0000200   M   B   A   B   W   E 377 377 377 377 377 377

## 互換性

標準SQLには`COPY`文はありません。

以下の構文は、PostgreSQLバージョン7.3以前で使用されていたもので、まだサポートされています。

    COPY [ BINARY ] tablename [ WITH OIDS ]
        FROM { 'filename' | STDIN }
        [ [USING] DELIMITERS 'delimiter' ]
        [ WITH NULL AS 'null string' ]

    COPY [ BINARY ] tablename [ WITH OIDS ]
        TO { 'filename' | STDOUT }
        [ [USING] DELIMITERS 'delimiter' ]
        [ WITH NULL AS 'null string' ]

前のページ | ホーム | 次のページ
COMMIT | 上に戻る | CREATE AGGREGATE