DBMS_CLOUD_PIPELINEパッケージ

DBMS_CLOUD_PIPELINEパッケージを使用すると、クラウドでデータをロードおよびエクスポートするためのデータ・パイプラインを作成できます。このパッケージは、データベースへのオブジェクト・ストア内のファイルの継続的な増分データ・ロードをサポートします。DBMS_CLOUD_PIPELINEでは、タイムスタンプ列に基づく表データまたはデータベースからの問合せ結果のオブジェクト・ストアへの継続的な増分エクスポートもサポートされます。

関連項目

前提条件

開発者は、Oracle Public Cloud、マルチクラウドまたはExadata Cloud@CustomerにデプロイされたAutonomous DatabaseでDBMS_CLOUDプロシージャを使用できます。

デプロイメントの選択肢に応じて、Amazon S3、Azure Blob StorageおよびGoogle Cloud Storageサービス・プロバイダでDBMS_CLOUDプロシージャを使用するには、次の前提条件を満たす必要があります。

アウトバウンド接続は、次に説明するようにフリート管理者によってNATゲートウェイを使用して構成されている必要があります:
  • Oracle Cloud InfrastructureドキュメンテーションのNAT Gatewayの作成の説明に従って、Autonomous Databaseリソースが存在するVirtual Cloud Network (VCN)でNATゲートウェイを作成します。
  • NATゲートウェイを作成したら、Autonomous Databaseリソースが存在する各サブネット(VCN内)にルート・ルールおよびエグレス・セキュリティ・ルールを追加して、これらのリソースがゲートウェイを使用してAzure ADインスタンスから公開キーを取得できるようにします:
    1. サブネットの「サブネットの詳細」ページに移動します。
    2. 「Subnet Information」タブで、サブネットの「Route Table」の名前をクリックして、その「Route Table Details」ページを表示します。
    3. 既存のルート・ルールの表で、次の特性を持つルールがすでに存在します:
      • 宛先: 0.0.0.0/0
      • ターゲット・タイプ: NAT Gateway
      • ターゲット: VCN内に作成したNATゲートウェイの名前

      このようなルールが存在しない場合は、「ルート・ルールの追加」をクリックし、これらの特性を持つルート・ルールを追加します。

    4. サブネットの「サブネットの詳細」ページに戻ります。
    5. サブネットの「セキュリティ・リスト」表で、サブネットのセキュリティ・リストの名前をクリックして、その「セキュリティ・リストの詳細」ページを表示します。
    6. サイド・メニューの「リソース」で、「エグレス・ルール」をクリックします。
    7. 既存のエグレス・ルールの表で、次の特性を持つルールがすでに存在します:
      • 宛先タイプ: CIDR
      • 宛先: 0.0.0.0/0
      • IPプロトコル: TCP
      • ソース・ポート範囲: 443
      • 宛先ポート範囲: すべて

      そのようなルールが存在しない場合は、「エグレス・ルールの追加」をクリックし、これらの特性を持つエグレス・ルールを追加します。

環境のHTTPプロキシ設定では、データベースがクラウド・サービス・プロバイダにアクセスできるようにする必要があります。

これらの設定は、Exadata Cloud@Customerインフラストラクチャの作成時にフリート管理者が定義します(コンソールを使用したExadata Database Service on Cloud@Customerのプロビジョニングを参照)。

ノート:

HTTPプロキシを含むネットワーク構成は、Exadataインフラストラクチャが「アクティブ化が必要」状態になるまで編集できます。いったんアクティブ化すると、それらの設定は編集できません。

すでにプロビジョニングされているExadataインフラストラクチャのHTTPプロキシを設定するには、My Oracle Supportでサービス・リクエスト(SR)が必要です。詳細は、My Oracle Supportでのサービス・リクエストの作成を参照してください。

DBMS_CLOUD_PIPELINEサブプログラムの概要

この表は、DBMS_CLOUD_PIPELINEパッケージに含まれるサブプログラムの概要を示しています。

サブプログラム 説明

CREATE_PIPELINEプロシージャ

新規のデータ・パイプラインを作成します。

DROP_PIPELINEプロシージャ

既存のデータ・パイプラインを削除します。

RESET_PIPELINEプロシージャ

データ・パイプラインのトラッキング状態をリセットします。パイプラインのリセットを使用して、データ・ロードまたはエクスポートの初期状態からパイプラインを再起動します。オプションで、パイプラインをリセットすると、パイプラインのタイプに応じて、データベースまたはオブジェクト・ストア内のデータをパージできます。

RUN_PIPELINE_ONCEプロシージャ

スケジュールされたジョブではなく、現在のフォアグラウンド・セッションでパイプラインのオンデマンド実行を実行します。

SET_ATTRIBUTEプロシージャ

パイプライン属性を設定します。オーバーロードされた2つのプロシージャがあります。1つは1つの属性を設定し、もう1つは属性名と値のペアのJSONドキュメントを使用して複数の属性を設定するプロシージャです。

START_PIPELINEプロシージャ

データ・パイプラインを開始します。パイプラインが開始されると、パイプライン属性はパイプライン属性で構成された「間隔」に従って、スケジュール済ジョブでパイプライン操作が継続的に実行されます。

STOP_PIPELINEプロシージャ

データ・パイプラインを停止します。パイプラインが停止すると、パイプラインに対して将来のジョブはスケジュールされません。

CREATE_PIPELINEプロシージャ

このプロシージャは、新しいデータ・パイプラインを作成します。

構文

DBMS_CLOUD_PIPELINE.CREATE_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      pipeline_type        IN   VARCHAR2,
      attributes           IN   CLOB        DEFAULT NULL,
      description          IN   VARCHAR2    DEFAULT NULL
);

Parameters

パラメータ 説明

pipeline_name

パイプラインの名前を指定します。パイプライン名は、Oracle SQL識別子のネーミング・ルールに従う必要があります。詳細は、Oracle Database Database PL/SQL言語リファレンスの識別子またはOracle Database 23ai Database PL/SQL言語リファレンスを参照してください。

このパラメータは必須です。

pipeline_type

パイプライン・タイプを指定します。

有効な値: LOAD、EXPORT

このパラメータは必須です。

attributes

JSON形式のパイプライン属性。

デフォルト値: NULL

詳細は、DBMS_CLOUD_PIPELINE属性を参照してください。

description

パイプラインの説明。

デフォルト値: NULL

DROP_PIPELINEプロシージャ

このプロシージャは、既存のデータ・パイプラインを削除します。パイプラインが開始されている場合は、パイプラインを削除する前に停止する必要があります。

構文

DBMS_CLOUD_PIPELINE.DROP_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       force                IN   BOOLEAN DEFAULT FALSE
 );

Parameters

パラメータ 説明

pipeline_name

パイプライン名を指定します。

このパラメータは必須です。

force

パイプラインが開始状態であっても、強制的にドロップします。

有効な値: TRUE、FALSE

デフォルト値: FALSE

使用上のノート

  • 開始状態のパイプラインを削除するには、forceパラメータをTRUEに設定します。

RESET_PIPELINEプロシージャ

データ・パイプラインのトラッキング状態をリセットします。パイプラインのリセットを使用して、データ・ロードまたはエクスポートの初期状態からパイプラインを再起動します。オプションで、パイプラインをリセットすると、パイプラインのタイプに応じて、データベースまたはオブジェクト・ストア内のデータをパージできます。データ・パイプラインをリセットするには、停止状態である必要があります。

構文

DBMS_CLOUD_PIPELINE.RESET_PIPELINE(
       pipeline_name        IN   VARCHAR2,
       purge_data           IN   BOOLEAN DEFAULT FALSE
 );

Parameters

パラメータ 説明

pipeline_name

パイプラインの名前を指定します。

このパラメータは必須です。

purge_data

パージ・データは、ロード・パイプラインまたはエクスポート・パイプラインに適用されます。

  • ロード・パイプラインの場合、TRUEの場合、データベース表のデータを切り捨てます。

  • エクスポート・パイプラインの場合、TRUEの場合、オブジェクト・ストアの場所にあるファイルを削除します。

有効な値: TRUE、FALSE

デフォルト値: FALSE

使用上のノート

  • データ・パイプラインをリセットするには、停止状態である必要があります。詳細は、STOP_PIPELINEプロシージャを参照してください。

  • ロード・パイプラインの場合、パイプラインをリセットすると、パイプラインによってロードされているファイルのレコードがクリアされます。ロード・パイプラインのリセット後にSTART_PIPELINEまたはRUN_PIPELINE_ONCEをコールすると、パイプラインはデータ・ロードを繰り返し、オブジェクト・ストアの場所に存在するすべてのファイルを含めます。

    purge_dataがTRUEに設定されている場合、DBMS_CLOUD_PIPELINE.RESET_PIPELINEは次のことを行います。

    • table_name属性で指定したパイプラインのデータベース表内のデータを切り捨てます。

    • パイプラインのステータス表、およびパイプラインの不正なファイル表とエラー表(存在する場合)を削除します。

  • エクスポート・パイプラインの場合、パイプラインをリセットすると、データベース表の最後の追跡データがクリアされます。エクスポート・パイプラインのリセット後にSTART_PIPELINEまたはRUN_PIPELINE_ONCEをコールすると、パイプラインは表または問合せからのデータのエクスポートを繰り返します。

    purge_dataをTRUEに設定すると、DBMS_CLOUD_PIPELINE.RESET_PIPELINEは、location属性で指定されたオブジェクト・ストアの場所にある既存のファイルを削除します。

RUN_PIPELINE_ONCEプロシージャ

このプロシージャは、スケジュール済ジョブで実行されるのではなく、現在のフォアグラウンド・セッションでパイプラインのオンデマンド実行を実行します。DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCEを使用して、パイプラインを連続ジョブとして開始する前にパイプラインをテストします。

構文

DBMS_CLOUD_PIPELINE.RUN_PIPELINE_ONCE(
       pipeline_name  IN  VARCHAR2
);

Parameters

パラメータ 説明

pipeline_name

実行するパイプラインの名前を指定します。

このパラメータは必須です。

使用上のノート

  • パイプラインのテスト実行を実行した後、DBMS_CLOUD_PIPELINE.RESET_PIPELINEを使用してパイプライン状態をリセットできます。これにより、スケジュール済ジョブでパイプラインを開始する前にパイプラインの状態をリセットできます。

  • パイプラインが開始状態の場合、フォアグラウンド・セッションでは実行できません。

SET_ATTRIBUTEプロシージャ

このプロシージャは、パイプライン属性を設定します。オーバーロードされた2つのプロシージャがあります。1つは単一の属性を設定するためのプロシージャで、もう1つは属性名と値のペアのJSONドキュメントを使用して複数の属性を設定するプロシージャです。

構文

PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attribute_name       IN   VARCHAR2,
      attribute_value      IN   CLOB
);
 
PROCEDURE DBMS_CLOUD_PIPELINE.SET_ATTRIBUTE(
      pipeline_name        IN   VARCHAR2,
      attributes           IN   CLOB
);

Parameters

パラメータ 説明

pipeline_name

属性を設定するパイプラインの名前を指定します。

このパラメータは必須です。

attribute_name

設定する属性の属性名を指定します。

詳細は、DBMS_CLOUD_PIPELINE属性を参照してください。

attribute_value

設定するパイプライン属性の値を指定します。

詳細は、DBMS_CLOUD_PIPELINE属性を参照してください。

attributes

属性名と値を含むJSONドキュメントを指定します。

詳細は、DBMS_CLOUD_PIPELINE属性を参照してください。

使用上のノート

  • DBMS_CLOUD_PIPELINE.SET_ATTRIBUTEを使用してattributesパラメータで複数の属性を設定すると、既存のすべての属性が削除され、JSONドキュメントから指定された属性で上書きされます。

START_PIPELINEプロシージャ

プロシージャは、データ・パイプラインを起動します。パイプラインが開始されると、パイプライン属性で構成されたintervalに従って、パイプライン操作はスケジュール済ジョブで継続的に実行されます。

構文

DBMS_CLOUD_PIPELINE.START_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      start_date           IN   TIMESTAMP WITH TIME ZONE DEFAULT NULL
);

Parameters

パラメータ 説明

pipeline_name

パイプラインの名前を指定します。

このパラメータは必須です。

start_date

パイプライン・ジョブの開始日を指定します。

デフォルト値: NULL

使用上のノート

  • デフォルトでは、パイプラインが開始されるとすぐにパイプライン・ジョブが開始されます。パイプライン・ジョブを後で開始するには、start_dateパラメータを使用して有効な日付またはタイムスタンプを指定します。

  • パイプラインintervalおよびその他のパイプライン属性の詳細は、DBMS_CLOUD_PIPELINE属性を参照してください。

STOP_PIPELINEプロシージャ

このプロシージャは、データ・パイプラインを停止します。パイプラインが停止すると、パイプラインに対して将来のジョブはスケジュールされません。

構文

DBMS_CLOUD_PIPELINE.STOP_PIPELINE(
      pipeline_name        IN   VARCHAR2,
      force                IN   BOOLEAN  DEFAULTFALSE
);

Parameters

パラメータ 説明

pipeline_name

パイプラインの名前を指定します。

このパラメータは必須です。

force

強制パラメータがTRUEとして渡されると、パイプラインで実行中のジョブが終了します。

有効な値: TRUE, FALSE

デフォルト値: FALSE

DBMS_CLOUD_PIPELINE属性

属性は、データ・パイプラインの動作を制御および構成するのに役立ちます。

属性

ノート:

「パイプライン・タイプ」列に示されているように、パイプライン・タイプLOADまたはEXPORTに応じて、パイプラインは異なる属性セットをサポートします。
属性名 説明 パイプライン・タイプ パイプラインの開始後に変更可能
credential_name

ソースのCloud Object Storageにアクセスするための資格証明の名前。

デフォルト値: NULL。

credential_nameを指定しない場合、credential_nameはNULLに設定されます。

LOAD, EXPORT ○
field_list

ソース・ファイル内のフィールドとそのデータ型を識別します。この引数の構文は、通常のOracle外部表のfield_list句と同じです。詳細は、Oracle Database 19cユーティリティまたはOracle Database 23aiユーティリティのfield_listを参照してください。

デフォルト値: NULL

デフォルト値では、フィールドとそのデータ型は、table_name属性で指定された表の列によって決定されます。

LOAD ○
format

パイプラインのタイプを表すオプション。

データポンプformatは、エクスポート・パイプラインではサポートされていません。

この属性は、LOADパイプラインとEXPORTパイプラインの両方に必須です。

LOAD, EXPORT ○
interval

スケジュール済パイプライン・ジョブの連続実行間隔(分)。

デフォルト値: 15分

 LOAD, EXPORT ○
key_column

新しいデータをオブジェクト・ストアに継続的にエクスポートするための、指定したtableまたはqueryのタイムスタンプまたは日付列。最終実行タイムスタンプまたは日付は、エクスポート・パイプラインによって追跡され、key_columnの値と比較されて、オブジェクト・ストアにエクスポートするための新しいデータが識別されます。

デフォルト値: NULL

エクスポート・パイプラインにkey_columnが指定されていない場合、tableまたはqueryの内容全体が、各パイプライン・ジョブ実行のオブジェクト・ストアにアップロードされます。

EXPORT ×
location

このパラメータは、ソース・ファイルのURIまたはディレクトリとソース・ファイルを指定します。ファイル名にはワイルドカードを使用できます。

このパラメータは必須です。

クラウドのソース・ファイルURI

バケットまたはサブフォルダのソース・ファイルURIを指定できます。ワイルドカードを使用して、サブフォルダまたはファイル名パターンを指定できます。文字「*」は、複数の文字に対応するワイルドカードとして使用でき、文字「?」は1文字のワイルドカードとして使用することができます。

ワイルドカードの使用例:

location_uri => 'https://objectstorage.my$region.oraclecloud.com/n/namespace-string/b/bucketname/o/year=????/month=??/*.csv

URIのフォーマットは、使用中のクラウド・オブジェクト・ストレージ・サービスによって異なります。詳細は、「クラウド・オブジェクト・ストレージURIフォーマット」を参照。

ディレクトリ

1つのディレクトリとファイル名を指定できます。ディレクトリを指定する形式は、'MY_DIR:filename.ext'です。デフォルトでは、ディレクトリ名MY_DIRはデータベース・オブジェクトであり、大/小文字は区別されません。ファイル名は、大/小文字が区別されます。

ワイルドカードを使用して、ディレクトリ内のファイル名を指定できます。文字"*"は、複数の文字に対応するワイルドカードとして使用でき、文字"?"は、1文字に対応するワイルドカードとして使用することができます。

例: 'MY_DIR:*"または'MY_DIR:test?'

大/小文字を区別するディレクトリ名を指定するには、二重引用符を使用します。

例: '"my_dir1":*, "my_dir2":Test?'

引用符文字を含めるには、2つの引用符を使用します。

例: 'MY_DIR:''filename.ext'。これは、ファイル名が引用符(')で始まることを示します。

   
priority

パイプラインに対して実行されるパラレル操作の数を決定する文字列値を指定します。

  • ロード・パイプラインでは、パラレルにロードされるファイルの数が決定されます。

  • エクスポート・パイプラインでは、データベースからデータをフェッチするための並列度が決定されます。

優先度が高い操作は、より多くのデータベース・リソースを消費し、より早く完了します。

有効な値:

  • HIGH: データベースのECPU数(データベースがOCPUを使用している場合はOCPU数)を使用して処理されるパラレル・ファイルの数を決定します。
  • MEDIUM: 中規模サービスの同時実行性制限を使用して、同時プロセスの数を決定します。デフォルトは4です。
  • LOW: パイプライン・ジョブを順番に実行します。

デフォルト値: MEDIUM

同時ファイル操作の最大数は64に制限されています。

 LOAD, EXPORT ○
query

必要なデータのみがエクスポートされるようにSELECT文を指定します。問合せによって、テキスト・ファイル(CSV、JSON、ParquetまたはXML)またはダンプ・ファイルとしてエクスポートするファイルのコンテンツが決定されます。

たとえば次のようにします。

SELECT warehouse_id, quantity FROM inventories

デフォルト値: NULL

エクスポート・パイプラインの場合、table_nameまたはqueryは必須です。

EXPORT ×
table_name

データをロードまたはエクスポートするためのターゲット表の名前を指定します。

ロード・パイプラインの場合、table_nameは必須です。

エクスポート・パイプラインの場合、table_nameまたはqueryは必須です。

LOAD, EXPORT ×
table_owner

データをロードまたはエクスポートするためのターゲット表が存在するスキーマの名前。

デフォルト値: NULL

NULL値の場合、ターゲット表はプロシージャを実行しているユーザーと同じスキーマ内にあります。

LOAD, EXPORT ×