106afd41b6
* step 1 to add aggs in the find function of saved object * setp 2 - add specific unit test to aggs + fix bug found during integrations * step 3 - add security api_integration arounds aggs * fix types * unit test added for aggs_utils * add documentation * fix docs * review I * doc * try to fix test * add the new property to the saved object globaltype * fix types * delete old files * fix types + test api integration * type fix + test * Update src/core/server/saved_objects/types.ts Co-authored-by: Rudolf Meijering <skaapgif@gmail.com> * review I * change our validation to match discussion with Pierre and Rudolph * Validate multiple items nested filter query through KueryNode * remove unused import * review + put back test * migrate added tests to new TS file * fix documentation * fix license header * move stuff * duplicating test mappings * rename some stuff * move ALL the things * cast to aggregation container * update generated doc * add deep nested validation * rewrite the whole validation mechanism * some cleanup * minor cleanup * update generated doc * adapt telemetry client * fix API integ tests * fix doc * TOTO-less * remove xpack tests * list supported / unsupported aggregations * typo fix * extract some validation function * fix indent * add some unit tests * adapt FTR assertions * update doc * fix doc * doc again * cleanup test names * improve tsdoc on validation functions * perf nit Co-authored-by: Xavier Mouligneau <189600+XavierM@users.noreply.github.com> Co-authored-by: Rudolf Meijering <skaapgif@gmail.com> Co-authored-by: Kibana Machine <42973632+kibanamachine@users.noreply.github.com>
111 lines
3.8 KiB
Plaintext
111 lines
3.8 KiB
Plaintext
[[saved-objects-api-find]]
|
|
=== Find objects API
|
|
++++
|
|
<titleabbrev>Find objects</titleabbrev>
|
|
++++
|
|
|
|
experimental[] Retrieve a paginated set of {kib} saved objects by various conditions.
|
|
|
|
[[saved-objects-api-find-request]]
|
|
==== Request
|
|
|
|
`GET <kibana host>:<port>/api/saved_objects/_find`
|
|
|
|
`GET <kibana host>:<port>/s/<space_id>/api/saved_objects/_find`
|
|
|
|
[[saved-objects-api-find-path-params]]
|
|
==== Path parameters
|
|
|
|
`space_id`::
|
|
(Optional, string) An identifier for the space. If `space_id` is not provided in the URL, the default space is used.
|
|
|
|
[[saved-objects-api-find-query-params]]
|
|
==== Query Parameters
|
|
|
|
`type`::
|
|
(Required, array|string) The saved object types to include in the export.
|
|
|
|
`per_page`::
|
|
(Optional, number) The number of objects to return per page.
|
|
|
|
`page`::
|
|
(Optional, number) The page of objects to return.
|
|
|
|
`search`::
|
|
(Optional, string) An Elasticsearch {ref}/query-dsl-simple-query-string-query.html[simple_query_string] query that filters the objects in the response.
|
|
|
|
`default_search_operator`::
|
|
(Optional, string) The default operator to use for the `simple_query_string`.
|
|
|
|
`search_fields`::
|
|
(Optional, array|string) The fields to perform the `simple_query_string` parsed query against.
|
|
|
|
`fields`::
|
|
(Optional, array|string) The fields to return in the `attributes` key of the response.
|
|
|
|
`sort_field`::
|
|
(Optional, string) Sorts the response. Includes "root" and "type" fields. "root" fields exist for all saved objects, such as "updated_at".
|
|
"type" fields are specific to an object type, such as fields returned in the `attributes` key of the response. When a single type is
|
|
defined in the `type` parameter, the "root" and "type" fields are allowed, and validity checks are made in that order. When multiple types
|
|
are defined in the `type` parameter, only "root" fields are allowed.
|
|
|
|
`has_reference`::
|
|
(Optional, object) Filters to objects that have a relationship with the type and ID combination.
|
|
|
|
`filter`::
|
|
(Optional, string) The filter is a KQL string with the caveat that if you filter with an attribute from your saved object type,
|
|
it should look like that: `savedObjectType.attributes.title: "myTitle"`. However, If you use a root attribute of a saved
|
|
object such as `updated_at`, you will have to define your filter like that: `savedObjectType.updated_at > 2018-12-22`.
|
|
|
|
`aggs`::
|
|
(Optional, string) **experimental** An aggregation structure, serialized as a string. The field format is similar to `filter`, meaning
|
|
that to use a saved object type attribute in the aggregation, the `savedObjectType.attributes.title`: "myTitle"` format
|
|
must be used. For root fields, the syntax is `savedObjectType.rootField`
|
|
|
|
NOTE: As objects change in {kib}, the results on each page of the response also
|
|
change. Use the find API for traditional paginated results, but avoid using it to export large amounts of data.
|
|
|
|
[[saved-objects-api-find-request-codes]]
|
|
==== Response code
|
|
|
|
`200`::
|
|
Indicates a successful call.
|
|
|
|
==== Examples
|
|
|
|
Find index patterns with titles that start with `my`:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
$ curl -X GET api/saved_objects/_find?type=index-pattern&search_fields=title&search=my*
|
|
--------------------------------------------------
|
|
// KIBANA
|
|
|
|
The API returns the following:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
{
|
|
"total": 1,
|
|
"data": [
|
|
{
|
|
"id": "my-pattern",
|
|
"type": "index-pattern",
|
|
"version": 1,
|
|
"attributes": {
|
|
"title": "my-pattern-*"
|
|
}
|
|
}
|
|
]
|
|
}
|
|
--------------------------------------------------
|
|
|
|
For parameters that accept multiple values (e.g. `fields`), repeat the
|
|
query parameter for each value:
|
|
|
|
[source,sh]
|
|
--------------------------------------------------
|
|
$ curl -X GET api/saved_objects/_find?fields=id&fields=title
|
|
--------------------------------------------------
|
|
// KIBANA
|