Replacing records

The Data Ingest Web Service allows you to replace records in a running data domain.

The updateRecords operation of ingestChanges includes the replaceRecords element to replace records.

When you replace a record, the Data Ingest Web Service first deletes the record (along with all of its assignments on all attributes) and then adds a new record with the attribute assignments that you specify for the record, including a required assignment on a primary-key attribute.

The request must specify the EQL expression that correctly identifies one or more records to be replaced, using this request format:
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ns="http://www.endeca.com/MDEX/ingest/2/0" 
xmlns:ns1="http://www.endeca.com/MDEX/XQuery/2009/09">
   <soapenv:Header/>
   <soapenv:Body>
      <ns:ingestChanges>
          <ns:replaceRecords>
            <ns:recordSpecifier>?</ns:recordSpecifier>
            <ns:record>
               <ns1:attribute name="?" type="mdex:string">?</ns1:attribute>
             </ns:record>
         </ns:replaceRecords>
      </ns:ingestChanges>
   </soapenv:Body>
</soapenv:Envelope>

Record replacement, since it is the combination of a deletion and an addition, cannot be combined in the same request with any operation that would modify the records to be deleted. Similarly, the record to be added is not available for any operations in the same request.

If you submit the ingestChanges request after a Transaction Web Service request that starts an outer transaction, the request must specify the outer transaction ID. If no outer transactions have been started, the ID attribute must be omitted in the request.

To replace a record in the data domain:

  1. Ensure that both the data domain's Dgraph process and the Data Ingest Web Service are running.
  2. Create a replaceRecords request, similar to the example below that replaces one record, and send the request to the Data Ingest service.
    <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
    xmlns:ns="http://www.endeca.com/MDEX/ingest/2/0" 
    xmlns:ns1="http://www.endeca.com/MDEX/XQuery/2009/09">
       <soapenv:Header/>
       <soapenv:Body>
          <ns:ingestChanges>
              <ns:replaceRecords>
                <ns:recordSpecifier>"partID" = 'P345'</ns:recordSpecifier>
                <ns:record>
                  <ns1:attribute name="partID">P345</ns1:attribute>
                   <ns1:attribute name="color" type="mdex:string">green</ns1:attribute>
                 <ns1:attribute name="price">100</ns1:attribute>
                </ns:record>
             </ns:replaceRecords>
          </ns:ingestChanges>
       </soapenv:Body>
    </soapenv:Envelope>
    Note: When you are replacing records, you are first deleting a record and all its assignments on all attributes (including an assignment on a primary-key attribute, which is required), and then adding assignments on those attributes that are listed inside the record element. Therefore, to ensure that an update operation succeeds, always include the primary-key attribute in the description of the record that is being updated. In this example, the primary-key attribute is partID, and even though its assignment for this record is not being replaced, this attribute must be included in the record's description to make the update operation valid.
  3. After the request is made, check the ingestChangesResponse to determine if the request transaction was successful.
A successful ingestChangesResponse returned from the above sample request should look like this, indicating that one record has been affected:
<ingest:ingestChangesResponse xmlns:ingest="http://www.endeca.com/MDEX/ingest/2/0">
   <ingest:numPropertiesCreated>0</ingest:numPropertiesCreated>
   <ingest:numRecordsAffected>1</ingest:numRecordsAffected>
   <ingest:numRecordsDeleted>1</ingest:numRecordsDeleted>
</ingest:ingestChangesResponse>

Note that if you incorrectly identify records, the replaceRecords request will not fail, but instead will delete zero records and add one record (if using the example above). In this case, the numRecordsDeleted element in the response will have a value of 0, and numRecordsAffected will have a value of 1.