Elasticsearch-py: Examples in doc

[Garito]

Hi!
I'm new to elasticsearch but I'm not to python. There is no examples in the documentation so it's super hard to start with your client

For example I'm trying to update a document
Did I have to do this:

body = {"content_type": content_type, "accept": accept, "accept_lang": accept_lang}
es.update(index = esindex, id = hit['_id'], body = body)

Or this:

body = {"_index": esindex, "id": hit['_id'], "content_type": content_type, "accept": accept, "accept_lang": accept_lang}
es.update(body = body)

Exactly no one works... :(

Could you point me why? Thanks!

[Garito]

Anyone here?

[HonzaKral]

Hi,
the client maps very closely to the REST api offered by elasticsearch so you can actually use it's documentation.

In this case if you want to update the document using a partial document, it needs to be in the doc key in the body, so:

body = {"doc": {"content_type": content_type, "accept": accept, "accept_lang": accept_lang}}
es.update(index = esindex, id = hit['_id'], body = body)

Alternatively, if you wish to replace the entire document you can use your code as is and just use the .index method instead.

[Garito]

Thanks for the response
It is imperative that you add tons of examples in the documentation to avoid this kind of doubts
The whole documentation from Elasticsearch has the same problem: the lag of examples

I understand that for you could be obvious but not for the rest (spacially if you are a newbie like me)

[Garito]

Hi!
I've tested your suggestion without success. Here is my update attempt:

body = {"doc": {
"content_type": content_type,
"accept": accept,
"accept_lang": accept_lang
}
}

es.update(index = esindex, id = hit['_id'], body = body)

And here is the raised error:
TypeError: update() takes at least 4 arguments (5 given)

Could you point me where the error is?

Thanks a lot!

[HonzaKral]

You need to specify full path to the document - doc_type paramter is
missing.

[Garito]

Thanks!
As you can see it is not obvious event for you

I'm not agree with you about closing this issue because the original intent for this one is to have better documentation

[xavitorne]

Hi,
You can find examples here:

https://github.com/elasticsearch/elasticsearch-py/tree/master/example

On Thu, Sep 18, 2014 at 2:27 PM, Garito [email protected] wrote:

Thanks!
As you can see it is not obvious event for you

I'm not agree with you about closing this issue because the original
intent for this one is to have better documentation

—
Reply to this email directly or view it on GitHub
https://github.com/elasticsearch/elasticsearch-py/issues/126#issuecomment-56031065
.

Xavi Torné

[Garito]

Xavi!
I've seen them before but this only enforces my point: super hard to follow, barely commented
For instance: what do you think a newbie will think if she reads:

es.update(
index='git',
doc_type='repos',
id='elasticsearch',
body={
"script" : "ctx._source.tags += tag",
"params" : {
"tag" : "java"
}
}
)

script???????? WTF!!!!

If the writer of the docs don't put in the newbie's shoes, how do you expect what will be her feelings?
Do you think that with this examples will be confortable?

I anwser my self: huge NO (and the proof of that is this very thread. I'm newbie to elasticsearch but have huge experience with computing and I have lots of troubles to follow the whole elasticsearch company help documents)

[xavitorne]

I think the problem is not in elasticsearch-py, this is an easy client and
its documentation is sufficient. If you understand elasticsearch api, you
can understand this client perfectly.
But i'm agree the elasticsearch.org documentation ...is a little bit
complicated. The problem maybe is there, but not an issue in
elasticsearch-py :).

If you have problems with certain requests, you can try first with "curl"
and elasticsearch api directly, once you have the correct request you can
do easy the correct one with the client.

On Thu, Sep 18, 2014 at 3:16 PM, Garito [email protected] wrote:

Xavi!
I've seen them before but this only enforces my point: super hard to
follow, barely commented
For instance: what do you think a newbie will think if she reads:

es.update(
index='git',
doc_type='repos',
id='elasticsearch',
body={
"script" : "ctx._source.tags += tag",
"params" : {
"tag" : "java"
}
}
)

script???????? WTF!!!!

If the writer of the docs don't put in the newbie's shoes, how do you
expect what will be her feelings?
Do you think that with this examples will be confortable?

I anwser my self: huge NO (and the proof of that is this very thread. I'm
newbie to elasticsearch but have huge experience with computing and I have
lots of troubles to follow the whole elasticsearch company help documents)

—
Reply to this email directly or view it on GitHub
https://github.com/elasticsearch/elasticsearch-py/issues/126#issuecomment-56036198
.

Xavi Torné

[Garito]

So you think it is not a elasticsearch-py problem to show how to use it? WAT? (there is no redundant info when it comes to examples)
Then you suggest we use the elasticsearch api but then you are agree that it is too complicated WAT?

It doesn't matter how I try to make my tests if I don't really know how to test, don't you think so?

[HonzaKral]

Garito, could you please use a slightly less aggressive tone? it is not constructive when you attack people who are trying to help you or demand answers instead of politely asking. Thank you!

As Xavi said - elasticsearch-py is intended for people who know elasticsearch and it's APIs and just need a convenient way how to call those from python. For more advanced use cases we are building Elasticsearch DSL in python, right now it can help you with query building.

I absolutely agree that more examples would be great for both elasticsearch and the python client. We are trying to solve it for elasticsearch by publishing a book (The Definitive Guide, part of the docs on-line or soon as eBook or dead-tree book from O'Reilly) and improving the docs. To replicate that for each and every client we have and maintain would be a herculean task with questionable results.

I know the documentation could be greatly improved, no question about it. It you have any concrete criticism of the provided example I would be thrilled to hear them. A script is perfectly reasonable way to update a document in elasticsearch - some operations are only doable by a script, for example incrementing a number or adding an item to a list (as this example shows).

[Garito]

Sorry is not my intention. But, in the same time, you need to understand that an anwser like a "documentation is good enought" is not true and unrespectful, too, giving the fact that never a docu is good enought, never, ever... (it is like a piece of art, ask an artist)

I understand that making open source is super hard because it is a lot of work, but you need to understand that when someone ask is because one has search a lot before (if you ask without research you risk to ask something super obvious) and some rude answer like "the doc is enought" (it is rude because then it implies one is stupid) causes more frustration

The lag of examples in the documentation is something endemic in elasticsearch, I am using elasticsearch, logstash and kibana and the problem is the same everywhere in this company

This is not a criticism, believe me, it is a fact, only a TODO's line in the readme, no problem but I think that, because we all know how it works, everyone can have pacience with people's frustration

I ask you sorry again if my tone was rude. You teach me how to solve my problem and, because of that, I thank you, this is what is really important to me

[HonzaKral]

I did not say, nor do I think it, that the documentation is good or done, just that we have other priorities now. If you have concrete feedback on the examples, I would be super happy.

Also if you have any ideas on how to improve things - for example the required arguments are correctly set in python - I use positional args for required and keyword for optional. Is that clear enough or is there a way how to make it clearer?

Thanks!