1. 管理者ガイド
  2. 管理ユーティリティ・コマンド・リファレンス
  3. import

import

java -jar KVHOME/lib/kvtool.jar import
-import-all | -table table_names | -namespace namespaces | -external
-store storeName
-helper-hosts helper_hosts
-config config_file_name
[-status status_file]
[-format BINARY | JSON | MONGODB_JSON]
[-username user]
[-security security-file-path]
[-verbose]

インポート・ユーティリティのコマンドライン・パラメータ

  • -import-allを指定すると、エクスポート・パッケージ全体がインポートされます。このオプションを指定する場合、-tableおよび-namespaceは指定できません。このパラメータは、Oracle NoSQL Databaseエクスポート・ユーティリティで作成されたパッケージからのインポートにのみ使用できます。

    Oracle NoSQL Database以外のソースから生成されたデータをロードするには、-externalオプションを使用します。

  • -tableは、インポートする1つ以上の表の名前です。複数の表をインポートするには、表名のカンマ区切りリストを指定します。このパラメータは、Oracle NoSQL Databaseエクスポート・ユーティリティで作成されたパッケージから1つ以上の特定の表をインポートする場合にのみ使用できます。

    Oracle NoSQL Database以外のソースから生成されたデータをロードするには、-externalオプションを使用します。

    このパラメータを指定する場合、-import-allおよび-namespaceは指定できません。

    ノート:

    子表をインポートする場合、子表の名前はその親表全体で修飾されている必要があります。たとえば、親表がchild1でさらにその親表がparent1である表grandchild1をインポートするには、フルパスparent1.child1.grandchild1を指定する必要があります。

    ノート:

    子表をインポートする場合、その子表へのパスに含まれるすべての親表が、インポートに含まれるかまたはターゲットのOracle NoSQL Databaseストアにすでに存在している必要があります。

    ノート:

    ネームスペースを使用している場合は、-tableフラグで表の完全修飾名を指定する必要があります。たとえば、namespace1:userProfilesなどです。

  • -namespaceは、インポートする1つ以上のネームスペースの名前です。複数のネームスペースをインポートするには、ネームスペースのカンマ区切りリストを指定します。このパラメータは、Oracle NoSQL Databaseエクスポート・ユーティリティで作成されたパッケージから、1つ以上のネームスペースに存在する表をインポートする場合にのみ使用できます。Oracle NoSQL Database以外のソースから生成されたデータをロードするには、-externalオプションを使用します。

    このパラメータを指定する場合、-import-allおよび-tableは指定できません。

  • -externalは、インポートするデータがOracle NoSQL Database以外のソースによって生成されていることを指定します。つまり、このフラグは、インポート・ユーティリティによって読み取られるディレクトリ構造がエクスポート・パッケージ形式ではないことを示します。

    このパラメータを指定する場合、-import-all、-tableおよび-namespaceは指定できません。これらは構成ファイルで指定する必要があります。

  • -storeは、データをインポートするOracle NoSQL Databaseストアの名前です。インポート・ユーティリティは、このOracle NoSQL Databaseストア内の実行中のノードに接続できる必要があります。

    ノート:

    このパラメータは必須で、大/小文字が区別されます。
  • -helper-hostsは、hostname:port形式のホスト名とレジストリ・ポートのペアのリストです。このリストでは、各項目をカンマで区切って指定します。少なくとも1つのヘルパー・ホストを指定する必要があります。
  • -configは、使用する構成ファイルの名前です。このパラメータは必須です。このユーティリティの構成ファイルの詳細は、インポート・ユーティリティの構成ファイルを参照してください。
  • -statusはオプション・パラメータで、エクスポートのcheckpointOutput構成パラメータと同じです。このパラメータは、インポート・チェックポイント機能によってチェックポイント情報が格納されるディレクトリを指定します。ディレクトリは、完全修飾ディレクトリ名または単一のディレクトリ名を指定できます。完全修飾されていない場合、インポート・ユーティリティが実行されている現在の作業ディレクトリとの相対とみなされます。インポートが完了する前に失敗した場合、後続のインポートの再起動は、ステータス・ファイルのチェックポイント情報を使用することで、中断した場所から開始できます。

    このパラメータを指定しなかった場合、障害が発生すると、後続のインポートの再起動が最初からやり直しになり、すでにインポートされているファイルもインポートされます。このシナリオにおけるインポートの動作の説明は、後述のoverwrite構成パラメータを参照してください。

  • -usernameは、データのインポートに使用するユーザーの名前です。ストアが認証を必要とするように構成されている場合、このパラメータは必須です。

    ノート:

    このパラメータでは大/小文字が区別されます。
  • -securityは、クライアント・セキュリティ構成ファイルです。ストアが認証を必要とするように構成されている場合、このパラメータは必須です。セキュリティ情報を含むファイルへの完全修飾パスを指定するか、ファイル名を指定できます。完全修飾されていない場合、インポート・ユーティリティは、現在の作業ディレクトリでセキュリティ・ファイルを検索します。このファイルに含まれるパラメータの詳細は、Javaダイレクト・ドライバ開発者ガイドのSSLの構成を参照してください。次に例を示します。
    oracle.kv.auth.username=clientUID1
oracle.kv.auth.pwdfile.file=/home/nosql/login.pwd
oracle.kv.transport=ssl
oracle.kv.ssl.trustStore=/home/nosql/client.trust

    Kerberosを使用している場合、このファイルは次のようになります。

    oracle.kv.auth.kerberos.keytab=kerberos/mykeytab
oracle.kv.auth.username=krbuser@EXAMPLE.COM
oracle.kv.auth.external.mechanism=kerberos
oracle.kv.auth.kerberos.services=node01:oraclenosql/node01.example.com@EXAMPLE.COM
oracle.kv.auth.kerberos.mutualAuth=false

    ノート:

    このパラメータでは大/小文字が区別されます。
  • -verboseを指定すると、トレース、デバッグおよび進捗のメッセージが標準出力に出力されます。このオプションは、特に表またはデータセットが大規模な場合に、インポート操作の進捗状況を追跡するために役立ちます。

ノート:

インポート/エクスポート・ユーティリティの詳細は、インポートおよびエクスポート・ユーティリティの使用を参照してください。

インポート・ユーティリティの構成ファイル

データは、BINARY、JSONおよびMONGODB JSONの3つの形式でインポートできます。インポートするデータの形式に応じて、特定の構成オプションが関連します。たとえば、JSONデータのインポート時にcharset構成オプションを使用して、インポートするJSONデータの文字セットを記述できます。次のリストでは書式設定関連の構成オプションを太字で示し、関連する箇条書きリストで詳細を説明しています。 

{
    "configFileVersion": <version>,
    "abortOnError": [false | true],
    "errorOutput": <error-dir>,
    "errorFileSizeMB": <error-file-chunk-size-mb>,
    "errorFileCount": <error-file-count>,
    "path": <dir-or-file>,
    "namespace": <namespace>,
    "tableName": <table-name>,
    "ignoreFields": [<field1>, <field2>, ...],
    "renameFields": {
        <old-name>:<new-name>,
        ...
    }
    "charset": <charset-name>,
    "ddlSchemaFile": <file>,
    "continueOnDdlError": <false | true>,
    "overwrite": <false | true>,
    "ttlRelativeDate": <date-to-use in UTC>,
    "dateTimeToLong": <true | false>
            }
  • configFileVersion - オプション。このフィールドは、構成ファイルのバージョンを表します。この構成オプションでサポートされている値は、1のみです。
  • abortOnError - オプション。trueの場合、最初にエラーが発生した時点でユーティリティは終了します。ターゲットのOracle NoSQL Databaseデータ・ストアは実行中状態になり、エラーの前にインポートされたデータがすべて含まれます。falseの場合、インポートは続行され、エラーは構成済のerrorOutputディレクトリにあるファイルに記録されます。デフォルトはtrueです。
  • errorOutput - オプションで、大/小文字が区別されます。ユーティリティがエラー・ログ・ファイルを作成するディレクトリです。このファイルには、エラーに関連するOracle NoSQL Databaseのデータとともにエラー・メッセージが含まれます。インポート中に拒否されたレコードはすべて、このディレクトリのログ・ファイルに格納されます。完全修飾ディレクトリまたはディレクトリ名を使用できます。ディレクトリ名を使用する場合、インポート/エクスポート・ユーティリティが実行されている現在の作業ディレクトリに対して相対的な名前を使用します。指定しない場合、<path>/errorsにデフォルト設定されます。

    サブディレクトリは、それぞれが一連のログ・ファイルを保持し、インポートされる表ごとに作成されます。たとえば、table1、table2およびtable3をインポートし、errorOutputディレクトリを/users/oracle/nosqlに設定してある場合、インポートによって次のファイル・セットが作成されます。 

    /users/oracle/nosql/table1.err*
/users/oracle/nosql/table2.err*
/users/oracle/nosql/table3.err*

    エラー・ファイルはerrorFileSize (以下を参照)のサイズで作成され、0から番号が付けられます。

  • errorFileSize - オプション。単一のエラー・ファイルの最大サイズ(MB)。この制限に達すると、ユーティリティによって別のエラー・ファイルが作成されます。デフォルトは500mbです。
  • errorFileCount - オプション。インポートされる表ごとに作成されるエラー・ファイルの最大数。この制限に達すると、ユーティリティが終了し、インポートも終了します。デフォルトは5です。

    たとえば、errorFileCountが2で、3つの表をインポートする場合、作成されるエラー・ファイルの最大数は6です。表ごとに2つのエラー・ファイルが作成されます。

  • path - 必須で、大/小文字が区別されます。これは、インポートの唯一の必須パラメータです。エクスポートによって作成された構造をインポートする場合、このパスは、エクスポート・パッケージのディレクトリ構造のルートへのディレクトリ・パスにする必要があります。完全修飾ディレクトリまたはディレクトリ名を使用できます。ディレクトリ名を使用する場合、インポート/エクスポート・ユーティリティが実行されている現在の作業ディレクトリに対して相対的な名前を使用します。

    また、このパスで、インポートする単一のファイルを指すことも、単一の表にインポートするJSONテキスト・ファイルのディレクトリを指すこともできます。ファイルを使用する場合、ディレクトリはフラットである必要があります。インポート・ユーティリティは、エクスポートで作成されていないディレクトリ構造を再帰的に下位にたどることはしません。

  • namespace - オプションで、-externalフラグとともに使用します。指定した場合、インポートされるデータがOracle NoSQL Databaseに書き込まれるときに、指定したネームスペースでインポートされる表が修飾されます。

    ノート:

    -externalフラグが使用されていない場合、-externalフラグを必要とする構成オプションは警告なしで無視されます。
  • tableName - オプションで、-externalフラグとともに使用します。インポートされたデータを書き込むOracle NoSQL Databaseのターゲット表の名前です。指定しなかった場合、インポート・ツールにより、pathで指定したディレクトリのリーフ・レベルの名前が表の名前として使用されます。

    たとえば、JSONをロードしていて、pathを/usr/local/mydata/profile_dataに設定してある場合、インポート中に使用される表の名前はprofile_dataになります。

  • ignoreFields - オプションで、-externalフラグとともに使用します。Oracle NoSQL Databaseにデータをインポートするときに無視される属性を示すJSON属性の配列です。インポートされるドキュメントにこれらの属性が存在する場合、それらは無視されます。

    ノート:

    最上位レベルのドキュメント属性のみ指定できます。
  • renameFields - オプションで、-externalフラグとともに使用します。名前と値のペアのカンマ区切りリストです。old-nameはJSON属性で、Oracle NoSQL Databaseへの書込み時にnew-nameで指定した値に変更されます。

    ノート:

    最上位レベルのドキュメント属性のみ指定できます。
  • charset - オプションで、-externalフラグとともに使用します。US-ASCII、ISO-8859-1、UTF-8、UTF-16、UTF-16BE、UTF-16LEの形式を指定できます。デフォルトはUTF-8です。
  • ddlSchemaFile - オプション。指定する場合、このファイルには、Oracle NoSQL Databaseにデータをインポートする前に実行されるDDLを含めます。有効なDDL文(Javaダイレクト・ドライバ開発者ガイドの表の定義を参照)を指定できます。インポート/エクスポート・ツールでは、ddlSchemaFile内で1行に1つのDDL文のみをサポートします。

    ノート:

    ddlSchemaFileを使用しない場合、インポート・ユーティリティによってid列のある表が作成され、インポート中にidの値が自動生成されます。インポート中のJSONデータに最上位レベルのid属性がすでに含まれている場合、エラーが発生します。このエラーを回避するには、ddlSchemaFileを使用して、インポート用に作成される表を指定する必要があります。
  • continueOnDdlError - オプション。trueの場合、インポートはddlSchemaFileで指定したDDLの発行時に発生したエラーをすべて無視(して記録)します。デフォルトはfalseです。
  • overwrite - オプション。trueの場合、インポート/エクスポート・ユーティリティによって、インポート時にOracle NoSQL Databaseにすでに存在するレコードが自動的に上書きされます。デフォルトはfalseです。
  • ttlRelativeDate - オプションで、BINARY形式でのみ使用できます。YYYY-MM-DD HH:MM:SS形式のUTC日付で、Oracle NoSQL Databaseにインポートする際のレコードのTTL有効期限を調整するために使用できます。エクスポートされたデータのレコードが、TTL有効期限切れがすでに発生しているために期限切れになっている場合、ttlRelativeDateを、エクスポートされたデータのレコードの有効期限よりも前の日付に設定できます。このパラメータのデフォルトは、インポート操作の現在の時間です。

    たとえば、特定の表のTTL値で、1-Jan-2019から7日後にレコードが期限切れになる(データが8-Jan-2019に失効する)ことが示されているとします。この表を5-Jan-2019にエクスポートしました。7-Jan-2019に表の問題が発生し、エクスポート・パッケージからデータをインポートすることにしました。今日は7-Jan-2019 (現在の日付)であるため、エクスポート・パッケージ内のレコードは1日(有効期限日付からttlRelativedateのデフォルト値(現在の日付)を差し引いた日数)で期限切れになります。ttlRelativeDateパラメータを使用し、ttlRelativeDateに対して以前の日付を選択することで、これらのレコードの存続期間を延長できます。この例で、レコードの有効期限を変更し、これらのレコードの存続期間を7日間延長するには、ttlRelativeDateに1-Jan-2019を指定します。インポートによってすべてのレコードの有効期限が7日(8-Jan-2019から1-Jan-2019を差し引いた日数)に変更されます。

  • dateTimeToLong - オプションで、MONGODB_JSON形式でのみ使用できます。trueの場合、インポート操作中にMongoDBエクスポートからの日付値がlong値(Epoch以降のティック数)に変換されます。デフォルトはfalseで、この場合、すべての日付値がISO-8601文字列書式として処理されます。

MONGODB_JSON形式 - 表の自動作成

インポート・ユーティリティを実行してMongoDBエクスポート・パッケージからデータをロードすると、表が自動的に作成されます。ddlSchemaFileが使用されておらず、インポートの形式がMONGODB_JSONである場合、インポートによって次のDDLが自動的に発行され、インポートの表構造が作成されます。 

create table if not exists tableName(
    id STRING,
    document JSON,
    primary key(id)
)

インポート時に、MongoDBドキュメントの_id属性を抽出し、Oracle NoSQL Databaseのレコードのid属性に_id属性の値を移入することによって、表の各レコードが移入されます。

インポートの進捗の監視

大規模なデータセットで長時間実行されるインポート操作では、実行中のインポート・ユーティリティの進捗を追跡することが有用です。-verboseフラグを使用し、コマンドの標準出力をファイルにリダイレクトするか、またはUnixコマンドtail -fにパイプして、インポートの進捗を追跡できます。

インポート・チェックポイントの仕組み

インポートのチェックポイントの粒度は、ファイル・レベルです。多数のファイルを含むディレクトリを指定でき、それぞれのファイルにOracle NoSQL Databaseにある1つ以上の表にインポートされるデータの断片が含まれます(エクスポートで書き込まれたエクスポート・パッケージからのインポート時には、複数の表のインポートのみがサポートされることに注意してください)。インポート操作で各ファイルのロードが完了すると、その進捗状況に応じてチェックポイント・ファイルが更新されます。インポート操作が失敗して再実行されると、インポート/エクスポート・ユーティリティはチェックポイント・ファイルを参照し、Oracle NoSQL Databaseにすでにロードされているファイルは無視して、操作が中断した場所を効果的に取得します。そのため、大きいファイルを小さく管理しやすいデータ・チャンクに分割し、チェックポイントの粒度を小さくして、障害発生後の再起動でインポート操作がすばやく実行されるようにすることをお薦めします。

インポート時のデータ破損の検出

Oracle NoSQL Databaseからエクスポートされたバイナリ形式データをインポートする場合、インポート・ユーティリティによって各レコードのチェックサムが計算され、そのチェックサムが、インポートされるファイルのレコードとともに格納されているチェックサムと照合されます。チェックサムが一致しない場合、レコードは拒否され、errorOutputファイルに書き込まれます。

インポート終了コード

名前 コード 説明
EXIT_OK 0 エラーは見つかりませんでした。
EXIT_USAGE 100 インポート・コマンドの使用方法が不正です。
EXIT_NOCONNECT 103 指定されたストア名およびヘルパー・ホストを使用してソース・ストアに接続できませんでした。
EXIT_UNEXPECTED 104 ユーティリティで予期しないエラーが発生しました。
EXIT_NOREAD 106 インポート・ユーティリティに、エクスポート・パッケージの読取り権限がありません。
EXIT_SECURITY_ERROR 110 セキュリティ・ファイルのロード中にエラーが発生しました。
EXIT_NOEXPPACKAGE 112 インポートに必要なエクスポート・パッケージが、指定された場所にありません。

有効なJSONファイル

JSONファイルをインポートするときには、JSONファイルが次の基準を満たしていることを確認します。

  • インポートするJSONファイルに、1つ以上のJSONレコードが含まれている必要があります。
  • JSONレコードは、中カッコのペアで囲まれたキー/値のペアのコレクションである必要があります。
  • JSONレコードは、1行で指定することも、インデントや改行を使用して複数行で書式設定することもできます。

    次に例を示します。

    {"id" : 1, "lastName" : "Anderson", "firstName" : "Nick", "phones" : {"home" : "800-555-9201", "work" : "877-123-8811"}}

    または

    {
    "id" : 1,
    "lastName" : "Anderson",
    "firstName" : "Nick",
    "phone" : {
        "home" : "800-555-9201",
        "work" : "877-123-8811"
    }
}

  • ファイル内の複数のJSONレコードは、別々のJSONドキュメントで指定することも、JSON配列で指定することもできます。

    別々のJSONドキュメント:

    $ cat users.json
{"id" : 1, "lastName" : "Anderson", "firstName" : "Nick", "age" : 30}
{"id" : 2, "lastName" : "John", "firstName" : "Anderson", "age" : 31}
{"id" : 3, "lastName" : "Peter", "firstName" : "smith", "age" : 32}

    JSON配列:

    $ cat users.json
[
    {"id" : 1, "lastName" : "Anderson", "firstName" : "Nick", "age" : 30},
    {"id" : 2, "lastName" : "John", "firstName" : "Anderson", "age" : 30},
    {"id" : 3, "lastName" : "Peter", "firstName" : "smith", "age" : 30}
]

importコマンドの使用例

例1: KVSTOREからバイナリ形式でエクスポートされたデータを別のKVSTOREにインポートする方法

Oracle NoSQL Databaseデータ・ストアの内容全体を、別のOracle NoSQL Databaseデータ・ストアにインポートできます。

  1. Oracle NoSQL Databaseデータ・ストアkvstore1の内容全体をエクスポートし、エクスポート・パッケージを/users/oracle/kvstore_exportディレクトリに配置します。
    java -jar lib/kvtool.jar export -export-all \
-store kvstore1 -helper-hosts localhost:5000 \
-config export_config
    export_configファイルは現在の作業ディレクトリ内にあります。ファイルの内容は次のとおりです。
    { 
   "path": "/users/oracle/kvstore_export"
}

    データおよびスキーマ定義用のディレクトリは、kvstore_exportディレクトリに作成されます。

  2. 前述の例で作成したエクスポート・パッケージのすべてのデータを、別のOracle NoSQL Databaseデータ・ストアkvstore2にインポートします。エクスポート・ユーティリティによって作成されたエクスポート・パッケージを使用しているため、表が事前に存在しない場合は、エクスポートによって生成されたスキーマ・メタデータからすべての表が自動的に作成されます。
    java -jar lib/kvtool.jar import -import-all \
-store kvstore2 -helper-hosts localhost:5000 \
-config import_config
    import_configファイルは現在の作業ディレクトリ内にあります。ファイルの内容は次のとおりです。
    { 
   "path": "/users/oracle/kvstore_export"
}

    import-allを指定すると、エクスポート・パッケージ全体がインポートされます。

例2: JSON形式のKVSTORE表からエクスポートされたデータを別のKVSTOREにインポートする方法

Oracle NoSQL Databaseデータ・ストアの1つ以上の表を、別のOracle NoSQL Databaseデータ・ストアにインポートできます。

  1. kvstore1の表usersから内容をエクスポートし、エクスポート・パッケージを/users/oracle/kvstore_exportディレクトリに配置します。形式はJSONとして指定されます。
    java -jar lib/kvtool.jar export -table users \
-store kvstore1 -helper-hosts localhost:5000 \
-config export_config -format JSON
    export_configファイルは現在の作業ディレクトリ内にあります。ファイルの内容は次のとおりです。
    { 
   "path": "/users/oracle/kvstore_export"
}

    データおよびスキーマ定義用のディレクトリは、kvstore_exportディレクトリに作成されます。データ・ディレクトリ内では、すべての表にディレクトリがあり、対応するjsonファイルが表ディレクトリ内に格納されます。

  2. 前述の例で作成したエクスポート・パッケージのusersデータを、別のOracle NoSQL Databaseデータ・ストアkvstore2にインポートします。チェックポイントを使用すると、インポートが失敗した場合に、停止または中断した場所からインポートを再開できます。パラメータ-tableは、インポートする1つ以上の表の名前です。複数の表をインポートするには、表名のカンマ区切りリストを指定します。形式はJSONとして指定されます。
    java -jar lib/kvtool.jar import -store kvstore2 \
-table users -helper-hosts localhost:5000 
-config import_config -format JSON \
-status /users/oracle/checkpoint_dir
    import_configファイルは現在の作業ディレクトリ内にあります。ファイルの内容は次のとおりです。
    { 
   "path": "/users/oracle/kvstore_export"
}

例3: MongoDBエクスポートからKVSTOREにデータをインポートする方法

MongoDBのstrictエクスポートからのデータを含むデータ・ファイルをインポートできます。データがKVSTOREにインポートされる間、フィールドを無視するように指定できます。パラメータ-externalは、インポートするデータがOracle NoSQL Database以外のソースによって生成されていることを指定します。つまり、このフラグは、インポート・ユーティリティによって読み取られるディレクトリ構造がエクスポート・パッケージ形式ではないことを示します。形式はMONGODB_JSONとして指定されます。
java -jar lib/kvtool.jar import -external \
-store kvstore -helper-hosts localhost:5000 \
-config import_config -format MONGODB_JSON
import_configファイルは現在の作業ディレクトリ内にあります。ファイルの内容は次のとおりです。次の構成ファイルに示すように、このフィールドを無視するように選択したため、social_security_numberフィールドはKVSTOREに移入されません。インポートのすべてのエラーおよび進捗情報を/users/oracle/mongo_db_import_logsに格納します。 
{ 
   "path": "/users/oracle/my_mongodb_data",  
   "ignoreFields": "social_security_number",
   "errorOutput": "/users/oracle/mongo_db_import_logs" 
}