Basic Update Example

This sample updates a document to an Elasticsearch server via the Elasticsearch Update API. The sample then retrieves the contents of the updated document via a call to the Elasticsearch Get API. The sample displays the results of the Update and Get calls.

For more information on the Elasticsearch Update API, see the Elasticsearch Python Update API and Elasticsearch REST Update API documentation.

Prerequisites

• The samples configuration step has been completed (see Samples Configuration).

• The Elasticsearch API DXL service is running (see Elasticsearch DXL Service).

• In order to enable the use of the update and get APIs, both API names need to be listed in the apiNames setting under the [General] section in the "dxlelasticsearchservice.config" file that the service uses:

  [General]
  apiNames=update,get,...
  

  For more information on the configuration, see the Elasticsearch DXL Python Service configuration documentation.

• Run through the steps in the Basic Index Example to store a document to Elasticsearch. This example will update the stored document.

Running

To run this sample execute the sample/basic/basic_update_example.py script as follows:

python sample/basic/basic_update_example.py

If the document was previously stored via running the Basic Index Example, the output should appear similar to the following:

Response from update:
{
    "_id": "12345",
    "_index": "opendxl-elasticsearch-client-examples",
    "_shards": {
        "failed": 0,
        "successful": 2,
        "total": 2
    },
    "_type": "basic-example-doc",
    "_version": 2,
    "result": "updated"
}
Response from get:
{
    "_id": "12345",
    "_index": "opendxl-elasticsearch-client-examples",
    "_source": {
        "message": "Hello from OpenDXL",
        "source": "Basic Update Example"
    },
    "_type": "basic-example-doc",
    "_version": 2,
    "found": true
}

If the document to be updated does not exist on the Elasticsearch server at the time the sample is run, the output should appear similar to the following:

Requested document was not found on the server

Details

The majority of the sample code is shown below:

# Create the client
with DxlClient(config) as dxl_client:

    # Connect to the fabric
    dxl_client.connect()

    logger.info("Connected to DXL fabric.")

    # Create client wrapper
    client = ElasticsearchClient(dxl_client)

    try:
        # Invoke the update method
        resp_dict = client.update(
            index=DOCUMENT_INDEX,
            doc_type=DOCUMENT_TYPE,
            id=DOCUMENT_ID,
            body={"doc": {"source": "Basic Update Example"}})
    except NotFoundError:
        print("Requested document was not found on the server")
        sys.exit(1)

    # Print out the response (convert dictionary to JSON for pretty printing)
    print("Response from update:\n{0}".format(
        MessageUtils.dict_to_json(resp_dict, pretty_print=True)))

    # Invoke the get method
    resp_dict = client.get(
        index=DOCUMENT_INDEX,
        doc_type=DOCUMENT_TYPE,
        id=DOCUMENT_ID)

    print("Response from get:\n{0}".format(
        MessageUtils.dict_to_json(resp_dict, pretty_print=True)))

Once a connection is established to the DXL fabric, a dxlelasticsearchclient.client.ElasticsearchClient instance is created which will be used to invoke remote commands on the Elasticsearch DXL service.

Next, the dxlelasticsearchclient.client.ElasticsearchClient.update() method is invoked with the index, type (doc_type), and id of the document to update. The call also includes a dict representing the portion of the document body to update.

From the Elasticsearch Python Update API documentation:

"Update a document based on a script or partial data provided."

If the document to be updated does not exist on the Elasticsearch server at the time the sample is run, the update method will raise an elasticsearch.exceptions.NotFoundError exception. In this case, the sample catches the exception, displays an error message, and exits.

If the document to be updated does exist on the Elasticsearch server at the time the sample is run, the next step is to display the contents of the returned dictionary (dict) which contains the results of the attempt to update the document.

To confirm that the document was updated properly, the dxlelasticsearchclient.client.ElasticsearchClient.get() method is invoked to retrieve the information updated for the document. The method is invoked with the same index, type (doc_type), and id of the document used in the prior call to the update method.

From the Elasticsearch Python Get API documentation:

"Get a typed JSON document from the index based on its id."

The final step is to display the contents of the returned dictionary (dict) which contains information for the updated document.