Documentation doesn't explain overall structure or composition of document components (queries, filters, etc.)

[bitemyapp]

https://twitter.com/mausch/status/530504035540160513

https://twitter.com/LeviNotik/status/530505312777023488

https://twitter.com/mwotton/status/442775637648891904

https://twitter.com/melvinmt/status/530474427306479616

https://twitter.com/kosmikko/status/502340971527671808

https://twitter.com/kenperkins/status/494173990152175617 (navigation, I've had this problem and I'm a relatively experienced user of the site and ES itself)

https://twitter.com/icyliquid/status/477500839020752896

https://twitter.com/werg/status/466733972324880384 (another suggestion to bypass official ES documentation)

I wrote https://github.com/bitemyapp/bloodhound partly because I was having a hell of a time generating valid Elasticsearch requests without lots of copy-paste and templating.

The docs have not been improved much in the last couple years other than when you did the big site change.

It's extremely hard for a new user of Elasticsearch to get a bird's eye view.

I brought up Bloodhound when I first released it as a way to possibly start a proper spec of what Elasticsearch accepts as a valid request and what it does not. I'd like to revive the idea of having a spec so that users and client implementors don't have to keep rediscovering how Elasticsearch works through haphazard experimentation.

Back when I was implementing Bloodhound I asked if there was a spec. I was told there wasn't one. I was briefly hopeful when I saw there was a Thrift spec...but it passes off the actual document structure as a JSON blob, lending no useful information.

Please at least consider having a spec for the API.

[Fiedzia]

+1. Especially for horrible navigation. Though I think that the since ES income comes largely from support contracts, this may simply be intentional.

[Fiedzia]

+1. Especially for horrible navigation. Though I think that the since ES income comes largely from support contracts, this may simply be intentional.

[Mpdreamz]

The .NET client NEST has already mapped a great deal (guestimate 80%-90%) of the elasticsearch HTTP API so suffice to say we totally can relate to this issue.

That being said C# is not a great reference, i.e it misses i.e sum types to properly describe different valid states an object can take. NEST always expands to the most elaborate form a construct accepts. i.e NEST will always send:

{
    "term" : { "user" : { "value" : "kimchy" } }
}

over

{
    "term" : { "user" : "value" }
}

Even if the NEST API itself allows you to be terser.

We (.NET team) spent some time internally a couple of weeks ago trying to generate and refine a json schema draft 4 spec for all the requests and responses and its individual components but sadly found that some constructs simply cannot be expressed strictly enough in json schema i.e:

{
    "term" : { "user" : "kimchy" }
}

user being a variable property name wreaks havoc on trying to lock it down in a schema. Json schema does allow for something like patternProperties but you can not make them mandatory or limit the number of occurrences.

So its back to the drawing board on this for now. The idea i've been floating now is to identify all places that read and accept json and write out all valid objects it can read / write post that up somewhere and go from there (reference implementations of the types in various languages).

Suggestions are much welcomed!

[Mpdreamz]

The .NET client NEST has already mapped a great deal (guestimate 80%-90%) of the elasticsearch HTTP API so suffice to say we totally can relate to this issue.

That being said C# is not a great reference, i.e it misses i.e sum types to properly describe different valid states an object can take. NEST always expands to the most elaborate form a construct accepts. i.e NEST will always send:

{
    "term" : { "user" : { "value" : "kimchy" } }
}

over

{
    "term" : { "user" : "value" }
}

Even if the NEST API itself allows you to be terser.

We (.NET team) spent some time internally a couple of weeks ago trying to generate and refine a json schema draft 4 spec for all the requests and responses and its individual components but sadly found that some constructs simply cannot be expressed strictly enough in json schema i.e:

{
    "term" : { "user" : "kimchy" }
}

user being a variable property name wreaks havoc on trying to lock it down in a schema. Json schema does allow for something like patternProperties but you can not make them mandatory or limit the number of occurrences.

So its back to the drawing board on this for now. The idea i've been floating now is to identify all places that read and accept json and write out all valid objects it can read / write post that up somewhere and go from there (reference implementations of the types in various languages).

Suggestions are much welcomed!

[ppurang]

+1

[ppurang]

+1

[aloiscochard]

👍

That would benefit any client written for statically typed language.

[aloiscochard]

👍

That would benefit any client written for statically typed language.

[mausch]

You can easily encode sum types in C#, e.g. http://bugsquash.blogspot.com/2012/01/encoding-algebraic-data-types-in-c.html .
They are quite verbose compared to languages with direct support for them, but you still get the benefits of precise typing.

[mausch]

You can easily encode sum types in C#, e.g. http://bugsquash.blogspot.com/2012/01/encoding-algebraic-data-types-in-c.html .
They are quite verbose compared to languages with direct support for them, but you still get the benefits of precise typing.

[clintongormley]

Closing as a duplicate of #8965

[clintongormley]

Closing as a duplicate of #8965