Field Capabilities API

edit

The field capabilities API allows for retrieving the capabilities of fields across multiple indices.

Field Capabilities Request

edit

A FieldCapabilitiesRequest contains a list of fields to get capabilities for, should be returned, plus an optional list of target indices. If no indices are provided, the request will be executed on all indices.

Note that fields parameter supports wildcard notation. For example, providing text_* will cause all fields that match the expression to be returned.

FieldCapabilitiesRequest request = new FieldCapabilitiesRequest()
    .fields("user")
    .indices("posts", "authors", "contributors");

Optional arguments

edit
request.indicesOptions(IndicesOptions.lenientExpandOpen()); 

Setting IndicesOptions controls how unavailable indices are resolved and how wildcard expressions are expanded.

Synchronous Execution

edit

The fieldCaps method executes the request synchronously:

FieldCapabilitiesResponse response = client.fieldCaps(request, RequestOptions.DEFAULT);

Asynchronous Execution

edit

The fieldCapsAsync method executes the request asynchronously, calling the provided ActionListener when the response is ready:

client.fieldCapsAsync(request, RequestOptions.DEFAULT, listener); 

The FieldCapabilitiesRequest to execute and the ActionListener to use when the execution completes.

The asynchronous method does not block and returns immediately. Once the request completes, the ActionListener is called back using the onResponse method if the execution successfully completed or using the onFailure method if it failed.

A typical listener for FieldCapabilitiesResponse is constructed as follows:

ActionListener<FieldCapabilitiesResponse> listener = new ActionListener<FieldCapabilitiesResponse>() {
    @Override
    public void onResponse(FieldCapabilitiesResponse response) {
        
    }

    @Override
    public void onFailure(Exception e) {
        
    }
};

Called when the execution is successfully completed.

Called when the whole FieldCapabilitiesRequest fails.

FieldCapabilitiesResponse

edit

For each requested field, the returned FieldCapabilitiesResponse contains its type and whether or not it can be searched or aggregated on. The response also gives information about how each index contributes to the field’s capabilities.

Map<String, FieldCapabilities> userResponse = response.getField("user");  
FieldCapabilities textCapabilities = userResponse.get("keyword");

boolean isSearchable = textCapabilities.isSearchable();
boolean isAggregatable = textCapabilities.isAggregatable();

String[] indices = textCapabilities.indices(); 
String[] nonSearchableIndices = textCapabilities.nonSearchableIndices(); 
String[] nonAggregatableIndices = textCapabilities.nonAggregatableIndices();

A map with entries for the field’s possible types, in this case keyword and text.

All indices where the user field has type keyword.

The subset of these indices where the user field isn’t searchable, or null if it’s always searchable.

Another subset of these indices where the user field isn’t aggregatable, or null if it’s always aggregatable.