Java APIs - again - and IncludeExclude agg query parameters

[ppine7 (Marina Popova)]

I see many questions about the availability of full Java API docs for ElasticSearch - some form 2014/2015. Still, I cannot find them anywhere. The only docs that are close to what a Java developer would need to start interacting with ES are docs from here: https://www.elastic.co/guide/en/elasticsearch/client/java-api/current/_metrics_aggregations.html - but they just show a few small examples and in no way provide info about all classes/interfaces/methods etc. to be able to write production-level code.

Here is an example.
We used to have this code to create aggregate queries for ES2.3:
TermsBuilder trafficType = AggregationBuilders.terms(TRAFFIC_TYPE).field(RI_PROTOCOL)
.include(new String[]{HTTP, HTTPS, UNKNOWN}).missing(UNKNOWN);

Now we are migrating to ES5.5 and this code does not compile. The migration guide I see here: https://www.elastic.co/guide/en/elasticsearch/reference/current/breaking_50_java_api_changes.html did not help as this specific case is not covered there.
By trial and error I found that the new class I should use for Term aggregations is this:
TermsAggregationBuilder. However, it does not have include( String [] args) method anymore.
By hovering over the errors in Eclipse I see suggestions that maybe I should use includeExclude(...) method instead.
Ok. But, this method tales IncludeExclude class as an argument. And I cannot find any info on how to construct and use that class.... unless I start digging in the source code of ES, which really should be only the last resort kind of solution.

The process should not be so painful. All that is needed are just full Java API docs - and Java developers can take it from there.

In the meantime - could somebody provide more info on how IncludeExclude arguments should be constructed for agg queries in Java?

[cbuescher (Christoph)]

Hi,

I agree that this should usually be solved by Javadocs, and I think we are publishing them (although they might not be as complete as can be, but PRs are always welome...). I'm going to try finding the link to the javadocs, there is an open issue here that agrees we should put them in the documentation, but the link given in the issue doesn't seem to work currently:

Issue: Link to javadocs

In the meantime, hope this solves your problem:

TermsAggregationBuilder termsAgg = 
                AggregationBuilders.terms(TRAFFIC_TYPE).field(RI_PROTOCOL)
                .includeExclude(new IncludeExclude(new String[] { HTTP, HTTPS, UNKNOWN }, null))
                .missing(UNKNOWN);

[ppine7 (Marina Popova)]

Thanks, Christoph,
Yes, this change did solve the issue! I did figure it out a bit earlier by going into ES source code ...

Thanks for tracking the API docs - I'm sure many of us developers will be very happy!

Marina

[cbuescher (Christoph)]

@ppine7

I did figure it out a bit earlier by going into ES source code

Great, that's usually the fastest way. In any case, usually the method names in the various builders should mostly resemble the parameter names that are used in the rest request bodies. In the case of InculdeExclude thats a bit more tricky, I agree.

The adress for javadocs is: core 5.5.0 API

But as I mentioned most of the internal classes don't have much docs, but some of the builder classes do. IncludeExclude at least has some class docs and list all the constructors (which IDEs, should usually also do).

Hope this helps.