Repository: deepset-ai/haystack

Issue:
Unclear documentation: explicit document IDs
Here: https://github.com/deepset-ai/haystack/blame/master/docs/_src/api/api/document_store.md#L63

You say:

> When using explicit document IDs, any existing document with the same ID gets updated.

For me it is not clear what is meant by "document IDs". Are the optional `index` strings from the function signature meant?

Maybe you could also improve the text here.

Thanks
Philip


Discussion:
Hey @PhilipMay , 

Thanks for the pointer. This is indeed not well described. Happy to clarify it and update it in the docs. 

**Background of IDs**
 The IDs mentioned there refer to the `Document` Object ([Code](https://github.com/deepset-ai/haystack/blob/4a77dc7a026e2ba0e3ca6c09c4bbae4d7bc44809/haystack/schema.py#L33)) that we use in many places in Haystack. For example, a list of Documents can be passed to the above mentioned `write_documents()` function. 
The `Document` object creates a UUID at init unless the user passes a custom one. This ID is stored in `Document.id` and will correspond to the one stored in Elasticsearch (or other DocumentStores) and what you will find in the answers returned from Finder.get_answers().

**Behaviour of write_documents()**
There are two options to deal with a document which ID is already existing in elasticsearch:
a) (Default) Throw Elastic's standard error message for duplicate ids
b) If `update_existing_documents` is set to True for DocumentStore: Overwrite existing documents with the new ones
https://github.com/deepset-ai/haystack/blob/4a77dc7a026e2ba0e3ca6c09c4bbae4d7bc44809/haystack/document_store/elasticsearch.py#L71-L74

**Example** 
```python
from haystack import Document
doc = Document(text="some text")
document_store.write_documents([doc])
d = document_store.get_document_by_id(id=doc.id)
print(d.to_dict())
# overwrite existing doc
doc2 = Document(text="new text", meta={"some_key": "custom Value"}, id=doc.id)
document_store.write_documents([doc2])
d = document_store.get_document_by_id(id=doc.id)
print(d.to_dict())
``` 


Resolving patch:
diff --git a/haystack/document_store/elasticsearch.py b/haystack/document_store/elasticsearch.py
--- a/haystack/document_store/elasticsearch.py
+++ b/haystack/document_store/elasticsearch.py
@@ -220,7 +220,12 @@ def write_documents(self, documents: Union[List[dict], List[Document]], index: O
         """
         Indexes documents for later queries in Elasticsearch.
 
-        When using explicit document IDs, any existing document with the same ID gets updated.
+        Behaviour if a document with the same ID already exists in ElasticSearch:
+        a) (Default) Throw Elastic's standard error message for duplicate IDs.
+        b) If `self.update_existing_documents=True` for DocumentStore: Overwrite existing documents.
+        (This is only relevant if you pass your own ID when initializing a `Document`.
+        If don't set custom IDs for your Documents or just pass a list of dictionaries here,
+        they will automatically get UUIDs assigned. See the `Document` class for details)
 
         :param documents: a list of Python dictionaries or a list of Haystack Document objects.
                           For documents as dictionaries, the format is {"text": "<the-actual-text>"}.


Test patch: