I think this might be partly due to the query language being JSON? It makes every example huge and hard to understand. JSON is a serialization format that's human-readable, it's not a human-first language. So it's a pity that's how you're expected to write searches (I know they have some SQL support now, but I've never seen it in the docs)
I don't think this has anything to do with json or examples in general. At least not for me.
Quite often after reading their doc I just don't understand what result I should expect.
Also the whole documentation simply lacks sane navigation. It's almost impossible to find anything there without google.
In 50% of cases this is how it works for me (exaggerated):
Question: how do I sum two integers?
Expected Answer: You should use SUM(). The result of the function is the sum of two integers. Examples:
2 + 2 = 4
2 + (-2) = 0
-1 + (-1) = -2
Answer from Elastic docs: Well, you should execute this query agains this API, which will launch X subroutines in Elastic engine and the final result will be the result of of the aggregation of function defined by the Ex with En+1 being your query's body field Y with respect to url query param N.
Hate to pile on, but I'm glad it's not just me. When I read their docs, I just get the feeling that I'm kind of dumb, or I just don't have the context they expect me to have.
Every time I consult their docs, I feel like I have less of a handle on the topic than when I started.
I think this might be partly due to the query language being JSON? It makes every example huge and hard to understand. JSON is a serialization format that's human-readable, it's not a human-first language. So it's a pity that's how you're expected to write searches (I know they have some SQL support now, but I've never seen it in the docs)
I don't think this has anything to do with json or examples in general. At least not for me.
Quite often after reading their doc I just don't understand what result I should expect. Also the whole documentation simply lacks sane navigation. It's almost impossible to find anything there without google.
In 50% of cases this is how it works for me (exaggerated):
Question: how do I sum two integers?
Expected Answer: You should use SUM(). The result of the function is the sum of two integers. Examples:
2 + 2 = 4
2 + (-2) = 0
-1 + (-1) = -2
Answer from Elastic docs: Well, you should execute this query agains this API, which will launch X subroutines in Elastic engine and the final result will be the result of of the aggregation of function defined by the Ex with En+1 being your query's body field Y with respect to url query param N.
Hate to pile on, but I'm glad it's not just me. When I read their docs, I just get the feeling that I'm kind of dumb, or I just don't have the context they expect me to have.
This. It almost like their docs is a cheat sheet for the Elastic devs, not for the end users.