field-caps.asciidoc 3.7 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182
  1. [[java-rest-high-field-caps]]
  2. === Field Capabilities API
  3. The field capabilities API allows for retrieving the capabilities of fields across multiple indices.
  4. [[java-rest-high-field-caps-request]]
  5. ==== Field Capabilities Request
  6. A `FieldCapabilitiesRequest` contains a list of fields to get capabilities for,
  7. should be returned, plus an optional list of target indices. If no indices
  8. are provided, the request will be executed on all indices.
  9. Note that fields parameter supports wildcard notation. For example, providing `text_*`
  10. will cause all fields that match the expression to be returned.
  11. ["source","java",subs="attributes,callouts,macros"]
  12. --------------------------------------------------
  13. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-request]
  14. --------------------------------------------------
  15. [[java-rest-high-field-caps-request-optional]]
  16. ===== Optional arguments
  17. ["source","java",subs="attributes,callouts,macros"]
  18. --------------------------------------------------
  19. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-request-indicesOptions]
  20. --------------------------------------------------
  21. <1> Setting `IndicesOptions` controls how unavailable indices are resolved and
  22. how wildcard expressions are expanded.
  23. [[java-rest-high-field-caps-sync]]
  24. ==== Synchronous Execution
  25. The `fieldCaps` method executes the request synchronously:
  26. ["source","java",subs="attributes,callouts,macros"]
  27. --------------------------------------------------
  28. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute]
  29. --------------------------------------------------
  30. [[java-rest-high-field-caps-async]]
  31. ==== Asynchronous Execution
  32. The `fieldCapsAsync` method executes the request asynchronously,
  33. calling the provided `ActionListener` when the response is ready:
  34. ["source","java",subs="attributes,callouts,macros"]
  35. --------------------------------------------------
  36. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute-async]
  37. --------------------------------------------------
  38. <1> The `FieldCapabilitiesRequest` to execute and the `ActionListener` to use when
  39. the execution completes.
  40. The asynchronous method does not block and returns immediately. Once the request
  41. completes, the `ActionListener` is called back using the `onResponse` method
  42. if the execution successfully completed or using the `onFailure` method if
  43. it failed.
  44. A typical listener for `FieldCapabilitiesResponse` is constructed as follows:
  45. ["source","java",subs="attributes,callouts,macros"]
  46. --------------------------------------------------
  47. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-execute-listener]
  48. --------------------------------------------------
  49. <1> Called when the execution is successfully completed.
  50. <2> Called when the whole `FieldCapabilitiesRequest` fails.
  51. [[java-rest-high-field-caps-response]]
  52. ==== FieldCapabilitiesResponse
  53. For each requested field, the returned `FieldCapabilitiesResponse` contains its type
  54. and whether or not it can be searched or aggregated on. The response also gives
  55. information about how each index contributes to the field's capabilities.
  56. ["source","java",subs="attributes,callouts,macros"]
  57. --------------------------------------------------
  58. include-tagged::{doc-tests}/SearchDocumentationIT.java[field-caps-response]
  59. --------------------------------------------------
  60. <1> A map with entries for the field's possible types, in this case `keyword` and `text`.
  61. <2> All indices where the `user` field has type `keyword`.
  62. <3> The subset of these indices where the `user` field isn't searchable, or null if it's always searchable.
  63. <4> Another subset of these indices where the `user` field isn't aggregatable, or null if it's always aggregatable.