elasticsearch-java

elasticsearch-java copied to clipboard

This is a roadmap issue for the Java API client documentation. If you want additional topics to be addressed than the ones listed below, please add a comment.

The documentation structure derives from the two main principles that guided the Java API client design:

• be very close to the Elasticsearch JSON API. The client no more depends on Elasticsearch server internals, and is generated from the API specification. This guarantees consistency with everything that is explained in the Elasticsearch documentation.
• allow completion-driven discovery of APIs and their properties. The lambada-based DSL is meant for that.

With that in mind, the documentation is structured in two main areas:

• Java API conventions: explain the conventions used consistently (because of code generation) throughout the entire code base,
• Using the Java API client: provide use-case oriented tutorials to get started and for more advanced/less obvious Elasticsearch APIs.

We do not aim for an exhaustive documentation of all Elasticsearch APIs similar to the HLRC docs. This would be a lot of work for little value over the Elasticsearch documentation, in particular with the closer proximity of the Java API client with the Elasticsearch API specification.

Outline

• [x] Introduction
• [x] Getting started
  • [x] Installation
  • [x] Connecting
  • [x] Migrating from the High Level Rest Client
  • [x] Java Low Level Rest Client
• [x] Java API conventions
  • [x] Package structure and namespace clients
  • [x] Method naming conventions
  • [x] Blocking and asynchronous clients
  • [x] Building API objects
  • [x] Lists and maps
  • [x] Variant types
  • [x] Object life cycles & thread safety
  • [x] Creating API objects from JSON data
  • [ ] User-defined types and object mapping
  • [ ] Using server plugin extensions (not yet implemented)
  • [x] Exceptions (linking to troubleshooting)
• [x] Using the Java API client
  • [x] Indexing single documents
  • [x] Bulk: indexing multiple documents
    • [ ] ↑ add links to bulk delete & update
  • [x] Reading documents by id
    • [ ] ↑ add multiget example
  • [x] Searching for documents
    • [ ] ↑ addcomplex queries (nested, range, etc)
  • [ ] Async search
  • [ ] Scroll & Point in Time
  • [x] Aggregations
    • [ ] ↑ add nested aggregations
  • [ ] Updating and deleting documents (incl. bulk)
  • [ ] Creating indices: mappings and settings
  • [ ] Managing indices: ILM
  • [ ] Transport options: custom request headers and parameters.
• [ ] Helpers
  • [ ] Streaming injection with the Bulk Processor (not yet implemented)
  • [ ] Streaming search with the Point in Time helper (not yet implemented)
• [ ] Troubleshooting
  • [ ] Exceptions (moved from API conventions)
  • [ ] Elasticsearch deprecation warnings
  • [ ] Debugging
• [ ] Javadoc and source code
• [x] Release notes
  • [x] Breaking changes policy
  • [ ] Release x.y.z

@swallez this is great.

Can we please add section for Bulk update and Bulk delete as well. As i can see Bulk Update request is changed and it support TDocument and TPartialDocument params.

@sagarpatel07 thanks, and good point. I added bulk update/delete to the list.

Can you please add example for subaggregation. looking for new elasticsearch client code for below query. Filter followed by nested query and term queries.

{
  "aggs_all_filters": {
    "filters": {
      "filters": [
        {
          "bool": {
            "adjust_pure_negative": true,
            "boost": 1.0
          }
        }
      ],
      "other_bucket": false,
      "other_bucket_key": "_other_"
    },
    "aggregations": {
      "facetsData": {
        "nested": {
          "path": "data.attributes.facetEnable.searchable"
        }       
      }
    }
  }
}

Hope there is documentation on creation of mappings from a JSON string.

@KnowledgeGarden for this you can use withJson which is documented here, using index mapping as an example.

Thanks! I switched to that a while back. Still having issues. Plan to document what I did with a gist so the issue can be resolved.

I guess some documentation on how to add a filter to an aggregation could be useful or how to create a new aggregation with a specific name, a filter and other subaggregations as described here https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations-bucket-filter-aggregation.html#search-aggregations-bucket-filter-aggregation.

Also an example when I already have the filter query and want to add it as a filter to an aggregation