How to use the enum 'co.elastic.clients.elasticsearch._types.Time.Kind.offset'

[308299160]

I know the useage for Kind.Time, but I can't find any useful message about Kind.Offset. None of comment about 'Offset' in code, none of specification, so I don't know how to use the enum 'Kind.Offset'. Please tell me the useage, thanks in advance.

[l-trotta]

Hello! The Time class is implemented as a union to handle both cases accepted by the server, so you can use Offset if you want to set the time as a number (like 2) or Time for strings (like 2d). As an example let's try a HealthReportRequest with the query parameter timeout, which can be set as 0, -1, or any string that defines a time interval:

GET /_cluster/health?timeout=0
GET /_cluster/health?timeout=2s

In java you can write those as:

esClient.cluster().health(h -> h.timeout(Time.of(t -> t.offset(0))))
esClient.cluster().health(h -> h.timeout(Time.of(t -> t.time("2s"))))

Hope this clarifies things for you, let me know :)

[308299160]

@l-trotta Thanks for your answer. But I still have some confusions.I use scroll api, when I use kind of 'Time', '2d' means snapshot of scroll matain 2 days. When I use kind of offset, what's mean that 2 offset?

[l-trotta]

Ah I get the confusion: 2 is actually not supported. The only supported numbers are 0 (which will be interpreted as "no timeout set", meaning it will use the default value for timeout which I think it's 30s) and -1 (infinite timeout). Other than these two special cases, no other number is supported.

[308299160]

@l-trotta Thanks for your patience. I am chinese, so my english is poor 😂.
show my code:

    SearchRequest searchRequest = new SearchRequest.Builder()
            .index(indexName)
            .query(new Query(new MatchQuery.Builder().field("labels").query(label).build()))
            .scroll(new Time.Builder().offset(0).build())
            .size(2)
            .build();

What's mean that 'new Time.Builder().offset(0).build()' in the above code ?
The parameter of 'offset' method only set 0 or -1?

[l-trotta]

Don't worry about your english :) I'll try to be as clear as possible:
For fields such as scroll (or timeout in my previous example) the Elasticsearch server accepts both a string (to define a period of time) or a number (to define other options).

Let's check the documentation for scroll:

Period to retain the search context for scrolling. See Scroll search results.
By default, this value cannot exceed 1d (24 hours).
You can change this limit using the search.max_keep_alive cluster-level setting.

So you can set a value that will determine how long the search context will be kept in memory, and it also tells you that by default the maximum value is 1d. So for example is you want to keep it for 10 hours then you'll write:

.scroll(Time.of(t -> t.time("10h")))

You can check the Time Units documentation for references on the various accepted units.

Now, if you were to set scroll as 0, like this:

.scroll(Time.of(t -> t.offset(0)))

This will select the default value of scroll, which as the documentation said is 1 day!
This is all there is to it, as you know Java is strongly typed, so we needed a way to differentiate the two cases. Since this class is used in multiple other requests, there might be cases where 0 and -1 are not the only numbers accepted, this is why we made it generic.

Hope this clarifies how Time works!

[308299160]

@l-trotta Thank you very much. I get it. The 'Time' class is generic, so it needed support multiple case. Someone maybe want to use number, others want to use string, so, the 'Time' class have two kind(time and offset). The kind of 'offset' can set numbers which we want to use, according to our needs. In my case（scroll api）, 'Time.time' is satisfies my needs, I can ignore 'Time.offset'.