新規レコードの追加

addRecordsサブ操作では、Endecaデータ・ドメインに新規レコードを追加できます。

ingestChanges操作のaddRecordsサブ操作では、新規レコードの追加のみを行うことができます。つまり、既存のレコードは更新できません。

追加されるレコードは、 Endecaデータ・ドメインで完全に新しいレコードとみなされます。つまり、指定された主キーと同じ値を持つレコードがデータ・ドメインにすでに存在する場合、addRecordsリクエストは失敗し、次の例のようなエラー・メッセージが表示されます。

<ingest:errorDetail>Error applying updates: Attempt to add a second identical assignment 
to a unique property: partID="1234"</ingest:errorDetail>

この例では、主キーがpartID=1234のレコードを追加しようとしています。しかし、この主キー/値ペアを持つレコードはすでに存在するので、(エラーが示しているように)一意の属性に対して同じ値をもう1つ追加することはできません。

注意: 既存のレコードを拡張(更新)するには、addOrUpdateRecordsサブ操作(「初期ロード後のレコードの追加」を参照)またはupdateRecordsサブ操作(「レコードの更新」を参照)のいずれかを使用します。

addRecordsリクエスト

addRecordsリクエストでは、ingestChanges操作でaddRecords要素を使用します。追加するレコードには、必要に応じてキー/値ペア割当てを指定できます。このうち、1つの割当てにのみ、一意の属性を使用する必要があります。

追加されるレコードは、同じリクエストの他の操作には使用できません。

注意: 外部トランザクションを開始するトランザクションWebサービスのリクエストの後に、addRecordsリクエストを送信する場合、そのリクエストでは外部トランザクションIDを指定する必要があります。外部トランザクションが開始されていない場合、リクエストのID属性は省略する必要があります。

addRecordsリクエストの基本書式は次のとおりです。

<ns:ingestChanges>
   <!--Optional:-->
   <ns:OuterTransactionId>?</ns:OuterTransactionId>
   <!--Optional:-->
   <ns:Language>en</ns:Language>
   <!--Zero or more repetitions:-->
   <ns:addRecords>
      <ns:record>
         <!--Zero or more repetitions:-->
         <ns1:attribute name="?" type="?">?</ns1:attribute>
      </ns:record>
   </ns:addRecords>
</ns:ingestChanges>

たとえば、次のリクエストでは、partIDがP567、colorがblue、priceが19.99の1つのレコードをデータ・ドメインに追加しています。

<ns:ingestChanges>
  <ns:addRecords>
    <ns:record>
      <ns1:attribute name="partID" type="mdex:string">P567</ns1:attribute>
      <ns1:attribute name="color" type="mdex:string">blue</ns1:attribute>
      <ns1:attribute name="price" type="mdex:double">19.99</ns1:attribute>
    </ns:record>
  </ns:addRecords>
</ns:ingestChanges>

属性partIDの割当てが追加されます。この属性には、レコードの一意の割当てが指定されています。このリクエストでは、color属性およびprice属性も作成されます。

注意: 新規標準属性を作成する場合、リクエストではタイプの指定を省略できます。タイプを指定しない場合、標準属性はタイプmdex:string (PDRのデフォルト)を使用して作成されます。ただし、特定のタイプの標準属性(たとえば、この例ではmdex:double)を作成する場合は、新規属性の作成時にそのタイプを明示的に指定する必要があります。

成功のレスポンス

成功したaddRecordsリクエストに対するingestChangesResponseは、次の例のようになります。

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
   <soapenv:Header/>
   <soapenv:Body>
      <ingest:ingestChangesResponse xmlns:ingest="http://www.endeca.com/MDEX/ingest/3/0">
         <ingest:numPropertiesCreated>2</ingest:numPropertiesCreated>
         <ingest:numRecordsAffected>1</ingest:numRecordsAffected>
         <ingest:numRecordsDeleted>0</ingest:numRecordsDeleted>
      </ingest:ingestChangesResponse>
   </soapenv:Body>
</soapenv:Envelope>

サンプル・レスポンスは、1つのレコードが作成され、2つの属性(color属性およびprice属性)も作成されたことを示しています。partID属性は、すでにデータ・ドメインに存在しているため、作成されませんでした。

失敗のレスポンス

障害時には、SOAPフォルトが返されます。ingestFaultおよびerrorDetail要素には、通常、障害の原因となったエラーが含まれます。

たとえば、主キーP567のレコードがデータ・ドメインにすでに追加されている場合に、addRecordsリクエスト内でそれを再度指定するとします。

<ns1:attribute name="partID">P567</ns1:attribute>

レスポンスによって次のようなエラーが返されます。

<detail>
 <ingest:ingestFault xmlns:ingest="http://www.endeca.com/MDEX/ingest/3/0">
  <ingest:errorDetail>Error applying updates: Attempt to add a second 
   identical assignment to a unique property: partID="P567"</ingest:errorDetail>
 </ingest:ingestFault>
</detail>

この例で、エラーの原因は、主キーP567のレコードがすでにデータ・ドメインに存在しているためです。

失敗時のデータ収集プロセスの状態

データ・インジェストWebサービスでは、レコードのバッチごとに、すべてを挿入するか、すべてを挿入しないという方針を採用しています。つまり、バッチ内で少なくとも1つのレコードがOracle Endeca ServerのDgraphプロセスによって無効とみなされると、すべてのレコードが拒否されます。たとえば、1000レコードのバッチ内に999の有効なレコードと1つの無効なレコードが含まれる場合、999の有効なレコード(および無効なレコード)はデータ・ドメインにロードされません。

データ収集プロセスがETLクライアントまたはDgraphプロセスのクラッシュなどで中断されると、現行のバッチ(中断の発生時に処理中だったバッチ)は、データ・ドメインにロードされません。ただし、その前のすべての有効なバッチは、データ・ドメインにロードされています。たとえば、5000のバッチをロードする予定で、バッチ3500の処理中に中断が発生した場合、バッチ3500はデータ・ドメインにロードされませんが、その前の3499のバッチはデータ・ドメインに存在しています。

データ・ローディング操作には外部トランザクションの使用をお薦めします。

標準属性の割当ておよび作成

標準属性を追加する場合、操作は新規属性(追加される属性)に対して次のように動作します。

新規属性がすでにデータ・ドメインに存在するが、タイプが異なる場合、エラーがスローされて新規属性は追加されません。
新規属性がすでにデータ・ドメインに存在し、同じタイプの場合、エラーはスローされず、何も行われません。

標準属性の名前は、NCName書式を使用する必要があります。標準属性の名前は、次の書式で割当ての要素名として使用されます。

<ns1:attribute name="?" type="?">?</ns1:attribute>

たとえば、ItemIDという名前の標準属性を割り当てるには、次のようにします。

<ns1:attribute name="ItemID" type="mdex:int">247</ns1:attribute>

標準属性は、レコードに対して存在しない属性が指定されると、必要に応じて作成されます。属性のPDRでは、システムのデフォルト設定を使用します。この属性の自動作成を無効にすることはできません。