api use help

[personAutumn]

Description

help,
I wnat to send a search request ,need to used api to
search(SearchRequest request, Class tDocumentClass)
,but I do not know how to use it。

I checked Google，and got nothing，so I want to come here for help
How about create "tDocumentClass"

[pgifford]

tDocumentClass is the class of the response you're expecting. Try passing Map.class for that parameter.

The API is almost completely undocumented, even the source code lacks basic Javadoc. My suggestion is to develop using the deprecated Rest High Level Client (RHLC). It's well-documented and there are plenty of examples. Once you have that working then convert to the Java API client.

I suggest that approach because on my project another developer and I are working on converting RHLC code to use the Java API client. We both agree that if we didn't have working RHLC code it would be nearly impossible to develop using the Java API client from scratch. We frequently have to refer to the API client's source code and test code to understand how to use the API client. Looking through open and closed issues has also helped because sometimes people include their source code in issues and comments.

Unfortunately "Java API client" is such a generic name it may be hard to find specific examples/tutorials in the future (once they exist).

[swallez]

@personAutumn a search will return documents from the index. Instead of dealing with raw JSON, the Java API client allows you to map these documents to application classes. This is the role of tDocumentClass: it is the class to use to return search hits.

This pattern is illustrated in the getting started documentation.

This project is still new and indeed documentation is scarce. Improving it is however a priority. There are two aspects to this:

• introductory material to help get started, which is obviously what is missing here,
• documentation for API classes and their properties. This part of the work on the API specification where our documentation team is porting information from the Elasticsearch API docs to the API specification used to generate the client code.

@pgifford although the Java API client isn't as mature as the HLRC, advising to stick with HLRC goes in the wrong direction: HLRC is in maintenance mode while the new Java client is in active development. So while it may be low in documentation yet, things will improve in the coming months.

[pgifford]

@swallez I apologize for the confusion. My advice was to start with HLRC and then move to the Java API client, not to stick with the HLRC. It is my opinion that it would be impossible for someone with zero Elasticsearch experience to use the Java API client at this time given the lack of documentation.

I absolutely do not advise staying with the HLRC. I have been unabashed in my praise of the Java API client here at work. I frequently describe it as "beautiful" which I don't think I've ever said about a library in my 20+ years of Java development. I think the client is brilliant and is a joy to use. However, we are converting from the HLRC so we already have working code which I believe makes it possible for us to convert to the documentation-less Java API client .

Great job on the Java API client, seriously.

[swallez]

@pgifford oh, so I misunderstood your comment. Thanks a lot for the wonderful comment, this is music to my ears! Users usually come to us to raise issues or ask questions, so it's really nice to hear this, although I totally understand your frustration about documentation. Thanks 😊

[technige]

I'd also like to second @swallez here and confirm that improving our client documentation is a big priority for us. So if you have any specific suggestions on areas we can improve, it'll be great to hear those.

[grambofof]

@technige @swallez Considering we're now 5 months out from the first documentation request I can see on here, and there's still scant documentation or examples of even the basic procedures, such as creating indices and doing some searches (you only get that from examples of how it uses lambda expressions now), it would seem like publishing anything, anything at all that you have right now (as in today) would be a suggestion on an area for improvement.

This might very well be the wonderous code that @pgifford gives you praise for, but that doesn't mean much if next to no one knows how to use it. I'd rather stick to the deprecated code that works just fine and has enough documentation to figure it out than bang my head against updating (as I've done for the past couple weeks) to the best code in the world with barely three examples to show me how it works.

It could be great, if we all had 20+ years of Java coding under our belts, but I'm betting a good number of us don't, and we're left scratching our heads as to how this convoluted stacking of lambda expressions that don't use the same objects we've been using are all supposed to make our lives easier.

My apologies if this seems like a harsh note. It's born of frustration. It's born out of the fact that I can't give you any other suggestions on how to improve getting your documentation out when I haven't seen much of it, other than to say, give us the basics, please! Documentation for highly complex solutions are no good if we can't even get it set up.

[garyui]

@technige @swallez Many of us have invested much time and sweat in developing apps with the HLRC so documentation and examples on migrating from old to new would be helpful. For example we regularly create and combine different query builders into our query - what is the path to go from that to the new api - or can we use those builders to create the query and still use those with the new Java Client Api. Concrete basic examples with downloadable code would be great. Thanks

[swallez]

We've just published a significant overhaul and extension of the documentation in PR #243. This sets up a solid structure for future documentation and adds tutorials for the fundamental operations in Elasticsearch. It's far from complete and we'll soon add more examples, starting with complex aggregations, index mappings and settings, and a section on troubleshooting.

I'm going to close this issue as the original question about the Class parameter is explained in the tutorials on reading, search and aggregations.

@grambofof lambda expressions did not exist 20 years ago 😉 More seriously, we know that no everybody likes lambda even if we really think they provide a nice way to create complex hierarchical structures that exist everywhere in the Elasticseach API. And for that, every class has a more traditional Builder companion class that you can use if you prefer this approach. These builder objects are what is used behind the hoods by the lambda-based DSL. This is explained in Building API objects.

@garyui the Java API client is a brand new code base and code written against HLRC is not compatible with the new client. This is by design, as one of the goals of this new client is to remove the dependency to the Elasticsearch code base that exists in HLRLC. That being said, HLRC 7.17 will work with Elasticsearch 8.x if compatibility mode is enabled in HLRC. Also, HLRC and the Java API client can live side by side in the same application and share the same network connections. This is explained in "Migrating from the High Level Rest Client" that now has its own page in the docs.

Thank you all for your patience, and I hope you will find this new documentation useful.